Manipulate roles

These sections show how to create, read, update, and delete managed roles, and to grant roles to users. For information about using roles to provision users to external systems, refer to Use assignments to provision users.

Create a role

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

Using the Advanced Identity Cloud admin UI

From the navigation bar, click Identities > Manage.
On the Manage Identities page, click Realm-name - Roles > New Realm-name - Role .
On the New Role page, enter a name and description for the new role, and click Next.
Optionally, to assign users to the role based on the presence of specific attributes, enable Condition, and define the query. Then click Next.
Optionally, to allow the role to be assigned only on a temporary basis, enable An array of temporal constraints for this role, and set the Start time, End time, and Time Zone Offset. Then click Save.

For more information, refer to Grant Roles Dynamically and Use temporal constraints to restrict effective roles.

Using the IDM admin UI

On the Quick Start page, click the Manage Roles tile.
On the Realm-name - Role List page, click New Realm-name - Role.
On the New Realm-name - 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.

Using REST

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

curl \
--header "Authorization: Bearer <token>" \
--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"
}' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role?_action=create"
{
  "_id": "5790220a-719b-49ad-96a6-6571e63cbaf1",
  "_rev": "0000000079c6644f",
  "name": "employee",
  "description": "Role granted to workers on the company payroll"
}

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.

Use script hooks to configure role behavior. For more information, refer to event hooks.

List roles

Using the Advanced Identity Cloud admin UI

From the navigation bar, click Identities > Manage.
On the Manage Identities page, click Realm-name - Roles > New Realm-name - Role.

Using REST

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

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role?_queryFilter=true"
{
  "result": [
    {
      "_id": "5790220a-719b-49ad-96a6-6571e63cbaf1",
      "_rev": "0000000079c6644f",
      "name": "employee",
      "description": "Role granted to workers on the company payroll"
    }
  ],
  ...
}

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 Relationships between objects.

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.

Using the Advanced Identity Cloud admin UI

From the navigation bar, click Identities > Manage.
On the Manage Identities page, click Realm-name - Roles > New Realm-name - Role.
Click the role-name you want to assign to users.
On the role-name page, click Role Members > + Add Role Members
Enter the name of the user.
Optionally enable Assign role only during a selected time period, and specify the time interval.
Click Save.

Using the IDM admin UI

On the Quick Start page, click the Manage Roles tile.
On the Realm-name - Role List page, click Realm-name.
On the Realm-name page, click Role Members > Add Role Members.
Enter Realm-name in the Role Members field.
Optionally, to restrict the role grant to a set time period, enable Temporal Constraint, and set the Timezone Offset, Start Date, and End Date.
Click Add.

Using REST

Grant roles statically

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

Add the user as a role member.

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

