Create Privileges

Privileges are assigned to internal roles. A privilege specifies the following information:

The service path to which users with that internal role have access.
The methods and actions allowed on that service path.
The specific attributes of the objects at that service path, to which access is allowed.

You can use a query filter within a privilege so that the privilege applies to only a subset of managed objects.

The privileges property is an array, and can contain multiple privileges. Each privilege can contain:

accessFlags

A list of attributes within a managed object that you wish to give access to. Each attribute has two fields:

attribute—the name of the property you are granting access to.
readOnly (boolean)—determines what level of access is allowed.

Attributes marked as "readOnly": true can be viewed but not edited. Attributes marked as "readOnly": false can be both viewed and edited. Attributes that are not listed in the accessFlags array cannot be viewed or edited.

Note

Privileges are not automatically aware of changes to the managed object schema. If new properties are added, removed, or made mandatory, you must update any existing privileges to account for these changes. When a new property is added, it has a default permission level of NONE in existing privileges, including when the privilege is set to access all attributes.
IDM applies policy validation when creating or updating a privilege, to ensure that all required properties are writable when the CREATE permission is assigned. This validation does not run when schema changes are made, however, so you must verify that any existing privileges adhere to defined policies.

actions

A list of the specific actions allowed if the ACTION permission has been specified. Allowed actions must be explicitly listed.

description (optional)

A description of the privilege.

filter (optional)

This property lets you apply a static or dynamic query filter to the privilege, which can be used to limit the scope of what the privilege allows the user to access.

Static Filter Example

To allow a delegated administrator to access information only about users for the stateProvince Washington, include a static filter such as:

filter : "stateProvince eq \"Washington\""

Dynamic Filter Example

Dynamic filters insert values from the authenticated resource. To allow a delegated administrator to access information only about users in their own stateProvince, include a dynamic filter by wrapping the parameter in curly braces:

filter : "stateProvince eq \"{{stateProvince}}\""

Users with query filter privileges cannot edit the properties specified in the filter in ways that would cause the privilege to lose access to the object. For example, if a user with either of the preceding example privileges attempted to edit another user's stateProvince field to anything not matching the query filter, the request would return a 403 Forbidden error.

Note

Fields must be searchable by IDM to be used in a privilege filter. Make sure that the field you are filtering on has "searchable" : true set in repo.jdbc.json. This is not necessary if you are using a DS or a PostgreSQL repository.

Privilege filters are another layer of filter in addition to any other query filters you create. This means any output must satisfy all filters to be included.

name

The name of the privilege being created.

path

The path to the service you want to allow members of this privilege to access. For example, managed/user.

permissions

A list of permissions this privilege allows for the given path. The following permissions are available:

VIEW—allows reading and querying the path, such as viewing and querying managed users.
CREATE—allows creation at the path, such as creating new managed users.
UPDATE—allows updating or patching existing information, such as editing managed user details.
DELETE—allows deletion, such as deleting users from managed/user.
ACTION—allows users to perform actions at the given path, such as custom scripted actions.
Note
Actions that require additional filtering on the results of the action are not currently supported.

Adding Privileges Using the Admin UI

The easiest way to modify privileges is using the Admin UI.

From the navigation bar, click Manage > Role.
From the Roles page, click the Internal tab, and then click an existing role (or create a new role).
From the Role Name page, click the Privileges tab.
IDM displays the current privileges for the role.
To add privileges, click Add Privileges.
- In the Add a privilege window, enter information, as necessary, and click Add.

Adding Privileges Using REST

The following example creates a new support role with privileges that let members view, create, and update information about users, but not delete users:

curl \
--header "X-OpenIDM-UserName: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--cacert ca-cert.pem \
--request PUT \
--data '{
  "name": "support",
  "description": "Support Role",
  "privileges": [ {
    "name": "support",
    "description": "Support access to user information.",
    "path": "managed/user",
    "permissions": [
      "VIEW", "UPDATE", "CREATE"
    ],
    "actions": [],
    "filter": null,
    "accessFlags": [
      {
        "attribute" : "userName",
        "readOnly" : false
      },
      {
        "attribute" : "mail",
        "readOnly" : false
      },
      {
        "attribute" : "givenName",
        "readOnly" : false
      },
      {
        "attribute" : "sn",
        "readOnly" : false
      },
      {
        "attribute" : "accountStatus",
        "readOnly" : true
      }
    ]
  } ]
}' \
"https://localhost:8443/openidm/internal/role/support"
{
  "_id": "support",
  "_rev": "00000000bfbac2ed",
  "name": "support",
  "description": "Support Role",
  "temporalConstraints": [],
  "condition": null,
  "privileges": [
    {
      "name": "support",
      "description": "Support access to user information.",
      "path": "managed/user",
      "permissions": [
        "VIEW",
        "UPDATE",
        "CREATE"
      ],
      "actions": [],
      "filter": null,
      "accessFlags": [
        {
          "attribute": "userName",
          "readOnly": false
        },
        {
          "attribute": "mail",
          "readOnly": false
        },
        {
          "attribute": "givenName",
          "readOnly": false
        },
        {
          "attribute": "sn",
          "readOnly": false
        },
        {
          "attribute": "accountStatus",
          "readOnly": true
        }
      ]
    }
  ]
}

Policies Related to Privileges

When creating privileges, IDM runs policies found in policy.json and policy.js, including the five policies used for validating privileges:

valid-accessFlags-object

Verifies that accessFlag objects are correctly formatted. Only two fields are permitted in an accessFlag object: readOnly, which must be a boolean; and attribute, which must be a string.

valid-array-items

Verifies that each item in an array contains the properties specified in policy.json, and that each of those properties satisfies any specific policies applied to it. By default, this is used to verify that each privilege contains name, path, accessFlags, actions, and permissions properties, and that the filter property is valid if included.

valid-permissions

Verifies that the permissions set on the privilege are all valid and can be achieved with the accessFlags that have been set. It checks:

CREATE permissions must have write access to all properties required to create a new object.
CREATE and UPDATE permissions must have write access to at least one property.
ACTION permissions must include a list of allowed actions, with at least one action included.
If any attributes have write access, then the privilege must also have either CREATE or UPDATE permission.
All permissions listed must be valid types of permission: VIEW, CREATE, UPDATE, ACTION, or DELETE. Also, no permissions are repeated.

valid-privilege-path

Verifies that the path specified in the privilege is a valid object with a schema for IDM to reference. Only objects with a schema (such as managed/user) can have privileges applied.

valid-query-filter

Verifies that the query filter used to filter privileges is a valid query.

For more information about policies and creating custom policies, see Use Policies to Validate Data.