PermissionsClient

Constructor

new PermissionsClient(
client,
options // optional
)

The PermissionsClient is intended to make it easy to setup and maintain permission policies in the fabric.

Item Policies:

An item policy is the full specification of the policy for an object. It consists of a set of available profiles and a list of permissions.
The item policy must be initialized using CreateItemPolicy before the other modification methods in this client can be used.
The item policy can be retrieved using the ItemPolicy method to check if the policy for a particular item has been initialized.

Dates:

start and end can be specified in several places in the policy. These can be provided in any format supported by JavaScript's new Date(date) constructor, such as Unix epoch timestamps or ISO timestamps.
Permissions, profiles and custom profile permissions may have start and end times. The effective allowed access is the most restrictive combination of applicable start and end times.

Subjects:

A subject is a recipient of a permission - namely Fabric and oauth users and groups.
When specifying a subject, both the name and ID must be provided. For Fabric users, the ID is either the user or group address, or the igrp/iusr hash format of the address.

Items:

An 'item' in this API is a content object to which permissions are granted. All profiles and permissions are on a per-item basis.

Profiles:

Profiles represent a set of permissions that can be applied to a subject (via a 'permission', see below)
A profile may have start and end times
A profile includes permission specifications for both the assets and the offerings of an item. Both must be specified when creating or modifying a profile.
For both assets and offerings, there is a default_permission entry, which can be either full-access or no-access. This represents the access allowed to the assets and offerings when a permission for the profile is granted, excepting any custom permissions that override it.
For both assets and offerings, a profile may have a custom_permissions section, which specifies permissions for specific assets or offerings. These permissions must have a permission entry which is either full-access or no-access, and may have start and end times.

Example Profile Specification:

   "pre-release": {
      "start": "2020-12-10T08:00:00.000Z",
      "end": "2020-12-31T08:00:00.000Z",
      "assets": {
        "custom_permissions": {
          "2wLgQXV5VYvRPZlOEPN0.tif": {
            "start": "2020-09-10T07:00:00.000Z",
            "end": "2020-12-31T08:00:00.000Z",
            "permission": "full-access"
          },
          "781rsItfv8UxrkYgSNhb.tif": {
            "start": "2020-09-10T07:00:00.000Z",
            "end": "2020-12-31T08:00:00.000Z",
            "permission": "full-access"
          },
          "QCVtsOAcUKbA8svZeFRI.tif": {
            "permission": "full-access"
          },
          "QXWQVA7FfUwLlEPlBI1G.tif": {
            "permission": "full-access",
            "start": "2020-09-30T07:00:00.000Z"
          }
        },
        "default_permission": "no-access"
      },
      "offerings": {
        "default_permission": "no-access"
      }
    }

Permissions:

A permission represents a grant of an item profile's permissions to a subject.
A permission must have a profile that is present in the item's policy
A permission may have start and end times. As mentioned above, the effective start and end times of a permission are the most restrictive of all applicable start and end times.
A permission must have a subject, which can be either a user or group, either from the Fabric or from an OAuth provider, or an NTP instance or an NTP Subject
A subject must have an ID and a name. In the case of certain OAuth providers, the name may be used as an ID in most cases, but the immutable ID for that subject must be used as the ID. For example, in Okta, a group may be specified by its name "Content Admins", but have the Okta ID "00g102tklfAorixGi4x7". The former should be used as the subjectName, and the latter as the subjectId

Example Permission:

   {
      "start": "2021-01-01T08:00:00.000Z",
      "end": "2021-03-31T07:00:00.000Z",
      "profileName": "servicing",
      "subjectSource": "oauth",
      "subjectType": "group",
      "subjectName": "Partner1",
      "subjectId: "00g102uednmwrTihN4x7"
    }

Parameters

Name Type Required Description

Name	Type	Required	Description
`client`		✓	An instance of ElvClient
`options`	`object`		false} - Options for the PermissionsClient offline - If specified, metadata reads and updates will be done with a local copy. Use OpenOfflineDraft and CloseOfflineDraft (default: `{offline:`)

client

✓

An instance of ElvClient

options

object

false} - Options for the PermissionsClient

offline - If specified, metadata reads and updates will be done with a local copy. Use OpenOfflineDraft and CloseOfflineDraft

