Configure OpenID Connect authentication

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

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

Supported capabilities

When using an OpenID Connect IDP, the user is redirected to the OpenID Connect issuer for SSO, and is 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 of the OpenID Connect type, using the properties listed in the following table for reference.

Property Definition

Connectivity
The following properties configure the connection and exchanges for OpenID Connect authentication.

Issuer identifier

OpenID Connect issuer, typically a URL. This property is mandatory (e.g., https://accounts.google.com).

Client ID

Client ID used to authenticate to the OpenID Connect service. This property is mandatory.

Client secret

Client secret used to authenticate to the OpenID Connect service. This property is mandatory.

Redirect URL

URL to which the IDP should return the user after authentication. This property is read-only. The default generated value is <host-base-url>/login/oauth2/code/<idp-name>, where <host-base-url> is the base URL by which you access xDM.

In high-availability architectures, you can access Semarchy xDM via two URLs:

  • One for the active node, using the host and port of the active node.

  • One for load balancer routing the traffic on the passive nodes, using the host and port of the load balancer.

Make sure to configure both these URLs in the third-party IDP for redirection to work for both the active and load-balanced passive nodes.

Logout URL

Identity provider URL to perform SSO logout. If unspecified, only a local logout is performed.

User authentication
The following properties configure how user information is retrieved.

Additional scopes

Comma-separated list of additional scopes requested from the IDP, in addition to the openid, email, and profile scopes requested by default. These scopes return a set of claims as defined by the IDP. Note that OpenID Connect providers return no value when requesting an unknown scope.

Username claim

ID token claim containing the user name. This property is mandatory. The default value is email.

Roles
The following properties are used to retrieve the roles of an authenticated user.

Roles claim

Claim mapped to the list of roles. The default value is groups.

Roles claim separator

Character separating roles in the roles claim token if the role claim is a delimited string. The default value is ,.

Advanced
The following properties cover specific configuration situations.

Extra parameters

Additional parameters added to the query string of the IDP authorization endpoint URL. The value is a JSON object with keys being the parameter names and values being the parameter values (e.g., Google supports a specific HD parameter to limit the accounts to a specific domain).

Provider document URL

If the IDP is not using the standard document endpoint /well-known/openid-configuration, use this property to specify the configuration document URL.

Profile synchronization

In OpenID Connect, individual profile attributes can be mapped to a claim using their respective name. The IDP must be configured accordingly to ensure these claims are returned in the additional scopes.

For more information on profile synchronization properties, see Configure profile synchronization.