Configure an OpenID Connect identity provider

The OpenID Connect protocol is widely supported by single sign-on identity providers (IDPs), including Google, PingFederate, AD FS, Okta, Microsoft Entra ID (formerly known as Azure Active Directory), Microsoft, or SalesForce.com.

Semarchy xDG supports authentication with such providers using OpenID Connect IDPs.

Supported capabilities

When using an OpenID Connect IDP, users are redirected to the OpenID Connect issuer for single sign-on (SSO) and are authenticated using a client ID and client secret provided by the issuer.

After successful authentication:

The username is returned in the username claim.
The list of roles is returned in a role claim.

Profile properties are synchronized from claims mapped by their name. These claims should be included in the list of additional scopes requested from the IDP.

Configuration

To configure OpenID Connect authentication, follow the steps to configure an identity provider, using the properties listed in the table below for reference.

General

Property Definition

Property	Definition
Redirect URI	URI indicating where the identity provider should redirect after authentication. This property is read-only. The default generated value is `<host-base-url>/login/oauth2/code/<idp-name>`, where `<host-base-url>` represents the base URL for accessing xDM.
Display order	Number defining the providers' order of appearance on the login page. Lowest number is listed first.
Use discovery endpoint	If enabled, the discovery endpoint will be used to fetch the provider configuration. This allows the platform to load the configuration from the endpoint and automatically update it any changes occur at the source.
Discovery endpoint	URL pointing to the location where the remote IDP’s discovery metadata is hosted.
Authorization URL	Endpoint required by the OpenID Connect protocol for authorization.
Token URL	Endpoint required by the OpenID Connect protocol for obtaining tokens.
Logout URL	(Optional) Endpoint for logout in the OpenID Connect protocol.
User info URL	(Optional) Endpoint for user information in the OpenID Connect protocol.
Issuer	(Optional) Value against which the platform verifies issuer claims in IDP responses.
Token URL	Endpoint required by the OpenID Connect protocol to issue a token.
Validate signature	Determines whether the platform verifies signatures on the external ID token signed by this IDP. If enabled, the platform equires knowledge of the external OpenID Connect IDP’s public key. For performance purposes, the platform caches the public key of the external OpenID Connect IDP.
Use JWKS URL	Only available if Validate signature* is enabled.* If enabled, the platform downloads the IDP’s public keys from the JSON Web Key Set (JWKS) URL. New keys are download when the IDP generates a new key pair. If disabled, the platform uses the public key (or certificate) stored in its database. In this case, any new key is imported into the platform as well when the IDP key pair changes.
JWKS URL	URL pointing to the location of the IDP’s JSON Web Key Set. For more information, see the JWK specification.
Validating public key	Only available if Use JWKS URL* is disabled.* Public key in PEM format used by the platform to verify external IDP signatures.
Validating public key ID	Only available if Use JWKS URL* is disabled.* ID of the public key in PEM format. Because there is no standardized method for computing the key ID from the key, external IDPs may use different algorithms compared to the platform. If left unspecified, the platform uses the validating public key for all requests, regardless of the key ID provided by the external IDP. When specified, serves as the key ID used by the platform for signature validation from providers, and must align with the key ID specified by the IDP.
Use PKCE	Enable proof of key code exchange (PKCE) for IDP brokering.
PKCE method	Only availbale if Use PKCE* is enabled.* PKCE method to use.
Client authentication	Specifies the client authentication method used by the platform in conjunction with the authorization code flow. For more information, see the client authentication specifications.
Client ID	Identifier for the client registered with the identity provider.
Client secret	Secret key registered with the identity provider.
Client assertion signature algorithm	Signature algorithm used to create a JSON Web Token (JWT) assertion for client authentication. This is necessary for JWTs signed with a private key or when using a client secret as a JWT. If no algorithm is specified, the following algorithms are adapted: RS256 for JWTs signed with a private key and HS256 for client secrets used as JWTs.

Redirect URI

URI indicating where the identity provider should redirect after authentication. This property is read-only. The default generated value is <host-base-url>/login/oauth2/code/<idp-name>, where <host-base-url> represents the base URL for accessing xDM.

Display order

Number defining the providers' order of appearance on the login page. Lowest number is listed first.

Use discovery endpoint

If enabled, the discovery endpoint will be used to fetch the provider configuration. This allows the platform to load the configuration from the endpoint and automatically update it any changes occur at the source.

Discovery endpoint

URL pointing to the location where the remote IDP’s discovery metadata is hosted.

Authorization URL

Endpoint required by the OpenID Connect protocol for authorization.

Token URL

Endpoint required by the OpenID Connect protocol for obtaining tokens.

Logout URL

(Optional) Endpoint for logout in the OpenID Connect protocol.

User info URL

(Optional) Endpoint for user information in the OpenID Connect protocol.

Issuer

(Optional) Value against which the platform verifies issuer claims in IDP responses.

Token URL

Endpoint required by the OpenID Connect protocol to issue a token.

Validate signature

Determines whether the platform verifies signatures on the external ID token signed by this IDP. If enabled, the platform equires knowledge of the external OpenID Connect IDP’s public key. For performance purposes, the platform caches the public key of the external OpenID Connect IDP.

Use JWKS URL

Only available if Validate signature is enabled.
If enabled, the platform downloads the IDP’s public keys from the JSON Web Key Set (JWKS) URL. New keys are download when the IDP generates a new key pair. If disabled, the platform uses the public key (or certificate) stored in its database. In this case, any new key is imported into the platform as well when the IDP key pair changes.

JWKS URL

URL pointing to the location of the IDP’s JSON Web Key Set. For more information, see the JWK specification.