(default: {offline:)

CloseOfflineDraft

CloseOfflineDraft({ policyId })

Close an offline draft - copies the metadata stored locally back to the write token's metadata. Does not finalize the write token.

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy

CreateItemPolicy

CreateItemPolicy({
  policyId,
  policyWriteToken,
  itemId,
  profiles // optional
})

Initialize policy for the specified item

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`	✓	Write token for the policy
`itemId`	`string`	✓	Object ID of the item
`profiles`	`object`		Profiles to create (default: `{}`)

ItemPermissions

ItemPermissions({
  policyId,
  policyWriteToken, // optional
  itemId
}) → Promise.<Array>

Retrieve the permissions for the specified item policy

Returns: The list of permissions for the specified item

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`		Write token for the policy object - if specified, info will be retrieved from the write draft instead of the last finalized policy object
`itemId`	`string`	✓	Object ID of the item

ItemPolicy

ItemPolicy({
  policyId,
  policyWriteToken, // optional
  itemId
}) → Promise.<(Object|undefined)>

Retrieve the full item policy for the given item.

Returns: The policy for the specified item. If none exists, returns undefined

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`		Write token for the policy object - if specified, info will be retrieved from the write draft instead of the last finalized policy object
`itemId`	`string`	✓	Object ID of the item

ItemProfiles

ItemProfiles({
  policyId,
  policyWriteToken, // optional
  itemId,
  profileName // optional
})

Retrieve profile information on the specified item policy

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`		Write token for the policy object - if specified, info will be retrieved from the write draft instead of the last finalized policy object
`itemId`	`string`	✓	Object ID of the item
`profileName`	`string`		The name of the profile. If not specified, all profiles will be returned

OpenOfflineDraft

OpenOfflineDraft({
  policyId,
  policyLibraryId,
  policyWriteToken // optional
})

Open an offline draft - copies object data locally and allows the functions processing this data to operate on the local copy, much faster. Closing the draft will copy the data back to the object's write token.

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyLibraryId`	`string`	✓	Policy object library ID (optional)
`policyWriteToken`	`string`		Write token for the policy object

PolicyItems

PolicyItems({
policyId,
policyWriteToken // optional
}) → Promise.<Object>

Retrieve a list of all items in the specified policy

Returns: A mapping of item objectId to the display name of the item

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`		Write token for the policy object - if specified, info will be retrieved from the write draft instead of the last finalized policy object

RemoveItemPolicy

RemoveItemPolicy({
  policyId,
  policyWriteToken,
  itemId
})

Remove the specified item policy

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`	✓	Write token for the policy
`itemId`	`string`	✓	Object ID of the item

RemovePermission

RemovePermission({
  policyId,
  policyWriteToken,
  itemId,
  subjectId
})

Remove permission for the specified subject from the specified item policy

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`	✓	Write token for the policy
`itemId`	`string`	✓	Object ID of the item
`subjectId`	`string`	✓	The ID of the subject

RemoveProfile

RemoveProfile({
  policyId,
  policyWriteToken,
  itemId,
  profileName,
  profileSpec
})

Remove a profile from the specified item policy

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`	✓	Write token for the policy
`itemId`	`string`	✓	Object ID of the item
`profileName`	`string`	✓	The name of the profile
`profileSpec`	`object`	✓	Specification for the profile. If not provided, profile will default to no access for both assets and offerings

RemoveSubjectPermissions

RemoveSubjectPermissions({
  policyId,
  policyWriteToken,
  subjectId
})

Remove all permissions for the specified subject.

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`	✓	Write token for the policy
`subjectId`	`string`	✓	The ID of the subject

SetPermission

SetPermission({
  policyId,
  policyWriteToken,
  itemId,
  subjectSource,
  subjectType,
  subjectName, // optional
  subjectId,
  subjectNTPId, // optional
  profileName,
  start,
  end
})

Add or modify permission for the specified subject to the specified item policy

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`	✓	Write token for the policy
`itemId`	`string`	✓	Object ID of the item
`subjectSource`	`string`	✓	("fabric" \| "oauth") - The source of the subject (default: `"fabric"`)
`subjectType`	`string`	✓	("user" \| "group" \| "ntp" \| "ntp_subject") - The type of the subject (default: `"group`)
`subjectName`	`string`		The name of the subject
`subjectId`	`string`	✓	The ID of the subject
`subjectNTPId`	`string`		(For subjectType "ntp_subject") The NTP ID associated with the subject
`profileName`	`string`	✓	The profile to apply for the permission
`start`	`string` \| `number`	✓	The start time for the permission
`end`	`string` \| `number`	✓	The end time for the permission

SetProfile

SetProfile({
  policyId,
  policyWriteToken,
  itemId,
  profileName,
  profileSpec
})

Create or modify a profile for the specified item policy

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`	✓	Write token for the policy
`itemId`	`string`	✓	Object ID of the item
`profileName`	`string`	✓	The name of the profile
`profileSpec`	`object`	✓	Specification for the profile. If not provided, profile will default to no access for both assets and offerings

SubjectPermissions

SubjectPermissions({
  policyId,
  policyWriteToken, // optional
  subjectId
}) → Object

Retrieve all permissions for the specified subject.

Returns: All permissions pertaining to the given subject. Format of result for each item is identical to the format of ItemPolicy

Parameters

Name	Type	Required	Description
`policyId`	`string`	✓	Object ID of the policy
`policyWriteToken`	`string`		Write token for the policy object - if specified, info will be retrieved from the write draft instead of the last finalized policy object
`subjectId`	`string`	✓	The ID of the subject

Constructor​

CloseOfflineDraft​

CreateItemPolicy​

ItemPermissions​

ItemPolicy​

ItemProfiles​

OpenOfflineDraft​

PolicyItems​

RemoveItemPolicy​

RemovePermission​

RemoveProfile​

RemoveSubjectPermissions​

SetPermission​

SetProfile​

SubjectPermissions​

Constructor

CloseOfflineDraft

CreateItemPolicy

ItemPermissions

ItemPolicy

ItemProfiles

OpenOfflineDraft

PolicyItems

RemoveItemPolicy

RemovePermission

RemoveProfile

RemoveSubjectPermissions

SetPermission

SetProfile

SubjectPermissions