PingIDM

Authenticate through a generic OIDC provider

  • This feature requires the Platform admin UI 8.1.1 or later. Learn more in Install the Platform admin UI for standalone IDM.

  • This configuration delegates all authentication to the OpenID Connect (OIDC) provider. Your IDM authentication configuration must include the rsFilter configuration and no other authentication methods.

IDM can delegate authentication to any OIDC provider that supports OAuth 2.0 token introspection, not only PingAM. This is useful when you run the Platform admin UI in standalone mode against an external identity provider (IdP). This page uses PingOne as an example. You can substitute the equivalent settings from your own OIDC provider.

If you’re integrating IDM with AM in a platform deployment, use Authenticate through AM instead. The rsFilter configuration is specific to AM’s OAuth 2.0 clients and provisioning service.

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.

  • IDM validates the bearer token by calling the OIDC provider’s token introspection endpoint. It doesn’t need to be registered as an OIDC client itself. It only needs credentials to call introspection.

Set up PingOne

Before you configure the rsFilter, create a PingOne resource to act as the OAuth 2.0 resource server that IDM introspects tokens against:

  1. In the PingOne admin console, add a custom resource, for example, idm-resource-server, and add the fr:idm:* scope.

  2. Note the resource’s Resource ID and Client Secret, shown in the resource’s Overview panel.

    Unlike AM, a PingOne resource has no separate "Client ID" field. The Resource ID itself is used as the clientId when IDM authenticates against the Token Introspection Endpoint.

  3. Set the Token Introspection Endpoint Authentication Method to Client Secret Basic.

  4. Note the resource’s Token Introspection Endpoint.

    Example
    https://auth.pingone.com/<environment-id>/as/introspect

  5. Leave the default sub claim mapping (the PingOne user ID) as-is.

  6. Find the PingOne user ID of the user you want to map to an IDM identity. Then, go to that user’s profile and click the API tab.

  7. Copy the ID value.

Use the values from the Resource ID, Client Secret, Token Introspection Endpoint, and user ID to configure the rsFilter in the next section.

Configure the rsFilter

Add an rsFilter block to your IDM authentication configuration, using the values you collected from PingOne:

{
    "rsFilter" : {
        "clientId" : "<pingone-resource-id>",
        "clientSecret" : "<pingone-resource-client-secret>",
        "tokenIntrospectUrl" : "https://auth.pingone.com/<environment-id>/as/introspect",
        "scopes" : [
            "fr:idm:*"
        ],
        "cache" : {
            "maxTimeout" : "300 seconds"
        },
        "staticUserMapping" : [
            {
                "subject" : "<pingone-user-id>",
                "localUser" : "internal/user/openidm-admin",
                "roles" : [
                    "internal/role/openidm-authorized",
                    "internal/role/openidm-admin"
                ]
            }
        ],
        "anonymousUserMapping" : {
            "localUser" : "internal/user/anonymous",
            "roles" : [
                "internal/role/openidm-reg"
            ],
            "executeAugmentationScript" : false
        }
    }
}

The rsFilter configuration includes the following properties:

clientId

The identifier IDM presents when calling the OIDC provider’s token introspection endpoint. For PingOne, this is the Resource ID.

clientSecret

The secret IDM presents when calling the OIDC provider’s token introspection endpoint. IDM encrypts this field if it isn’t already.

tokenIntrospectUrl

The URI of the OIDC provider’s token introspection endpoint.

scopes

Any scopes required to be present in the access token. This varies depending on your configuration.

cache

Sets the maxTimeout to a seconds-based value (for example, 300 seconds), after which the token is removed from the cache.

staticUserMapping

Maps a subject claim from the access token to a matching IDM user. This mapping can contain multiple user mappings, each with the following properties:

  • subject: The value of the access token’s sub claim. For PingOne, this is the PingOne user ID, found on the user’s API tab.

  • localUser: The IDM user you want to associate with the subject. For example, 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.
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, any script specified in augmentSecurityContext won’t run for this mapping.

If your OIDC provider issues access tokens with claims other than a flat sub, or you need to map multiple realms or tenants to different IDM managed object types, use subjectMapping instead of, or in addition to, staticUserMapping. Learn more about the full subjectMapping property list. Its structure is provider-agnostic even though the examples there are written for AM.

Test authentication through a generic OIDC provider

The following step tests the rsFilter configuration using a bearer token directly. To test the full sign-on flow through the Platform admin UI, you also need to register your OIDC provider as a Proof Key for Code Exchange (PKCE) public client and set the corresponding environment variables. Learn more in Configure the Platform admin UI for a generic OIDC provider.

  1. Get a bearer token for the mapped user from your OIDC provider. How you do this depends on your provider. For PingOne, you can sign on as that user through an existing OIDC web application scoped to fr:idm:* and capture the resulting access token.

  2. Authenticate to IDM using the bearer token:

    curl \
--request GET \
--header "Content-Type: application/json" \
--header "Authorization: Bearer <access-token>" \
'http://localhost:8080/openidm/info/login'
{
  "_id": "login",
  "authenticationId": "<pingone-user-id>",
  "authorization": {
    "id": "<pingone-user-id>",
    "roles": [
      "internal/role/openidm-authorized",
      "internal/role/openidm-admin"
    ],
    "component": "internal/user"
  }
}

After you configure the Platform admin UI as a PKCE public client, users can sign on as follows:

  1. The user navigates to the Platform admin UI.

  2. The Platform admin UI redirects the user to the OIDC provider to sign on.

  3. After the user signs on, the OIDC provider redirects them back to the Platform admin UI, where they’re granted the permissions defined by the rsFilter mapping.