Authenticate through AM

When you use Identity Cloud and AM together in a platform deployment, you configure Identity Cloud to use AM bearer tokens for authentication, instead of setting up traditional authentication modules. This delegates all authentication to AM. In this configuration, Identity Cloud uses an rsFilter that replaces all other authentication methods.

With AM bearer tokens, all Identity Cloud 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.

Important

  • From Identity Cloud 7.0 onwards, using AM bearer tokens for authentication is the only supported method of integrating Identity Cloud with AM.

  • To use AM bearer tokens for authentication, your AM configuration must include at least the following configuration:

    Your Identity Cloud authentication configuration must include the rsFilter configuration and no other authentication methods.

{
    "rsFilter" : {
        "clientId" : "",
        "clientSecret" : "",
        "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"
            ]
        }
    }
}

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. Identity Cloud will encrypt this field if it isn't encrypted already.

tokenIntrospectUrl

The URI to reach the oauth2/introspect endpoint in AM, for example, http://am.example:8080/openam/oauth2/introspect.

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, see About Scopes 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, see "The augmentSecurityContext Trigger".

subjectMapping

An array of mappings that let you map AM realms to Identity Cloud managed object types. For example:

"subjectMapping" : [
    {
        "resourceTypeMapping" : {
            "usr" : "managed/realm-name_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 Identity Cloud. 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, see About the Subject and the Subname Claims in the section on /oauth2/userinfo.

    • queryOnResource: The Identity Cloud resource to check for the authenticating user; for example, managed/realm-name_user.

    Both the resourceTypeMapping and the queryOnResource properties support a 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:

    "resourceTypeMapping" : {
        "usr" : "managed/{{substring realm 1}}"
    }       

    This configuration lets an access token with the realm employee map to an Identity Cloud managed/employee, and an access token with the realm contractor map to an Identity Cloud managed/contractor. The configuration is useful if your AM and Identity Cloud 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 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 Identity Cloud. 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 Identity Cloud.

  • userRoles: 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. Identity Cloud uses the _refId from the array elements to populate the user roles in the security context.

  • 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. Identity Cloud 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.

Note

If you have a remote connector server that is authenticating against AM, you must add a subject mapping specifically for the connector server. For example:

{
    "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 Identity Cloud 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:

    "subject" : "(usr!amadmin)"
  • localUser is the Identity Cloud user you want to associate with the AM user identified in subject. For example, if subject is set to (usr!amadmin), you might set the corresponding localUser to internal/user/openidm-admin.

  • roles the default Identity Cloud roles that this mapped user will have after they authenticate.

Note

The idm-provisioning subject is a service account used by AM to provision users in Identity Cloud. You must include this subject in your staticUserMapping. For example:

{
    "subject": "(age!idm-provisioning)",
    "localUser": "internal/user/idm-provisioning",
    "roles" : [
        "internal/role/platform-provisioning"
    ]
}
anonymousUserMapping

The default user that will be used when no access token is included in the request. Contains two properties: localUser and userRoles.

  • localUser: the Identity Cloud user resource referenced when no specific user is identified. For example, internal/user/anonymous.

  • roles: the default roles that the anonymous user will have, usually internal/role/openidm-reg.

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 Identity Cloud using that bearer token:

    curl \
    --request GET \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer z4uKDWiv4wnxKY7OjeG04PujG8E" \
    'https://tenant-name.forgeblocks.com/openidm/info/login'
    {
      "_id": "login",
      "authenticationId": "idm-provisioning",
      "authorization": {
        "id": "idm-provisioning",
        "roles": [
          "internal/role/platform-provisioning"
        ],
        "component": "internal/user"
      }
    }

See the Platform Setup Guide for complete instructions on setting up Identity Cloud to use AM bearer tokens for authentication.

Read a different version of :