Validating public key

Only available if Use JWKS URL is disabled.
Public key in PEM format used by the platform to verify external IDP signatures.

Validating public key ID

Only available if Use JWKS URL is disabled.
ID of the public key in PEM format.
Because there is no standardized method for computing the key ID from the key, external IDPs may use different algorithms compared to the platform. If left unspecified, the platform uses the validating public key for all requests, regardless of the key ID provided by the external IDP. When specified, serves as the key ID used by the platform for signature validation from providers, and must align with the key ID specified by the IDP.

Use PKCE

Enable proof of key code exchange (PKCE) for IDP brokering.

PKCE method

Only availbale if Use PKCE is enabled.
PKCE method to use.

Client authentication

Specifies the client authentication method used by the platform in conjunction with the authorization code flow. For more information, see the client authentication specifications.

Client ID

Identifier for the client registered with the identity provider.

Client secret

Secret key registered with the identity provider.

Client assertion signature algorithm

Signature algorithm used to create a JSON Web Token (JWT) assertion for client authentication. This is necessary for JWTs signed with a private key or when using a client secret as a JWT. If no algorithm is specified, the following algorithms are adapted: RS256 for JWTs signed with a private key and HS256 for client secrets used as JWTs.

Advanced

Property Definition

Property	Definition
Scopes	Scopes requested for authorization. Supports a space-separated list of scopes. Defaults to `openid`.
Sync mode	Strategy for updating user information from the identity provider through mappers. Possible values are: Force: updates user data when possible. Import: imports user data without updating them.
Prompt	Specifies whether the authorization server prompts the end-user for re-authentication and consent.
Forwarded query parameters	Custom query parameters, not part of the OpenID Connect or OAuth standard, to be forwarded to external IDP from the initial application request to the Authorization endpoint. Multiple parameters should be separated by a comma (`,`).
Allowed clock skew	Permissible clock skew, in seconds, when validating identity provider tokens. Default value: `0`.
Verify essential claim	If enabled, ID tokens issued by the identity provider must include a specific claim. Otherwise, the user can not authenticate through this broker.
Essential claim	Only available if Verify essential claim* is enabled.* Name of the JWT token claim to filter (match is case sensitive).
Essential claim value	Only available if Verify essential claim* is enabled.* Specifies the value of the JWT token claim to match. Supports regular expressions.
Store tokens	If enabled, the platform stores tokens from the identity provider.
Store tokens readable	If enabled, users can retrieve the stored token from the identity provider. This action also applies to the broker client-level role’s read token.
Accepts prompt=none forward from client	If enabled, when a client sends a `prompt=none` request while not authenticated, the error is not directly returned to the client. Instead, the request is forwarded to the identity provider.
Access token is JWT	If enabled, indicates that the access token received from the identity provider is a JWT, making its claims accessible for mappers.
Disable user info	If enabled, the user info service for obtaining additional user information is disabled. By default, the platform uses the OpenID Connect service.
Trust email	If enabled, emails provided by this provider are not verified by the platform.
Disable nonce	If enabled, prevents the inclusion of the nonce parameter in the authentication request. By default, the nonce parameter is sent and verified.
Backchannel logout	If enabled, indicates that the external IDP supports backchannel logout.
Pass max_age	If enabled, includes the `max_age` parameter in the request sent to the identity provider.
Pass current locale	If enabled, includes the current locale as a `ui_locales` parameter in the request sent to the identity provider.

Scopes

Scopes requested for authorization. Supports a space-separated list of scopes. Defaults to openid.

Sync mode

Strategy for updating user information from the identity provider through mappers. Possible values are:

Force: updates user data when possible.
Import: imports user data without updating them.

Prompt

Specifies whether the authorization server prompts the end-user for re-authentication and consent.

Forwarded query parameters

Custom query parameters, not part of the OpenID Connect or OAuth standard, to be forwarded to external IDP from the initial application request to the Authorization endpoint. Multiple parameters should be separated by a comma (,).

Allowed clock skew

Permissible clock skew, in seconds, when validating identity provider tokens. Default value: 0.

Verify essential claim

If enabled, ID tokens issued by the identity provider must include a specific claim. Otherwise, the user can not authenticate through this broker.

Essential claim

Only available if Verify essential claim is enabled.
Name of the JWT token claim to filter (match is case sensitive).

Essential claim value

Only available if Verify essential claim is enabled.
Specifies the value of the JWT token claim to match. Supports regular expressions.

Store tokens

If enabled, the platform stores tokens from the identity provider.

Store tokens readable

If enabled, users can retrieve the stored token from the identity provider. This action also applies to the broker client-level role’s read token.

Accepts prompt=none forward from client

If enabled, when a client sends a prompt=none request while not authenticated, the error is not directly returned to the client. Instead, the request is forwarded to the identity provider.

Access token is JWT

If enabled, indicates that the access token received from the identity provider is a JWT, making its claims accessible for mappers.

Disable user info

If enabled, the user info service for obtaining additional user information is disabled. By default, the platform uses the OpenID Connect service.

Trust email

If enabled, emails provided by this provider are not verified by the platform.

Disable nonce

If enabled, prevents the inclusion of the nonce parameter in the authentication request. By default, the nonce parameter is sent and verified.

Backchannel logout

If enabled, indicates that the external IDP supports backchannel logout.

Pass max_age

If enabled, includes the max_age parameter in the request sent to the identity provider.

Pass current locale

If enabled, includes the current locale as a ui_locales parameter in the request sent to the identity provider.

Mappers

Mappers are generic for all identity provider types.

For more information, see Configure mappers.