Manipulate roles

This topic shows how to create, read, update, and delete managed roles, and grant roles to users. For information about using roles to provision users to external systems, refer to Use assignments to provision users.

You can create, query, update, and delete managed roles using the:

Platform admin UI: Available at people Identities > Manage, and click the assignment_ind Roles tab
Legacy admin UI (deprecated): Available at Manage > Role
REST interface: Available at /openidm/managed/role

Create a role

Starting with IDM 8.1, the legacy admin UI is deprecated and is no longer bundled with IDM. New deployments should use the Platform admin UI, which is the replacement for the legacy admin UI.

Both UIs are available as separate downloads from the Backstage download site:

To install the Platform admin UI, follow the steps in Install the Platform admin UI for standalone IDM.
To continue using the legacy admin UI, follow the steps in Install the legacy admin UI.

Using the Platform admin UI

From the sidebar, click people Identities > Manage, then select the assignment_ind Roles tab.
Click New Role, enter a Name and Description, and click Next.
Optionally, on the Dynamic Role Assignment step, enable A conditional filter for this role to define a query filter that dynamically grants the role to members, then click Next.

For more information, refer to Grant roles dynamically.
Optionally, on the Time Constraint step, enable An array of temporal constraints for a role to restrict the role grant to a set time period, and set the Start and End date and time, and the Time Zone Offset.

For more information, refer to Use temporal constraints to restrict effective roles.
Click Save.

To change the Condition or Temporal Constraints of a role after you create it, go to the role’s Settings tab.

Using the legacy admin UI

From the navigation bar, click Manage > Role.
On the Roles page, click New Role.
On the New Role page, enter a name and description, and click Save.
Optionally, do any of the following, and click Save:
- To restrict the role grant to a set time period, enable Temporal Constraint, and set the Timezone Offset, Start Date, and End Date.
- To define a query filter that dynamically grants the role to members, enable Condition, and define the query.
For more information, refer to Use temporal constraints to restrict effective roles and Grant roles dynamically.

Using REST

To create a role, send a PUT or POST request to the /openidm/managed/role context path. The following example creates a managed role named employee:

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" \
--request POST \
--data '{
  "name": "employee",
  "description": "Role granted to workers on the company payroll"
}' \
"http://localhost:8080/openidm/managed/role?_action=create"
{
  "_id": "5790220a-719b-49ad-96a6-6571e63cbaf1",
  "_rev": "0000000079c6644f",
  "name": "employee",
  "description": "Role granted to workers on the company payroll"
}

By default, the role name must be unique. To change this behavior, adjust the policy validation on the role property in your managed object configuration.

This employee role has no corresponding assignments. Assignments are what enables the provisioning logic to the external system. Assignments are created and maintained as separate managed objects, and are referred to within role definitions. For more information about assignments, refer to Use assignments to provision users.

List roles

To list all managed roles over REST, query the openidm/managed/role endpoint. The following example shows the employee role that you created in the previous example:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/role?_queryFilter=true"
{
  "result": [
    {
      "_id": "5790220a-719b-49ad-96a6-6571e63cbaf1",
      "_rev": "0000000079c6644f",
      "name": "employee",
      "description": "Role granted to workers on the company payroll"
    }
  ],
  ...
}

To display all configured managed roles in the Platform admin UI, go to people Identities > Manage, and select the assignment_ind Roles tab. In the legacy admin UI, select Manage > Role. You can use the search bar to display only the roles you want.

Grant roles to a user

You grant roles to users through the relationship mechanism. Relationships are essentially references from one managed object to another; in this case, from a user object to a role object. For more information about relationships, refer to Configuring relationships.

You can grant roles statically or dynamically.

To grant a role statically, you must do one of the following:

Update the value of the user’s roles property to reference the role.
Update the value of the role’s members property to reference the user.

Dynamic role grants use the result of a condition or script to update a user’s list of roles.

Grant roles statically

Grant a role to a user statically using the REST interface, the Platform admin UI, or the legacy admin UI as follows:

Using REST

Use one of the following methods to grant a role to a user over REST:

