--- title: Authenticate through AM description: From IDM 7.0 onwards, using AM bearer tokens for authentication is the only supported method of integrating IDM with AM. component: pingidm version: 8.1 page_id: pingidm:auth-guide:rsfilter-auth canonical_url: https://docs.pingidentity.com/pingidm/8.1/auth-guide/rsfilter-auth.html keywords: ["Authentication", "OAuth 2.0"] section_ids: test-rsfilter-auth: Test authentication through AM --- # Authenticate through AM | | | | - | ------------------------------------------------------------------------------------------------------------------------ | | | From IDM 7.0 onwards, using AM bearer tokens for authentication is the only supported method of integrating IDM with AM. | PingAM (AM) is a product that provides an infrastructure for managing users, roles, and access to resources. When you use IDM and AM together in a *platform deployment*, you must configure IDM to use AM bearer tokens for authentication. This delegates all authentication to AM. In this configuration: * IDM uses an `rsFilter` that replaces all other authentication methods. * All IDM endpoints that require authentication are accessed using an authorization header that contains the bearer token, instead of `X-OpenIDM-Username` and `X-OpenIDM-Password`. Endpoints that allow anonymous access can be accessed without a token. To use AM bearer tokens for authentication, your AM configuration must include at least the following configuration: * Two OAuth 2.0 clients: an `idm-resource-server` client to introspect the bearer token and an `idm-provisioning` client used by AM to provision users in IDM. For information on configuring these clients, refer to [Configure OAuth Clients (separate identity stores)](https://backstage.forgerock.com/docs/platform/7.5/platform-setup-guide/am-setup-1.html#oauth-clients) or [Configure OAuth Clients (shared identity store)](https://backstage.forgerock.com/docs/platform/7.5/platform-setup-guide/am-setup-2.html#oauth-clients-2) in the sample platform deployments. * An [OAuth 2 provider service (separate identity stores)](https://backstage.forgerock.com/docs/platform/7.5/platform-setup-guide/am-setup-1.html#oauth-service) or [OAuth 2 provider service (shared identity store)](https://backstage.forgerock.com/docs/platform/7.5/platform-setup-guide/am-setup-2.html#oauth-service-2). * An [IDM provisioning service (separate identity stores)](https://backstage.forgerock.com/docs/platform/7.5/platform-setup-guide/am-setup-1.html#idm-prov-service) or [IDM provisioning service (shared identity store)](https://backstage.forgerock.com/docs/platform/7.5/platform-setup-guide/am-setup-2.html#idm-prov-service-2). Your IDM authentication configuration *(tooltip: You can manage the authentication configuration over REST at the config/authentication endpoint, or directly in the conf/authentication.json file.)* must include the `rsFilter` configuration and *no other* authentication methods. Sample `rsFilter` configuration The following sample `rsFilter` configuration is also available in `/path/to/openidm/samples/example-configurations/conf/rsfilter/authentication.json`: > **Collapse: Sample rsFilter authentication** > > ```json > { > "rsFilter" : { > "clientId" : "test", > "clientSecret" : "changeme", > "tokenIntrospectUrl" : "http://am.example:8080/openam/oauth2/introspect", > "scopes" : [ ], > "cache" : { > "maxTimeout" : "300 seconds" > }, > "augmentSecurityContext" : { > "type" : "text/javascript", > "source" : "require('auth/orgPrivileges').assignPrivilegesToUser(resource, security, properties, subjectMapping, privileges, 'privileges', 'privilegeAssignments');" > }, > "subjectMapping" : [ > { > "resourceTypeMapping" : { > "usr" : "managed/user" > }, > "propertyMapping" : { > "sub" : "_id" > }, > "userRoles" : "authzRoles/*", > "additionalUserFields" : [ > "adminOfOrg", > "ownerOfOrg" > ], > "defaultRoles" : [ > "internal/role/openidm-authorized" > ] > } > ], > "staticUserMapping" : [ > { > "subject" : "(usr!amadmin)", > "localUser" : "internal/user/openidm-admin", > "roles" : [ > "internal/role/openidm-authorized", > "internal/role/openidm-admin" > ] > }, > { > "subject" : "(age!idm-provisioning)", > "localUser" : "internal/user/idm-provisioning", > "roles" : [ > "internal/role/platform-provisioning" > ] > } > ], > "anonymousUserMapping" : { > "localUser" : "internal/user/anonymous", > "roles" : [ > "internal/role/openidm-reg" > ], > "executeAugmentationScript" : false > } > } > } > ``` The `rsFilter` configuration includes the following properties: * `clientId` The client ID of the AM OAuth 2.0 client used to introspect the bearer token (the `idm-resource-server`) client, in this example). * `clientSecret` The client secret of the AM OAuth 2.0 client used to introspect the bearer token. IDM encrypts this field if it isn't already. * `tokenIntrospectUrl` The URI to reach the `oauth2/introspect` endpoint in AM; for example, `http://am.example:8080/openam/oauth2/introspect`. * `scopes` Any scopes required to be present in the access token. This varies depending on your configuration. For more information about scopes, refer to [OAuth 2.0 Scopes](https://docs.pingidentity.com/pingam/8.1/oauth2-guide/oauth2-scopes.html#delegating-realm-administration-privileges) in the AM *OAuth 2.0 Guide*. * `cache` Sets the `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](../scripting-guide/script-variables-augment-security.html). | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can disable execution of the script for anonymous and static user mappings using [the `executeAugmentationScript` property](#executeAugmentationScript). Doing so can improve IDM's performance for user mappings where it's not necessary to run the script. | * `subjectMapping` An array of mappings that let you map AM realms to IDM managed object types. For example: ```json "subjectMapping" : [ { "resourceTypeMapping" : { "usr" : "managed/user" }, "propertyMapping" : { "sub" : "_id" }, "userRoles" : "authzRoles/*", "additionalUserFields" : [ "adminOfOrg", "ownerOfOrg" ], "defaultRoles" : [ "internal/role/openidm-authorized" ] } ], ``` Each `subjectMapping` includes the following properties: * Either a `resourceTypeMapping` or a `queryOnResource` property: * `resourceTypeMapping`: Maps the identity type of a subject claim in AM to a resource collection in IDM. In the access token, the subject claim is a compound identity that consists of the claim `type` and subject name, separated by a `!`. To use a `resourceTypeMapping`, unique Oauth2 subject claims must be enabled in AM. (From AM 7.1, these are enabled by default.) For more information about subject claims, refer to *About the Subject and the Subname Claims* in the section on [/oauth2/userinfo](https://docs.pingidentity.com/pingam/8.1/oidc1-guide/rest-api-oidc-userinfo-endpoint.html). * `queryOnResource`: The IDM resource to check for the authenticating user; for example, `managed/user`. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If your AM and IDM deployments use consistent realm and managed object naming, you can configure the `resourceTypeMapping` and the `queryOnResource` properties to let a single subject mapping match multiple realms. This uses a dynamic handlebars template, as in the following example:Example configuration```json "resourceTypeMapping" : { "usr" : "managed/{{substring realm 1}}" } ```This configuration lets an access token with the realm `employee` map to an IDM `managed/employee`, and an access token with the realm `contractor` map to an IDM `managed/contractor`. | * `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 `resourceTypeMapping` or `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`. Although you can configure an array of subject mappings, 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`. Subject mapping with a Remote Connector Server (RCS) If you have an RCS that is authenticating against AM, you must add a subject mapping for it. Example configuration ```json { "subject" : "RCS-OAuth-clientId", "localUser" : "internal/user/idm-provisioning" } ``` The `subject` property must be the OAuth2 client in AM set up for the remote connector server. The `localUser` property can be any existing user. | | | | - | ----------------------------------------------------------------------------------------------- | | | Do not assign the `localUser` any roles. Doing so can allow the RCS bearer token to be misused. | * `staticUserMapping` Maps AM users to a matching IDM user. This mapping can contain multiple user mappings, each with the following properties: * `subject`: The subject of the access token is the AM user. If you've 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" : "(usr!amadmin)" ``` | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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" ] } ``` | * `localUser`: The IDM user you want to associate with the AM user identified in `subject`. For example, if `subject` is set to `(usr!amadmin)`, you can set the corresponding `localUser` to `internal/user/openidm-admin`. * `roles`: The default IDM roles that this mapped user has after they authenticate. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Roles defined in `staticUserMapping` use the access policies defined in `conf/access.json`. Learn more about configuring access control in `access.json` in [Authorization and roles](authorization-and-roles.html). | * []()`executeAugmentationScript`: A boolean value. When `false`, the scripts specified in `augmentSecurityContext` will not run for the user mapping. * `anonymousUserMapping` The default user used when no access token is included in the request. Contains the following: * `localUser`: The IDM user resource referenced when no specific user is identified. For example, `internal/user/anonymous`. * `roles`: The default roles the anonymous user has, usually `internal/role/openidm-reg`. * `executeAugmentationScript`: A boolean value. When `false`, the scripts specified in `augmentSecurityContext` will not run for the user mapping. ## Test authentication through AM 1. Obtain a bearer token from AM. For example: ``` curl \ --header "X-OpenAM-Username: amAdmin" \ --header "X-OpenAM-Password: password" \ --header "Accept-API-Version: resource=2.0, protocol=1.0" \ --request POST \ --data "grant_type=client_credentials" \ --data "client_id=idm-provisioning" \ --data "client_secret=openidm" \ --data "scope=fr:idm:*" \ "http://am.example.com:8080/am/oauth2/realms/root/access_token" { "access_token": "z4uKDWiv4wnxKY7OjeG04PujG8E", "scope": "fr:idm:*", "token_type": "Bearer", "expires_in": 3599 } ``` 2. Authenticate to IDM using that bearer token: ``` curl \ --request GET \ --header "Content-Type: application/json" \ --header "Authorization: Bearer z4uKDWiv4wnxKY7OjeG04PujG8E" \ 'http://localhost:8080/openidm/info/login' { "_id": "login", "authenticationId": "idm-provisioning", "authorization": { "id": "idm-provisioning", "roles": [ "internal/role/platform-provisioning" ], "component": "internal/user" } } ``` Refer to the [sample platform setup](https://backstage.forgerock.com/docs/platform/7.5/platform-setup-guide/preface.html) documentation for instructions on setting up IDM to use AM bearer tokens for authentication.