--- title: Authorization and roles description: Advanced Identity Cloud provides role-based authorization that restricts direct HTTP access to REST interface URLs. This access control applies to direct HTTP calls only. Access for internal calls (for example, calls from scripts) is not affected by this mechanism. component: pingoneaic page_id: pingoneaic:idm-auth:authorization-and-roles canonical_url: https://docs.pingidentity.com/pingoneaic/idm-auth/authorization-and-roles.html keywords: ["Authorization", "Roles", "Scripts"] section_ids: access-control-rest: Change the access configuration over REST access-config: Access configuration format granting-internal-roles: Grant internal authorization roles manually secure-openicf-access: Secure RCS access to Advanced Identity Cloud connector servers --- # Authorization and roles Advanced Identity Cloud provides role-based authorization that restricts direct HTTP access to REST interface URLs. This access control applies to direct HTTP calls only. Access for internal calls (for example, calls from scripts) is not affected by this mechanism. When a user authenticates, the user is given a set of default *roles*, as described in [Authentication and Roles](authentication-and-roles.html). The authorization configuration grants access rights to users, based on these roles acquired during authentication. You can use internal and managed roles to restrict access, with the following caveats: * Internal roles aren't meant to be provisioned or synchronized with external systems. * Internal roles can't be given assignments. * Event scripts, such as `onCreate`, can't be attached to internal roles. * The internal role schema isn't configurable. By default, managed users are assigned the `openidm-authorized` role when they authenticate. The following request shows the authorization roles for a user after they have authenticated and obtained a bearer token. Learn more in [Authentication through OAuth 2.0 and subject mappings](rsfilter-module.html). ``` curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///openidm/info/login" { "_id": "login", "authenticationId": "f7d...e9b", "authorization": { "component": "managed/realm-name_user", "roles": [ "internal/role/openidm-authorized" ], "id": "f7d...e9b" } } ``` The authorization implementation is configured in a router authorization script and the access configuration. Advanced Identity Cloud calls the router authorization for each request and checks against your access configuration to determine whether to allow HTTP requests. The `onResponse` and `relationshipFilter` filters provide additional filtering to ensure the user has the appropriate access to observe the data of the related object. Learn more in [Relationships between objects](../idm-objects/relationships.html). | | | | - | ------------------------------------------------------------------------------------------------- | | | You can configure [delegated administration](delegated-admin.html) to bypass this access control. | ## Change the access configuration over REST You can change the access configuration using the endpoint `openidm/config/access`. First, get the entire current access configuration with a GET request, then modify it as necessary, and finally, resubmit the complete, updated configuration using a PUT request. 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token). 2. Get the current access configuration: ```none curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///openidm/config/access" ``` > **Collapse: Show response** > > ```json > { > "_id": "access", > "configs": [ > { > "actions": "*", > "methods": "read", > "pattern": "info/*", > "roles": "*" > }, > { > "actions": "login,logout", > "methods": "read,action", > "pattern": "authentication", > "roles": "*" > }, > ... (1) > ] > } > ``` > > | | | > | ----- | -------------------------------------------------------------------------------------------------------------------------- | > | **1** | The response has been truncated to make the example clearer. Your response should contain the entire access configuration. | 3. Create a local copy of the access configuration from the response in step 2, then modify it. This example adds a rule that restricts access to the `info` endpoint to users who have authenticated: ```json { "_id": "access", "configs": [ { "actions": "*", "methods": "read", "pattern": "info/*", "roles": "*" }, { "actions": "login,logout", "methods": "read,action", "pattern": "authentication", "roles": "*" }, ... (1) { (2) "pattern": "info/*", "roles": "*", "methods": "read", "actions": "*" } (3) ] } ``` | | | | ----- | ---------------------------------------------------------------------------------------------- | | **1** | The example has been truncated. Your local copy should contain the whole response from step 2. | | **2** | Start of new rule. | | **3** | End of new rule. | 4. Replace the access configuration: ```none curl \ --header "Authorization: Bearer " \ --header "Content-type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --request PUT \ --data '{ "_id": "access", "configs": (1) }' \ "https:///openidm/config/access" ``` | | | | ----- | ---------------------------------------------------------------------------------------------- | | **1** | Replace \ with the array of access rules from `configs` in step 3. | > **Collapse: Show response** > > ```json > { > "_id": "access", > "configs": [ > { > "actions": "*", > "methods": "read", > "pattern": "info/*", > "roles": "*" > }, > { > "actions": "login,logout", > "methods": "read,action", > "pattern": "authentication", > "roles": "*" > }, > ... > { (1) > "pattern": "info/*", > "roles": "*", > "methods": "read", > "actions": "*" > } > ] > } > ``` > > | | | > | ----- | ----------------------------------------------- | > | **1** | The access configuration contains the new rule. | | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can also modify configuration using a PATCH request to the same endpoint.The following example appends the same configuration example in step 3 directly to the `configs` array:```none curl \ --header "Authorization: Bearer " \ --header "Content-type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --request PATCH \ --data ' [ { "operation" : "add", "field" : "/configs/-", "value" : { "pattern": "info/", "roles": "", "methods": "read", "actions": "*" } } ]' \ "https:///openidm/config/access" ``` | ## Access configuration format The access configuration includes a set of rules that govern access to specific endpoints. These rules are tested in the order they appear in the file. You can define more than one rule for the same endpoint. If one rule passes, the request is allowed. If all the rules fail, the request is denied. The following rule shows the access configuration structure: ```json { "pattern" : "system/*", "roles" : "internal/role/openidm-admin", "methods" : "action", "actions" : "test,testConfig,createconfiguration,liveSync,authenticate" } ``` This rule specifies that users with the `openidm-admin` role can perform the listed actions on all `system` endpoints. The parameters in each access rule are as follows: * `pattern` The REST endpoint for which access is being controlled. `"*"` specifies access to all endpoints in that path. For example, `"managed/realm-name_user/*"` specifies access to all managed user objects. * `roles` A comma-separated list of the roles to which this access configuration applies. The `roles` referenced here align with the object's security context (`security.authorization.roles`). The `authzRoles` relationship property of a managed user produces this security context value during authentication. * `methods` A comma-separated list of the methods that can be performed with this access. Methods can include `create, read, update, delete, patch, action, query`. A value of `"*"` indicates that all methods are allowed. A value of `""` indicates that no methods are allowed. * `actions` A comma-separated list of the allowed actions. The possible actions depend on the resource (URL) that is being exposed. Note that the `actions` in the example access file do not list all the [supported actions](../idm-scripting/scripting-func-engine.html#supported-actions) on each resource. A value of `"*"` indicates that all actions exposed for that resource are allowed. A value of `""` indicates that no actions are allowed. * `customAuthz` An optional parameter that lets you define a custom function for additional authorization checks. * `excludePatterns` An optional parameter that lets you specify endpoints to which access shouldn't be granted. ## Grant internal authorization roles manually Apart from the default roles that users get when they authenticate, you can grant internal authorization roles manually, over REST or using the IDM admin console. This mechanism works in the same way as the granting of managed roles. Learn more about granting managed roles in [Grant Roles to a User](../idm-objects/roles-over-rest.html#granting-role-user). To grant an internal role manually through the IDM admin console: 1. In the Advanced Identity Cloud admin console, click Native Consoles > Identity Management. 2. Click Manage Users and click a user. 3. On the Authorization Roles tab, click Add Authorization Roles. 4. Select Internal Role as the Type, click in the Authorization Roles field to select from the list of defined Internal Roles and click Add. To grant an internal role over REST manually, add a reference to the internal role to the user's `authzRoles` property. The following command adds the `openidm-admin` role to user bjensen with ID `9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb`: ``` curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request PATCH \ --data '[ { "operation": "add", "field": "/authzRoles/-", "value": {"_ref" : "internal/role/openidm-admin"} } ]' \ "https:///openidm/managed/realm-name_user/9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb" { "_id": "9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb", "_rev": "0000000050c62938", "mail": "bjensen@example.com", "givenName": "Barbara", "sn": "Jensen", "description": "Created By CSV", "userName": "bjensen", "telephoneNumber": "1234567", "accountStatus": "active", "effectiveRoles": [], "effectiveAssignments": [] } ``` You can also grant internal roles dynamically using [conditional role grants](../idm-objects/roles-over-rest.html#conditional-role-grants). | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Because internal roles aren't managed objects, you can't manipulate them in the same way as managed roles. You can't add a user to an internal role as you would to a managed role.To add users directly to an internal role, add the users as values of the role's `authzMembers` property. For example:``` curl \ --header "Authorization: Bearer " \ --header "Content-Type: application/json" \ --request POST \ --data '{"_ref":"managed/realm-name_user/bjensen"}' \ "https:///openidm/internal/role/3042798d-37fd-49aa-bae3-52598d2c8dc4/authzMembers?_action=create" ``` | ## Secure RCS access to Advanced Identity Cloud connector servers You can secure the `openicf` WebSocket endpoint used for communication between RCS client mode and Advanced Identity Cloud connector servers. Specifying the authorization roles allowed to connect to the `openicf` servlet for each RCS instance ensures that Advanced Identity Cloud connector servers can only be accessed by trusted RCS clients. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | This feature is [migration dependant](../product-information/migration-dependent-features.html), so isn't configured for connectors servers in tenants created before its introduction. Learn more about the introduction of the feature in [RCS configuration migration FAQ](../product-information/migration-dependent-features/rcs-configuration-migration-faq.html). | 1. Using the following example as a template, in your authentication configuration add a specific role to the `roles` array of the RCS static user mapping. This role authorizes access to the `openicf` endpoint for the specified RCS. Example ```json { "subject": "myrcsclient", (2) "roles": [ "myrcsserver-authorized" (1) ], "executeAugmentationScript": false } ``` | | | | ----- | ---------------------------------------------------------------------------------------------------------------- | | **1** | In this example, the role `myrcsserver-authorized` is added to the authenticated user's security context for the | | **2** | `myrcsclient` OAuth 2.0 client. | Use the instructions in [Change the authentication configuration over REST](authentication-and-roles.html#authentication-control-rest) to make the update. For further examples, refer to the [RCS configuration migration FAQ](../product-information/migration-dependent-features/rcs-configuration-migration-faq.html). 2. Using the following example as a template, add a new rule in your access configuration to define authorization for the `openicf` endpoint. Learn more about [changing the access configuration over REST](#access-control-rest). Example ```json { "servlet": "openicf", (2) "pattern": "myrcsserver", (3) "roles": "~myrcsserver-authorized", (1) "methods": "read" } ``` This rule ensures that: | | | | ----- | ---------------------------------------------------------------------- | | **1** | only users possessing the `myrcsserver-authorized` role can access the | | **2** | `openicf` WebSocket endpoint | | **3** | for the RCS named `myrcsserver`. | Use the instructions in [Change the access configuration over REST](#access-control-rest) to make the update. For further examples, refer to the [RCS configuration migration FAQ](../product-information/migration-dependent-features/rcs-configuration-migration-faq.html).