Add the user as a role member. The following example adds user scarter as a member of the role (5790220a-719b-49ad-96a6-6571e63cbaf1):

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" \
--request POST \
--data '{
  "_ref":"managed/user/scarter",
  "_refProperties":{}
}' \
"http://localhost:8080/openidm/managed/role/5790220a-719b-49ad-96a6-6571e63cbaf1/members?_action=create"
{
  "_id": "4c32ae53-abed-45f8-bc84-c367e2b0e194",
  "_rev": "00000000c67a99ce",
  "_ref": "managed/user/scarter",
  "_refResourceCollection": "managed/user",
  "_refResourceId": "scarter",
  "_refProperties": {
    "_id": "4c32ae53-abed-45f8-bc84-c367e2b0e194",
    "_rev": "00000000c67a99ce"
  }
}

This preferred method does not incur an unnecessary performance cost when working with a role that contains many members.

Update the user’s roles property to refer to the role.

The following example grants the employee role (5790220a-719b-49ad-96a6-6571e63cbaf1) to user scarter:

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" \
--request PATCH \
--data '[
  {
    "operation": "add",
    "field": "/roles/-",
    "value": {"_ref" : "managed/role/5790220a-719b-49ad-96a6-6571e63cbaf1"}
  }
]' \
"http://localhost:8080/openidm/managed/user/scarter"
{
  "_id": "scarter",
  "_rev": "000000003be825ce",
  "mail": "scarter@example.com",
  "givenName": "Steven",
  "sn": "Carter",
  "description": "Created By CSV",
  "userName": "scarter",
  "telephoneNumber": "1234567",
  "accountStatus": "active",
  "effectiveRoles": [
    {
      "_ref": "managed/role/5790220a-719b-49ad-96a6-6571e63cbaf1"
    }
  ],
  "effectiveAssignments": []
}

Note that scarter’s effectiveRoles attribute has been updated with a reference to the new role. For more information about effective roles and effective assignments, refer to Effective roles and effective assignments.

When you update a user’s existing roles array, use the - special index to add the new value to the set. For more information, refer to Set semantic arrays in Patch Operation: Add.

Update the role’s members property to refer to the user.

The following sample command makes scarter a member of the employee role:

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" \
--request PATCH \
--data '[
  {
    "operation": "add",
    "field": "/members/-",
    "value": {"_ref" : "managed/user/scarter"}
  }
]' \
"http://localhost:8080/openidm/managed/role/5790220a-719b-49ad-96a6-6571e63cbaf1"
{
  "_id": "5790220a-719b-49ad-96a6-6571e63cbaf1",
  "_rev": "0000000079c6644f",
  "name": "employee",
  "description": "Role granted to workers on the company payroll"
}

The members property of a role is not returned by default in the output. To show all members of a role, you must specifically request the relationship properties (*_ref) in your query. The following example lists the members of the employee role (currently only scarter):

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/role/5790220a-719b-49ad-96a6-6571e63cbaf1?_fields=*_ref,name"
{
  "_id": "5790220a-719b-49ad-96a6-6571e63cbaf1",
  "_rev": "0000000079c6644f",
  "name": "employee",
  "assignments": [],
  "members": [
    {
      "_ref": "managed/user/scarter",
      "_refResourceCollection": "managed/user",
      "_refResourceId": "scarter",
      "_refProperties": {
        "_id": "7ad15a7b-6806-487b-900d-db569927f56d",
        "_rev": "0000000075e09cbf"
      }
    }
  ]
}

You can replace an existing role grant with a new one by using the replace operation in your patch request.

The following command replaces the scarter user’s entire roles entry (that is, overwrites any existing roles) with a single entry, the reference to the employee role (ID 5790220a-719b-49ad-96a6-6571e63cbaf1):

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" \
--request PATCH \
--data '[
  {
    "operation": "replace",
    "field": "/roles",
    "value": [
      {"_ref":"managed/role/5790220a-719b-49ad-96a6-6571e63cbaf1"}
    ]
  }
]' \
"http://localhost:8080/openidm/managed/user/scarter"
{
  "_id": "scarter",
  "_rev": "00000000da112702",
  "mail": "scarter@example.com",
  "givenName": "Steven",
  "sn": "Carter",
  "description": "Created By CSV",
  "userName": "scarter",
  "telephoneNumber": "1234567",
  "accountStatus": "active",
  "effectiveRoles": [
    {
      "_ref": "managed/role/5790220a-719b-49ad-96a6-6571e63cbaf1"
    }
  ],
  "effectiveAssignments": []
}

Starting with IDM 8.1, the legacy admin UI is deprecated and is no longer bundled with IDM. New deployments should use the Platform admin UI, which is the replacement for the legacy admin UI.

