Overview of OpenID Connect

OIDC is a protocol that allows client applications (called relying parties or RPs) to confirm that a user is who they say they are by contacting an authorization server (called an OpenID Provider or OP).

The authorization code flow

The PingDirectory Server administrative console uses the authorization code flow implementation of the protocol.

The following is the basic authorization code flow where the PingDirectory Server administrative console acts as the RP in steps 1-7, the managed directory server acts as the RP in step 8, and PingOne or your custom authorization server acts as the OP.


A workflow diagram of the numbered steps in the authorization code flow.
  1. The PingDirectory Server administrative console (RP) prepares an authentication request containing the desired request parameters.
  2. The administrative console (RP) sends the request to the authorization server.
  3. The authorization server (OP) authenticates the user.
  4. The authorization server (OP) obtains user consent/authorization.
  5. The authorization server (OP) sends the user back to the administrative console with an authorization code.
  6. The administrative console (RP) requests a response using the authorization code at the token endpoint.
  7. The administrative console (RP) receives a response that contains an ID token and access token in the response body.
  8. The administrative console attempts to use the tokens to perform an LDAP bind with the directory server (RP) through the OAUTHBEARER SASL mechanism. In the process of establishing this LDAP bind, the directory server (RP) validates the tokens.

Configuring OIDC with the PingDirectory Server administrative console

The authorization server must be configured with the following settings.

Configuration requirement Description

An OIDC client with a client ID, client secret, and a Redirection URI.

The client ID and client secret are used by the authorization server to confirm that the authentication and token requests are coming from a valid source.

Set the redirection URI value to https://<hostname>:<HTTPS_port>/console/oidc/cb, where https://<hostname>:<HTTPS_port>/console/ is where you access the console.

Note:

The redirection URI value is used by the authorization server in steps 3 and 5 when sending the end user back to the RP. If the value is incorrect, the authorization server displays an error.

The authorization server must be able to return an ID token that maps to a user on the managed PingDirectory server.

The sub field in the ID token must be mappable.

The PingDirectory Server administrative console must be configured with the following settings.

application.yml configuration name Embedded console setting name Settings required

PingData.SSO.OIDC.enabled

SSO Enabled

true. Necessary for the console to start the OIDC login flow.

Note:

If SSO Enabled is set to false, the console asks for a username and password.

PingData.SSO.OIDC.issuerUri

OIDC Issuer URI

Allows the client to use OIDC discovery to determine the correct addresses to send the authentication request to in step 2, and the token request in step 6.

PingData.SSO.OIDC.clientID

OIDC Client ID

Value obtained from the authorization server. This is sent in the authentication request in step 2.

PingData.SSO.OIDC.clientSecret

OIDC Client Secret

Value obtained from the authorization server. This is sent in the token request in step 6.

ldap.server

LDAP Server

Set to the managed PingDirectory server’s hostname and LDAPS port.

Used in step 8 when the administrative console attempts to perform an LDAP bind to the managed PingDirectory server using the OAUTHBEARER SASL mechanism.

The managed PingDirectory server must be configured with the ability to accept LDAPS connections and with the following additional configuration properties.

Configuration requirement Description

A configured ID token validator

For PingOne SSO: the PingOne ID token validator

For general OIDC provider SSO: the OpenID Connect ID token validator

Note:

The ID token validator must be configured with an identity mapper that is able to map the sub value in the token to an LDAP user on the server.

A configured OAUTHBEARER SASL mechanism

Set the mechanism's ID token validator configuration property to the previously configured OIDC ID token validator.

Note:

The OAUTHBEARER SASL mechanism is used in step 8 when the PingDirectory server processes the LDAP bind.

Setting up SSO to the PingDirectory administrative console

To set up SSO using PingOne, see Setting up SSO to PingDirectory from PingOne.

To set up SSO using a generic OP, see Setting up SSO to PingDirectory from a generic OpenID Connect provider.