--- title: Authenticate through a generic OIDC provider description: Configure PingIDM to authenticate through a generic OpenID Connect provider using OAuth 2.0 bearer tokens and the rsFilter, using PingOne as an example component: pingidm version: 8.1 page_id: pingidm:auth-guide:rsfilter-oidc-auth canonical_url: https://docs.pingidentity.com/pingidm/8.1/auth-guide/rsfilter-oidc-auth.html llms_txt: https://docs.pingidentity.com/pingidm/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md keywords: ["Authentication", "OAuth 2.0", "OpenID Connect", "PingOne"] section_ids: rsfilter-oidc-pingone-setup: Set up PingOne rsfilter-oidc-config: Configure the rsFilter test-rsfilter-oidc-auth: Test authentication through a generic OIDC provider --- # 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](../setup-guide/platform-admin-ui.html). * This configuration delegates all authentication to the OpenID Connect (OIDC) provider. 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. | 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](../setup-guide/platform-admin-ui.html) in standalone mode against an external identity provider (IdP). This page uses [PingOne](https://docs.pingidentity.com/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](rsfilter-auth.html) 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](https://docs.pingidentity.com/pingone/applications/p1_resources.html) to act as the OAuth 2.0 resource server that IDM introspects tokens against: 1. In the PingOne admin console, [add a custom resource](https://docs.pingidentity.com/pingone/applications/p1_adding_custom_resource.html), for example, `idm-resource-server`, and add the `fr:idm:*` [scope](https://docs.pingidentity.com/pingone/applications/p1_editresource.html). 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](https://docs.pingidentity.com/pingone/applications/p1_editresource.html) to Client Secret Basic. 4. Note the resource's Token Introspection Endpoint. Example ```console https://auth.pingone.com//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 *(tooltip: You can manage the authentication configuration over REST at the config/authentication endpoint, or directly in the conf/authentication.json file.)*, using the values you collected from PingOne: ```json { "rsFilter" : { "clientId" : "", "clientSecret" : "", "tokenIntrospectUrl" : "https://auth.pingone.com//as/introspect", "scopes" : [ "fr:idm:*" ], "cache" : { "maxTimeout" : "300 seconds" }, "staticUserMapping" : [ { "subject" : "", "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](authorization-and-roles.html). | * `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](rsfilter-auth.html#subject-mapping-rsfilter-auth). 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](../setup-guide/platform-admin-ui.html#platform-admin-ui-oidc). | 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 " \ 'http://localhost:8080/openidm/info/login' { "_id": "login", "authenticationId": "", "authorization": { "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.