--- title: Authentication and roles description: When a user authenticates, the user is given a set of default internal roles. These roles determine what Advanced Identity Cloud resources the user can access. Advanced Identity Cloud includes a number of default internal roles on the openidm/internal/roles endpoint. You can configure additional internal roles to customize how you restrict access to the server. component: pingoneaic page_id: pingoneaic:idm-auth:authentication-and-roles canonical_url: https://docs.pingidentity.com/pingoneaic/idm-auth/authentication-and-roles.html keywords: ["Authentication", "Roles", "Security Context"] section_ids: dynamic-role-calculation: Dynamic role calculation auth-security-context: Roles, authentication, and the security context authentication-control-rest: Change the authentication configuration over REST --- # Authentication and roles When a user authenticates, the user is given a set of default *internal roles*. These roles determine what Advanced Identity Cloud resources the user can access. Advanced Identity Cloud includes a number of default internal roles on the `openidm/internal/roles` endpoint. You can configure additional internal roles to customize how you restrict access to the server. The following internal roles are defined by default: * openidm-admin IDM administrator role, excluded from the reauthorization required policy definition by default. * openidm-authorized Default role for any user who authenticates with a username and password. * openidm-cert Default role for any user who authenticates with mutual SSL authentication. This role applies only to mutual authentication. The shared secret (certificate) must be adequately protected. The `openidm-cert` role is excluded from the reauthorization required policy definition by default. * openidm-reg Assigned to users who access Advanced Identity Cloud with the default anonymous account. The `openidm-reg` role is excluded from the reauthorization required policy definition by default. * openidm-tasks-manager Role for users who can be assigned to workflow tasks. * platform-provisioning Role for platform provisioning access. When a user authenticates, Advanced Identity Cloud calculates that user's roles as follows: * Each authentication module includes a `defaultUserRoles` property. Depending on how the user authenticates, Advanced Identity Cloud assigns the roles listed in that module's `defaultUserRoles` property to the user on authentication. The `defaultUserRoles` property is specified as an array. For most authentication modules, the user obtains the `openidm-authorized` role on authentication. For example: ```json { "name" : "MANAGED_USER", "properties" : { ... "defaultUserRoles" : [ "internal/role/openidm-authorized" ] }, ... } ``` * The `userRoles` property in an authentication module maps to an attribute (or list of attributes) in a user entry that contains that user's authorization roles. This attribute is usually `authzRoles`, unless you have changed how user roles are stored. Any internal roles that are conditionally applied are also calculated and included in the user's `authzRoles` property at this point. * If the authentication module includes a `groupRoleMapping`, `groupMembership`, or `groupComparison` property, Advanced Identity Cloud can assign additional roles to the user, depending on the user's group membership on an *external* system. Learn more in [Map external groups to internal authz roles](../idm-objects/groups-and-access-to-idm.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The roles calculated in sequence are cumulative. Roles with temporal restrictions aren't included in that list if the current time is outside of the time assigned to the role. | ## Dynamic role calculation By default, Advanced Identity Cloud calculates a user's roles only on authentication. You can configure Advanced Identity Cloud to recalculate a user's roles dynamically, with each request, instead of only when the user reauthenticates. To enable this feature, set `enableDynamicRoles` to `true` in the `JWT_SESSION` session module in the authentication configuration *(tooltip: You can manage the authentication configuration over REST at the config/authentication endpoint.)*. ## Roles, authentication, and the security context The security context (`context.security`), consists of a principal (defined by the `authenticationId` property) and an access control element (defined by the `authorization` property). If authentication is successful, the authentication framework sets the principal. Advanced Identity Cloud stores that principal as the `authenticationId`. The `authorization` property includes an `id`, an array of `roles`, and a `component`, that specifies the resource against which authorization is validated. ## Change the authentication configuration over REST You can change the authentication configuration using the endpoint `openidm/config/authentication`. First, get the entire current authentication 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 authentication configuration: ```none curl \ --header "Authorization: Bearer " \ --header "Accept-API-Version: resource=1.0" \ --request GET \ "https:///openidm/config/authentication" ``` > **Collapse: Show response** > > ```json > { > "_id": "authentication", > "rsFilter": { > "augmentSecurityContext": { > "source": "require('auth/orgPrivileges').assignPrivilegesToUser(resource, security, properties, subjectMapping, privileges, security.authorization.component.includes('/alpha_') ? 'alphaOrgPrivileges' : 'bravoOrgPrivileges', 'privilegeAssignments');", > "type": "text/javascript" > }, > "cache": { > "maxTimeout": "300 seconds" > }, > "scopes": [ > "fr:idm:*" > ], > "subjectMapping": [ > { > "additionalUserFields": [ > "adminOfOrg", > "ownerOfOrg" > ], > "defaultRoles": [ > "internal/role/openidm-authorized" > ], > "propertyMapping": { > "sub": "_id" > }, > "queryOnResource": "managed/{{substring realm 1}}_user", > "userRoles": "authzRoles/*" > } > ] > } > } > ``` 3. Create a local copy of the authentication configuration from the response in step 2, then modify it. This example adds a `staticUserMapping` attribute. It contains configuration that assigns the access management OAuth 2.0 client `myrcs1-client` the `myrcs1-client-authorized` role after successful authentication. ```json { "_id": "authentication", "rsFilter": { "augmentSecurityContext": { "source": "require('auth/orgPrivileges').assignPrivilegesToUser(resource, security, properties, subjectMapping, privileges, security.authorization.component.includes('/alpha_') ? 'alphaOrgPrivileges' : 'bravoOrgPrivileges', 'privilegeAssignments');", "type": "text/javascript" }, "cache": { "maxTimeout": "300 seconds" }, "scopes": [ "fr:idm:*" ], "staticUserMapping": [ (1) { "subject": "myrcs1-client", "roles": [ "myrcs1-client-authorized" ] } ], (2) "subjectMapping": [ { "additionalUserFields": [ "adminOfOrg", "ownerOfOrg" ], "defaultRoles": [ "internal/role/openidm-authorized" ], "propertyMapping": { "sub": "_id" }, "queryOnResource": "managed/{{substring realm 1}}_user", "userRoles": "authzRoles/*" } ] } } ``` | | | | ----- | --------------------------------------- | | **1** | Start of `staticUserMapping` attribute. | | **2** | End of `staticUserMapping` attribute. | 4. Replace the authentication configuration: ```none curl \ --header "Authorization: Bearer " \ --header "Content-type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --request PUT \ --data '{ "_id": "access", "rsFilter": (1) }' \ "https:///openidm/config/authentication" ``` | | | | ----- | ------------------------------------------------------------------------------------------------- | | **1** | Replace \ with the `rsFilter` object you modified in step 3. | > **Collapse: Show response** > > ```json > { > "_id": "authentication", > "rsFilter": { > "augmentSecurityContext": { > "source": "require('auth/orgPrivileges').assignPrivilegesToUser(resource, security, properties, subjectMapping, privileges, security.authorization.component.includes('/alpha_') ? 'alphaOrgPrivileges' : 'bravoOrgPrivileges', 'privilegeAssignments');", > "type": "text/javascript" > }, > "cache": { > "maxTimeout": "300 seconds" > }, > "scopes": [ > "fr:idm:*" > ], > "staticUserMapping": [ (1) > { > "subject": "myrcs1-client", > "roles": [ > "myrcs1-client-authorized" > ] > } > ], > "subjectMapping": [ > { > "additionalUserFields": [ > "adminOfOrg", > "ownerOfOrg" > ], > "defaultRoles": [ > "internal/role/openidm-authorized" > ], > "propertyMapping": { > "sub": "_id" > }, > "queryOnResource": "managed/{{substring realm 1}}_user", > "userRoles": "authzRoles/*" > } > ] > } > } > ``` > > | | | > | ----- | -------------------------------------------------------------------------------- | > | **1** | The authentication configuration contains the new `staticUserMapping` attribute. | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can also modify configuration using a PATCH request to the same endpoint.- The following example adds the same `staticUserMapping` attribute example in step 3 directly to the `rsFilter` attribute: ```none curl \ --header "Authorization: Bearer " \ --header "Content-type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --request PATCH \ --data ' [ { "operation" : "add", "field" : "/rsFilter/staticUserMapping/", (1) "value" : [ { "subject" : "myrcs1_client", "roles" : [ "myrcsclient1-authorized" ] } ] } ]' \ "https:///openidm/config/authentication" ``` 1 If you specify the field name on its own (/rsFilter/staticUserMapping/), the value is added on the first request and overwrites on subsequent requests. - The following example appends an object to the `staticUserMapping` attribute: ```none curl \ --header "Authorization: Bearer " \ --header "Content-type: application/json" \ --header "Accept-API-Version: resource=1.0" \ --request PATCH \ --data ' [ { "operation" : "add", "field" : "/rsFilter/staticUserMapping/-", (1) "value" : { "subject" : "myrcs2_client", "roles" : [ "myrcsclient2-authorized" ] } } ]' \ "https:///openidm/config/authentication" ``` 1 If you specify the field name followed by a hyphen (/rsFilter/staticUserMapping/-), the value is appended. |