--- title: Authentication through OAuth 2.0 and subject mappings description: Ping Identity IDM uses AM bearer tokens for authentication. Accordingly, all authentication is delegated to AM. With AM bearer tokens, all Advanced Identity Cloud endpoints that require authentication are accessed using an authorization header that contains the bearer token. Endpoints that allow anonymous access can be accessed without a token. component: pingoneaic page_id: pingoneaic:idm-auth:rsfilter-module canonical_url: https://docs.pingidentity.com/pingoneaic/idm-auth/rsfilter-module.html keywords: ["Authentication", "OAuth 2.0"] section_ids: test-rsfilter-auth: Test authentication --- # Authentication through OAuth 2.0 and subject mappings Ping Identity IDM uses AM bearer tokens for authentication. Accordingly, all authentication is delegated to AM. With AM bearer tokens, all Advanced Identity Cloud endpoints that require authentication are accessed using an authorization header that contains the bearer token. Endpoints that allow anonymous access can be accessed without a token. This page details the backend process of how AM does this, which includes subject mappings. An `rsFilter` is an authentication method used to delegate authentication from IDM to AM. In Advanced Identity Cloud, the `rsFilter` is predefined in the authentication configuration *(tooltip: You can manage the authentication configuration over REST at the config/authentication endpoint.)*. The `rsFilter` configuration includes the following properties: * `scopes` Any scopes that are required to be present in the access token. This will vary depending on your configuration. For more information about scopes, refer to [OAuth 2.0 scopes](../am-oauth2/oauth2-scopes.html) in the AM *OAuth 2.0 Guide*. * `cache` Sets the timeout (`maxTimeout`), in seconds, after which the token is removed from the cache. * `augmentSecurityContext` Specifies a script that is executed only after a successful authentication request. The script helps to populate the expected security context. For more information, refer to [The `augmentSecurityContext` trigger](../idm-scripting/script-variables-augment-security.html). * `subjectMapping` An array of mappings that maps the AM realms (in Advanced Identity Cloud `/alpha` and `/bravo`) to IDM managed object types. For example: ```json { "subjectMapping": [ { "queryOnResource": "managed/realm-name_user", "propertyMapping": { "sub": "_id" }, "userRoles": [ "authzRoles/*" ], "additionalUserFields": [ "adminOfOrg", "ownerOfOrg" ], "defaultRoles": [ "internal/role/openidm-authorized" ] } ] } ``` * `queryOnResource`: The IDM resource to check for the authenticating user; for example, `managed/realm-name_user`. The `queryOnResource` property supports dynamic handlebars template that lets a single subject mapping match multiple realms, if the managed objects are named prescriptively, and based on the realm name. For example: ```json "queryOnResource" : "managed/realm-name_user" ``` This example configuration lets an access token with the realm `alpha` map to an IDM `managed/alpha_user`, and an access token with the realm `bravo` map to an IDM `managed/bravo_user`. The configuration is useful if your AM and IDM deployments use a consistent realm and managed object naming. * `realm`: The AM realm to which this subject mapping applies. A value of `/` specifies the top-level realm. If this property is absent, the mapping can apply to any realm, which is useful if the `queryOnResource` uses a dynamic handlebars template. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------- | | | You cannot have more than one mapping for the same realm, and you cannot have more than one mapping that has no `realm` in the configuration. | * `propertyMapping`: Maps fields in the AM access token to properties in IDM. This mapping is used to construct the query filter that locates the authenticating user. The default configuration maps the subject (`sub`) in the access token to the `_id` in IDM. * `userRoles`: Specifies one or more relationship fields containing authorization roles. IDM uses the `_refId` from the array elements in these fields to populate the user roles in the security context. `userRoles` accepts an array of strings, allowing roles to be sourced from multiple relationship fields. Example: Single relationship field (current array format) ```json "userRoles" : [ "authzRoles/*" ] ``` Example: Multiple relationship fields ```json "userRoles" : [ "authzRoles/*", "groups/*" ] ``` Example: Single relationship field (legacy format) ```json "userRoles" : "authzRoles/*" ``` * `additionalUserFields`: Determines the field to consult for locating the authorization roles; usually `authzRoles`, unless you have changed how user roles are stored. This field must be a relationship field. IDM uses the `_refId` from the array elements to populate the user roles in the security context. * `defaultRoles`: The default roles that should be applied to a user who authenticates using the `rsFilter`. ```json { "subject" : "RCS-OAuth-clientId", "localUser" : "internal/user/idm-provisioning" } ``` The `subject` must reflect the OAuth2 client in AM that has been set up for the remote connector server. The `localUser` can be any existing user. Do not assign that user any roles to ensure that the connector server bearer token cannot be used for any other purpose. * `staticUserMapping` Maps AM users to a matching IDM user. Can contain multiple user mappings, each with three properties: `subject`, `localUser`, and `roles`. * `subject` of the access token (the AM user). If you have specified a `resourceTypeMapping`, the static user mapping includes the full new subject string to match service accounts or static subject mappings, for example: ```json "subject" : "amadmin" ``` * `localUser` is the IDM user you want to associate with the AM user identified in `subject`. For example, if `subject` is set to `amadmin`, you might set the corresponding `localUser` to `internal/user/openidm-admin`. * `roles` the default IDM roles that this mapped user will have after they authenticate. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The `idm-provisioning` subject is a service account used by AM to provision users in IDM. You *must* include this subject in your `staticUserMapping`. For example: | ```json { "subject": "(age!idm-provisioning)", "localUser": "internal/user/idm-provisioning", "roles" : [ "internal/role/platform-provisioning" ] } ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Only one mapping is selected and used during the authentication process. If there is a `realm` attribute in the access token, that realm is used to select an appropriate mapping. If no mapping is defined for the access token's realm, or if the realm is not provided in the access token, the authentication uses a mapping that does not define a `realm`.In most situations if you have a remote connector server that is authenticating against AM, you must add a subject mapping specifically for the connector server.In this case you must add a `staticUserMapping`. | ## Test authentication To test authentication, create your own OAuth 2.0 client with the proper grant types. For more information, refer to [Create custom OAuth 2.0 applications with application management.](../app-management/applications.html#oidc-openid-connect-applications) 1. Obtain a bearer token from AM. For example, the bearer token would look like: ``` Authorization: Bearer z4uKDWiv4wnxKY7OjeG04PujG8E ``` For more information on how get a bearer token, refer to [Authenticate to REST API with an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#overview). 2. Authenticate to IDM using that bearer token: ``` curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer z4uKDWiv4wnxKY7OjeG04PujG8E" \ 'https:///openidm/info/login' { "_id": "login", "authenticationId": "testClientID", "authorization": { "id": "testClientID", "roles": [ "internal/role/platform-provisioning" ], "component": "internal/user" } } ```