Both UIs are available as separate downloads from the Backstage download site:

To install the Platform admin UI, follow the steps in Install the Platform admin UI for standalone IDM.
To continue using the legacy admin UI, follow the steps in Install the legacy admin UI.

Using the Platform admin UI

Use one of the following methods to grant a role to a user in the Platform admin UI:

Update the user entry

Go to people Identities > Manage, select the people Users tab, and select the user to whom you want to grant the role.
Select the Provisioning Roles tab, and click Add Provisioning Roles.
Select the role from the Provisioning Roles list, and click Save.

Update the role entry

Go to people Identities > Manage, select the assignment_ind Roles tab, and select the role that you want to grant.
Select the Role Members tab, and click Add Role Members.
Select the user from the Role Members list, and click Save.

Using the legacy admin UI

Use one of the following UI methods to grant a role to a user:

Update the user entry

Select Manage > User, and select the user to whom you want to grant the role.
Select the Provisioning Roles tab, and select Add Provisioning Roles.
Select the role from the list, and select Add.

Update the role entry

Select Manage > Role, and select the role that you want to grant.
Select the Role Members tab, and select Add Role Members.
Select the user from the list, and select Add.

Grant roles dynamically

Grant a role dynamically using one of the following methods:

Use a condition, expressed as a query filter, in the role definition. If the condition is true for a particular member, that member is granted the role. Conditions can be used in both managed and internal roles.
Use a custom script to define a more complex role-granting strategy.

Grant a role based on a condition

A role that is granted based on a defined condition is called a conditional role. To create a conditional role, include a query filter in the role definition.

Properties that are used as the basis of a conditional role query must be configured as searchable and must be indexed in the repository configuration. To configure a property as searchable, update the property definition in your managed object configuration. For more information, refer to Create and modify object types.

To create a conditional role using the Platform admin UI, go to the role’s Settings tab, click Set up next to Condition, enable A conditional filter for this role, then define the query filter that will be used to assess the condition using the Any/All condition builder, or click Advanced Editor to enter a raw query filter.

To create a conditional role using the legacy admin UI, select Condition on the role Details page, then define the query filter that will be used to assess the condition.

To create a conditional role over REST, include the query filter as a value of the condition property in the role definition. The following example creates a role, fr-employee, that will be granted only to those users who live in France (whose country property is set to FR):

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" \
--request POST \
--data '{
  "name": "fr-employee",
  "description": "Role granted to employees resident in France",
  "condition": "/country eq \"FR\""
}' \
"http://localhost:8080/openidm/managed/role?_action=create"
{
  "_id": "eb18a2e2-ee1e-4cca-83fb-5708a41db94f",
  "_rev": "000000004085704c",
  "name": "fr-employee",
  "description": "Role granted to employees resident in France",
  "condition": "/country eq \"FR\""
}

When a conditional role is created or updated, IDM automatically assesses all managed users, and recalculates the value of their roles property, if they qualify for that role. When a condition is removed from a role, that is, when the role becomes an unconditional role, all conditional grants are removed. So, users who were granted the role based on the condition, have that role removed from their roles property.

When a conditional role is defined in an existing data set, every user entry (including the mapped entries on remote systems) must be updated with the assignments implied by that conditional role. The time that it takes to create a new conditional role is impacted by the following items:

The number of managed users affected by the condition.
The number of assignments related to the conditional role.
The average time required to provision updates to all remote systems affected by those assignments.

In a data set with a very large number of users, creating a new conditional role can therefore incur a significant performance cost when you create it. Ideally, you should set up your conditional roles at the beginning of your deployment to avoid performance issues later.

Query a user’s roles

