PingDirectory

Single sign-on with the admin console

The OpenID Connect (OIDC) protocol enables single sign-on (SSO) with the PingDirectory server admin console using either PingOne, PingFederate, or a custom authorization server.

Overview of OpenID Connect

OIDC is a protocol that allows a client application called a relying party (RP) to confirm that a user is who they say they are by contacting an authorization server called an OpenID Provider (OP).

The authorization code flow

The PingDirectory server admin console uses the authorization code flow implementation of the protocol.

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

A workflow diagram of the following numbered steps in the authorization code flow.

  1. The PingDirectory server admin console (RP) prepares an authentication request containing the desired request parameters.

  2. The admin 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 admin console with an authorization code.

  6. The admin console (RP) requests a response using the authorization code at the token endpoint.

  7. The admin console (RP) receives a response that contains an ID token and access token in the response body.

  8. The admin console attempts to use the tokens to perform an Lightweight Directory Access Protocol (LDAP) bind with the server (RP) through the OAUTHBEARER SASL mechanism. While establishing this LDAP bind, the server (RP) validates the tokens.

Configuring OIDC with the PingDirectory server admin 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.

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 admin console must be configured with the following settings in the application.yml file, which is located in PingDirectory/tmp/console/webapp/WEB-INF/classes.

If doing this in DevOps, none of these settings will have any effect and the changes must be done through the profile.
application.ymlconfiguration name Embedded console setting name Settings required

PingData.SSO.OIDC.enabled

SSO Enabled

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

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 admin 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 PingFederate SSO or a general OIDC provider: the OIDC ID token validator.

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.

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

Setting up SSO to the PingDirectory admin console