--- title: Manipulate roles description: Create, list, grant, query, and delete PingIDM managed roles over REST or the admin UI, including static, dynamic, and conditional role grants component: pingidm version: 8.1 page_id: pingidm:objects-guide:roles-over-rest canonical_url: https://docs.pingidentity.com/pingidm/8.1/objects-guide/roles-over-rest.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Data Object Model", "Roles", "Assignments"] section_ids: create-new-role: Create a role using_the_platform_admin_ui: Using the Platform admin UI using_the_legacy_admin_ui: Using the legacy admin UI using_rest: Using REST list-existing-roles: List roles granting-role-user: Grant roles to a user to-grant-roles-statically: Grant roles statically using_rest_2: Using REST using_the_platform_admin_ui_2: Using the Platform admin UI using_the_legacy_admin_ui_2: Using the legacy admin UI to-grant-roles-dynamically: Grant roles dynamically conditional-role-grants: Grant a role based on a condition querying-user-roles: Query a user's roles delete-role-user: Delete a user's roles over_rest: Over REST using_the_platform_admin_ui_3: Using the Platform admin UI using_the_legacy_admin_ui_3: Using the legacy admin UI delete-role-definition: Delete a role definition --- # 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](working-with-role-assignments.html). You can create, query, update, and delete managed roles using the: * Platform admin UI Available at [icon: people, set=material, size=inline] Identities > Manage, and click the [icon: assignment_ind, set=material, size=inline] 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](../release-notes/deprecated-functionality.html#legacy-admin-ui-deprecated) and is no longer bundled with IDM. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI.Both UIs are available as separate downloads from the [Backstage download site](https://backstage.pingidentity.com/downloads):- To install the Platform admin UI, follow the steps in [Install the Platform admin UI for standalone IDM](../setup-guide/platform-admin-ui.html). - To continue using the legacy admin UI, follow the steps in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). | ### Using the Platform admin UI 1. From the sidebar, click [icon: people, set=material, size=inline] Identities > Manage, then select the [icon: assignment_ind, set=material, size=inline] Roles tab. 2. Click [icon: plus, set=fas]New Role, enter a Name and Description, and click Next. 3. 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](#to-grant-roles-dynamically). 4. 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](roles-temporal-constraints.html). 5. 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 1. From the navigation bar, click Manage > Role. 2. On the Roles page, click New Role. 3. On the New Role page, enter a name and description, and click Save. 4. 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](roles-temporal-constraints.html) and [Grant roles dynamically](#to-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 *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*. | 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](working-with-role-assignments.html). ## 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 [icon: people, set=material, size=inline] Identities > Manage, and select the [icon: assignment_ind, set=material, size=inline] 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](relationships.html). 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](effective-roles-and-assignments.html). 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](../crest/crest-patch.html#crest-patch-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](../release-notes/deprecated-functionality.html#legacy-admin-ui-deprecated) and is no longer bundled with IDM. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI.Both UIs are available as separate downloads from the [Backstage download site](https://backstage.pingidentity.com/downloads):* To install the Platform admin UI, follow the steps in [Install the Platform admin UI for standalone IDM](../setup-guide/platform-admin-ui.html). * To continue using the legacy admin UI, follow the steps in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). | #### 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 1. Go to [icon: people, set=material, size=inline] Identities > Manage, select the [icon: people, set=material, size=inline] Users tab, and select the user to whom you want to grant the role. 2. Select the Provisioning Roles tab, and click [icon: plus, set=fas]Add Provisioning Roles. 3. Select the role from the Provisioning Roles list, and click Save. * Update the role entry 1. Go to [icon: people, set=material, size=inline] Identities > Manage, select the [icon: assignment_ind, set=material, size=inline] Roles tab, and select the role that you want to grant. 2. Select the Role Members tab, and click [icon: plus, set=fas]Add Role Members. 3. 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 1. Select Manage > User, and select the user to whom you want to grant the role. 2. Select the Provisioning Roles tab, and select Add Provisioning Roles. 3. Select the role from the list, and select Add. * Update the role entry 1. Select Manage > Role, and select the role that you want to grant. 2. Select the Role Members tab, and select Add Role Members. 3. 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 *(tooltip: You can edit the managed object configuration over REST at the config/managed endpoint, or directly in the conf/managed.json file.)*. For more information, refer to [Create and modify object types](creating-modifying-managed-objects.html). | 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: 1. Go to [icon: people, set=material, size=inline] Identities > Manage, select the [icon: people, set=material, size=inline] Users tab, then select the user whose roles you want to see. 2. Select the Provisioning Roles tab. In the legacy admin UI: 1. Select Manage > User, then select the user whose roles you want to see. 2. Select the Provisioning Roles tab. 3. 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](#remove-roles-delete-method) to remove the role from the user's role property or a [PATCH request](#remove-roles-patch-method) 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](../release-notes/deprecated-functionality.html#legacy-admin-ui-deprecated) and is no longer bundled with IDM. New deployments should use the [Platform admin UI](../setup-guide/platform-admin-ui.html), which is the replacement for the legacy admin UI.Both UIs are available as separate downloads from the [Backstage download site](https://backstage.pingidentity.com/downloads):- To install the Platform admin UI, follow the steps in [Install the Platform admin UI for standalone IDM](../setup-guide/platform-admin-ui.html). - To continue using the legacy admin UI, follow the steps in [Install the legacy admin UI](../setup-guide/legacy-admin-ui.html). | ### Using the Platform admin UI Use one of the following methods to remove a user's roles in the Platform admin UI: Method 1: 1. Go to [icon: people, set=material, size=inline] Identities > Manage, select the [icon: people, set=material, size=inline] Users tab, and select the user whose roles you want to remove. 2. Select the Provisioning Roles tab, select the checkbox next to the role that you want to remove, then click Remove. Method 2: 1. Go to [icon: people, set=material, size=inline] Identities > Manage, select the [icon: assignment_ind, set=material, size=inline] Roles tab, and select the role whose members you want to remove. 2. 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: 1. Select Manage > User, and select the user whose roles you want to remove. 2. Select the Provisioning Roles tab, select the role that you want to remove, then select Remove Selected Provisioning Roles. Method 2: 1. Select Manage > Role, and select the role whose members you want to remove. 2. 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 [icon: people, set=material, size=inline] Identities > Manage, select the [icon: assignment_ind, set=material, size=inline] 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.