To query user roles over REST, query the user’s roles property. The following example shows that scarter has been granted two roles—an employee role, and an fr-employee role:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/user/scarter/roles?_queryFilter=true&_fields=_ref/*,name"
{
  "result": [
    {
      "_id": "5a023862-654d-4d7f-b9d0-7c151b8dede5",
      "_rev": "00000000baa999c1",
      "_refResourceCollection": "managed/role",
      "_refResourceId": "b8783543-869a-4bd4-907e-9c1d89f826ae",
      "_refResourceRev": "0000000027a959cf",
      "name": "employee",
      "_ref": "managed/role/b8783543-869a-4bd4-907e-9c1d89f826ae",
      "_refProperties": {
        "_id": "5a023862-654d-4d7f-b9d0-7c151b8dede5",
        "_rev": "00000000baa999c1"
      }
    },
    {
      "_id": "b281ffdf-477e-4211-a112-84476435bab2",
      "_rev": "00000000d612a248",
      "_refResourceCollection": "managed/role",
      "_refResourceId": "01ee6191-75d8-4d4b-9291-13a46592c57a",
      "_refResourceRev": "000000000cb0794d",
      "name": "fr-employee",
      "_ref": "managed/role/01ee6191-75d8-4d4b-9291-13a46592c57a",
      "_refProperties": {
        "_grantType": "conditional",
        "_id": "b281ffdf-477e-4211-a112-84476435bab2",
        "_rev": "00000000d612a248"
      }
    }
  ],
  ...
}

Note that the fr-employee role indicates a _grantType of conditional. This property indicates how the role was granted to the user. If no _grantType is listed, the role was granted statically.

Querying a user’s roles in this way does not return any roles that would be in effect as a result of a custom script, or of any temporal constraint applied to the role. To return a complete list of all the roles in effect at a specific time, query the user’s effectiveRoles property, as follows:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/user/scarter?_fields=effectiveRoles"

Alternatively, to check which roles have been granted to a user, either statically or dynamically, look at the user’s entry in the Platform admin UI or the legacy admin UI.

In the Platform admin UI:

Go to people Identities > Manage, select the people Users tab, then select the user whose roles you want to see.
Select the Provisioning Roles tab.

In the legacy admin UI:

Select Manage > User, then select the user whose roles you want to see.
Select the Provisioning Roles tab.
If you have a large number of managed roles, use the Advanced Filter option on the Role List page to build a custom query.

Delete a user’s roles

To remove a statically granted role from a user entry, do one of the following:

Update the value of the user’s roles property to remove the reference to the role.
Update the value of the role’s members property to remove the reference to that user.

A delegated administrator must use PATCH to add or remove relationships.

Roles that have been granted as the result of a condition can only be removed when the condition is changed or removed, or when the role itself is deleted.

Over REST

To remove a role grant from a user, you can either send a DELETE request to remove the role from the user’s role property or a PATCH request to update the user entry with a new version that doesn’t include the role.

Sending a DELETE request is preferred because it explicitly identifies the relationship between user and role to be deleted. The PATCH method requires an exact match on all properties.

DELETE the role from the user’s roles property, including the reference ID (the ID of the relationship between the user and the role) in the delete request.

The following example removes the employee role from user scarter. The role ID is b8783543-869a-4bd4-907e-9c1d89f826ae, but the ID required in the DELETE request is the reference ID (5a023862-654d-4d7f-b9d0-7c151b8dede5):

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/managed/user/scarter/roles/5a023862-654d-4d7f-b9d0-7c151b8dede5"
{
  "_id": "5a023862-654d-4d7f-b9d0-7c151b8dede5",
  "_rev": "00000000baa999c1",
  "_ref": "managed/role/b8783543-869a-4bd4-907e-9c1d89f826ae",
  "_refResourceCollection": "managed/role",
  "_refResourceId": "b8783543-869a-4bd4-907e-9c1d89f826ae",
  "_refProperties": {
    "_id": "5a023862-654d-4d7f-b9d0-7c151b8dede5",
    "_rev": "00000000baa999c1"
  }
}

PATCH the user entry to remove the role from the array of roles, specifying the value of the role object in the JSON payload.

When you remove a role in this way, you must include the following four fields:

_ref
_refResourceCollection
_refResourceId
_refProperties

For example:

curl \
--header "Content-type: application/json" \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request PATCH \
--data '[
  {
    "operation" : "remove",
    "field" : "/roles",
    "value" : {
      "_ref": "managed/role/b8783543-869a-4bd4-907e-9c1d89f826ae",
      "_refResourceCollection": "managed/role",
      "_refResourceId": "b8783543-869a-4bd4-907e-9c1d89f826ae",
      "_refProperties": {
        "_id": "5a023862-654d-4d7f-b9d0-7c151b8dede5",
        "_rev": "00000000baa999c1"
      }
    }
  }
]' \
"http://localhost:8080/openidm/managed/user/scarter"
{
  "_id": "scarter",
  "_rev": "000000007b78257d",
  "mail": "scarter@example.com",
  "givenName": "Steven",
  "sn": "Carter",
  "description": "Created By CSV",
  "userName": "scarter",
  "telephoneNumber": "1234567",
  "accountStatus": "active",
  "effectiveRoles": [
    {
      "_ref": "managed/role/01ee6191-75d8-4d4b-9291-13a46592c57a"
    }
  ],
  "effectiveAssignments": [],
  "preferences": {
    "updates": false,
    "marketing": false
  },
  "country": "France"
}

DELETE the user from the role’s members property, including the reference ID (the ID of the relationship between the user and the role) in the delete request.

The following example first queries the members of the employee role, to obtain the ID of the relationship, then removes the bjensen membership from that role:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/role/b8783543-869a-4bd4-907e-9c1d89f826ae/members?_queryFilter=true"
{
  "result": [
    {
      "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72",
      "_rev": "00000000c25d994a",
      "_ref": "managed/user/bjensen",
      "_refResourceCollection": "managed/user",
      "_refResourceId": "bjensen",
      "_refProperties": {
        "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72",
        "_rev": "00000000c25d994a"
      }
    }
  ],
  ...
}

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/managed/role/b8783543-869a-4bd4-907e-9c1d89f826ae/members/a5a4bf94-6425-4458-aae4-bbd6ad094f72"
{
  "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72",
  "_rev": "00000000c25d994a",
  "_ref": "managed/user/bjensen",
  "_refResourceCollection": "managed/user",
  "_refResourceId": "bjensen",
  "_refProperties": {
    "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72",
    "_rev": "00000000c25d994a"
  }
}

Starting with IDM 8.1, the legacy admin UI is deprecated and is no longer bundled with IDM. New deployments should use the Platform admin UI, which is the replacement for the legacy admin UI.

Both UIs are available as separate downloads from the Backstage download site:

To install the Platform admin UI, follow the steps in Install the Platform admin UI for standalone IDM.
To continue using the legacy admin UI, follow the steps in Install the legacy admin UI.

Using the Platform admin UI

Use one of the following methods to remove a user’s roles in the Platform admin UI:

Method 1:

Go to people Identities > Manage, select the people Users tab, and select the user whose roles you want to remove.
Select the Provisioning Roles tab, select the checkbox next to the role that you want to remove, then click Remove.

Method 2:

Go to people Identities > Manage, select the assignment_ind Roles tab, and select the role whose members you want to remove.
Select the Role Members tab, select the checkbox next to the members that you want to remove, then click Remove.

Using the legacy admin UI

Use one of the following methods to remove a user’s roles:

Method 1:

Select Manage > User, and select the user whose roles you want to remove.
Select the Provisioning Roles tab, select the role that you want to remove, then select Remove Selected Provisioning Roles.

Method 2:

Select Manage > Role, and select the role whose members you want to remove.
Select the Role Members tab, select the members that you want to remove, then select Remove Selected Role Members.

Delete a role definition

To delete a role over the REST interface, simply delete that managed object. The following command deletes the employee role created in the previous section:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/managed/role/b8783543-869a-4bd4-907e-9c1d89f826ae"
{
  "_id": "b8783543-869a-4bd4-907e-9c1d89f826ae",
  "_rev": "0000000027a959cf",
  "privileges": [],
  "name": "employee",
  "description": "All employees"
}

You cannot delete a role that is currently granted to users. If you attempt to delete a role that is granted to a user (either over the REST interface, or using the Platform admin UI or the legacy admin UI), IDM returns an error. The following example attempts to remove a role that is still granted to a user:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/managed/role/01ee6191-75d8-4d4b-9291-13a46592c57a"
{
  "code": 409,
  "reason": "Conflict",
  "message": "Cannot delete a role that is currently granted"
}

To delete a role through the Platform admin UI, go to people Identities > Manage, select the assignment_ind Roles tab, click the role to delete, then click Delete Role.

To delete a role through the legacy admin UI, select Manage > Role, select the role you want to remove, then click Delete Selected.

PingIDM

Manipulate roles

Create a role

Using the Platform admin UI

Using the legacy admin UI

Using REST

List roles

Grant roles to a user

Grant roles statically

Using REST

Using the Platform admin UI

Using the legacy admin UI

Grant roles dynamically

Grant a role based on a condition

Query a user’s roles

Delete a user’s roles

Over REST

Using the Platform admin UI

Using the legacy admin UI

Delete a role definition