The following example adds user scarter with UUID 1002e929-5605-4a31-865d-ee0a16df6e3a as a member of the role (5790220a-719b-49ad-96a6-6571e63cbaf1):

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "_ref":"managed/realm-name_user/<scarterUUID>",
  "_refProperties":{}
}' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role/5790220a-719b-49ad-96a6-6571e63cbaf1/members?_action=create"
{
  "_id": "4c32ae53-abed-45f8-bc84-c367e2b0e194",
  "_rev": "5b65b2b8-4955-461b-8532-d763426fc058-5396",
  "_ref": "managed/realm-name_user/1002e929-5605-4a31-865d-ee0a16df6e3a",
  "_refResourceCollection": "managed/realm-name_user",
  "_refResourceId": "<scarterUUID>",
  "_refProperties": {
    "_id": "4c32ae53-abed-45f8-bc84-c367e2b0e194",
    "_rev": "5b65b2b8-4955-461b-8532-d763426fc058-5396"
  }
}

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 "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[
  {
    "operation": "add",
    "field": "/roles/-",
    "value": {"_ref" : "managed/realm-name_role/5790220a-719b-49ad-96a6-6571e63cbaf1"}
  }
]' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user/<scarterUUID>"
{
  "_id": "<scarterUUID>",
  "_rev": "000000003be825ce",
  "mail": "scarter@example.com",
  "givenName": "Steven",
  "sn": "Carter",
  "description": "Created By CSV",
  "userName": "scarter",
  "telephoneNumber": "1234567",
  "accountStatus": "active",
  "effectiveRoles": [
      {
        "_ref": "managed/realm-name_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.

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 "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PATCH \
--data '{
    "operation": "add",
    "field": "/members/-",
    "value": {"_ref" : "managed/realm-name_user/<scarterUUID>"}
  }' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_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 "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role/5790220a-719b-49ad-96a6-6571e63cbaf1?_fields=*_ref,name"
{
  "_id": "5790220a-719b-49ad-96a6-6571e63cbaf1",
  "_rev": "0000000079c6644f",
  "name": "employee",
  "assignments": [],
  "members": [
    {
      "_ref": "managed/realm-name_user/<scarterUUID>",
      "_refResourceCollection": "managed/realm-name_user",
      "_refResourceId": "<scarterUUID>",
      "_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 scarter’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 "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PATCH \
--data '[
  {
    "operation": "replace",
    "field": "/roles",
    "value": [
      {"_ref":"managed/realm-name_role/5790220a-719b-49ad-96a6-6571e63cbaf1"}
    ]
  }
]' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user/<scarterUUID>"
{
  "_id": "<scarterUUID>",
  "_rev": "00000000da112702",
  "mail": "scarter@example.com",
  "givenName": "Steven",
  "sn": "Carter",
  "description": "Created By CSV",
  "userName": "scarter",
  "telephoneNumber": "1234567",
  "accountStatus": "active",
  "effectiveRoles": [
    {
      "_ref": "managed/realm-name_role/5790220a-719b-49ad-96a6-6571e63cbaf1"
    }
  ],
  "effectiveAssignments": []
}

Grant roles dynamically

Grant a role dynamically by 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 conditional role

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.

To set up a condition for a role by using the Advanced Identity Cloud admin UI, select Settings node on the role [.var]#Role-nmae page, then define the query filter that will be used to assess the condition.

To set up a condition for a role by using the IDM admin UI, select Condition on the role Details page, then define the query filter that will be used to assess the condition.

To set up a condition for a 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 to users whose country property is set to FR:

curl \
--header "Authorization: Bearer <token>" \
--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\""
}' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_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 condition is enabled for a role, IDM automatically assesses all managed users. It recalculates the value of the roles property for users who 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 condition 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

Using the Advanced Identity Cloud admin UI

From the navigation bar, click Identities > Manage.
On the Manage Identities page, click Realm name - Users.
Click the User name you want to check the roles.
On the User name page, click Provisioning Roles.

Using the IDM admin UI

You can verify the dynamic and static roles granted to a user from the user’s entry in the IDM admin UI:

On the Quick Start page, select Manage Users, then select User name.
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.

Using REST

Query user’s roles property to get the roles granted to the user. The following example shows that scarter has been granted two roles—an employee role, and an fr-employee role:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user/<scarterUUID>/roles?_queryFilter=true&_fields=_ref/*,name"
{
  "result": [
    {
      "_id": "5a023862-654d-4d7f-b9d0-7c151b8dede5",
      "_rev": "00000000baa999c1",
      "_refResourceCollection": "managed/realm-name_role",
      "_refResourceId": "b8783543-869a-4bd4-907e-9c1d89f826ae",
      "_refResourceRev": "0000000027a959cf",
      "name": "employee",
      "_ref": "managed/realm-name_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/realm-name_role",
      "_refResourceId": "01ee6191-75d8-4d4b-9291-13a46592c57a",
      "_refResourceRev": "000000000cb0794d",
      "name": "fr-employee",
      "_ref": "managed/realm-name_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 "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user/<scarterUUID>?_fields=effectiveRoles"

Remove 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.

Using the Advanced Identity Cloud admin UI

From the navigation bar, click Identities > Manage.
On the Manage Identities page, click Realm name - Roles.
Click the Role name that you want to delete membership.
Select the users you want to remove from this role and click Remove.
On the Confirm Removal page, click Remove.

Using the IDM admin UI

Method 1 (If you want to remove multiple roles from a user):

On the Quick Start page, select Manage Users, and select the user whose roles you want to remove.
Select the Provisioning Roles tab, select the roles that you want to remove, then select Remove Selected Provisioning Roles.

Method 2 (If you want to remove a role from multiple users):

On the Quick Start page, select Manage Roles, 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.

Using REST

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

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 "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user/<scarterUUID>/roles/5a023862-654d-4d7f-b9d0-7c151b8dede5"
{
  "_id": "5a023862-654d-4d7f-b9d0-7c151b8dede5",
  "_rev": "00000000baa999c1",
  "_ref": "managed/realm-name_role/b8783543-869a-4bd4-907e-9c1d89f826ae",
  "_refResourceCollection": "managed/realm-name_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 entire object in the value, as shown in the following example:

curl \
--header "Content-type: application/json" \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request PATCH \
--data '[
  {
    "operation" : "remove",
    "field" : "/roles",
    "value" : {
      "_ref": "managed/realm-name_role/b8783543-869a-4bd4-907e-9c1d89f826ae",
      "_refResourceCollection": "managed/realm-name_role",
      "_refResourceId": "b8783543-869a-4bd4-907e-9c1d89f826ae",
      "_refProperties": {
        "_id": "5a023862-654d-4d7f-b9d0-7c151b8dede5",
        "_rev": "00000000baa999c1"
      }
    }
  }
]' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user/<scarterUUID>"
{
  "_id": "<scarterUUID>",
  "_rev": "000000007b78257d",
  "mail": "scarter@example.com",
  "givenName": "Steven",
  "sn": "Carter",
  "description": "Created By CSV",
  "userName": "scarter",
  "telephoneNumber": "1234567",
  "accountStatus": "active",
  "effectiveRoles": [
    {
      "_ref": "managed/realm-name_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 bjensen’s membership from that role:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role/b8783543-869a-4bd4-907e-9c1d89f826ae/members?_queryFilter=true"
{
  "result": [
    {
      "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72",
      "_rev": "00000000c25d994a",
      "_ref": "managed/realm-name_user/bjensen",
      "_refResourceCollection": "managed/realm-name_user",
      "_refResourceId": "bjensen",
      "_refProperties": {
        "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72",
        "_rev": "00000000c25d994a"
      }
    }
  ],
  ...
}

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role/b8783543-869a-4bd4-907e-9c1d89f826ae/members/a5a4bf94-6425-4458-aae4-bbd6ad094f72"
{
  "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72",
  "_rev": "00000000c25d994a",
  "_ref": "managed/realm-name_user/bjensen",
  "_refResourceCollection": "managed/realm-name_user",
  "_refResourceId": "bjensen",
  "_refProperties": {
    "_id": "a5a4bf94-6425-4458-aae4-bbd6ad094f72",
    "_rev": "00000000c25d994a"
  }
}

Delete a role definition

To delete a role over the REST interface, delete that managed object.

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 by using the IDM admin UI), IDM returns an error.

Using the Advanced Identity Cloud admin UI

From the navigation bar, click Identities > Manage.
On the Manage Identities page, click Realm name - Roles.
Click the Role name you want to delete.
Click Delete Realm name - Role.
On the Delete Realm name - Role page, click Delete.

Using the IDM admin UI

On the Quick Start page, select Manage Roles.
Select the roles you want to remove and click Delete Selected.

Using REST

The following example deletes the employee role created in the previous section:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role/b8783543-869a-4bd4-907e-9c1d89f826ae"
{
  "_id": "b8783543-869a-4bd4-907e-9c1d89f826ae",
  "_rev": "0000000027a959cf",
  "privileges": [],
  "name": "employee",
  "description": "All employees"
}

The following example attempts to remove a role that is still granted to a user, and receives an error message:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_role/01ee6191-75d8-4d4b-9291-13a46592c57a"
{
  "code": 409,
  "reason": "Conflict",
  "message": "Cannot delete a role that is currently granted"
}

PingOne Advanced Identity Cloud

Manipulate roles

Create a role

Using the Advanced Identity Cloud admin UI

Using the IDM admin UI

Using REST

List roles

Using the Advanced Identity Cloud admin UI

Using REST

Grant roles to a user

Using the Advanced Identity Cloud admin UI

Using the IDM admin UI

Using REST

Grant roles statically

Grant roles dynamically

Grant a conditional role

Query a user’s roles

Using the Advanced Identity Cloud admin UI

Using the IDM admin UI

Using REST

Remove a user’s roles

Using the Advanced Identity Cloud admin UI

Using the IDM admin UI

Using REST

Delete a role definition

Using the Advanced Identity Cloud admin UI

Using the IDM admin UI

Using REST