In this use case, PingFederate is an OAuth client, specifically a relying party (RP) to the OP. PingFederate supports both the Basic Client and the Implicit Client profiles.

The setup involves establishing an IdP connection to the OP. PingFederate retrieves identity information from the OP and passes the end-user claims, which are user attributes in an ID token, to one or more target applications. This configuration allows administrators to take advantage of their existing last-mile integration and expand the horizon of their applications to additional partners using the OpenID Connect protocol.

If the OP supports the OpenID Connect Discovery specification, the connection setup is expedited by loading the metadata from the OP. Based on the discovery specification, PingFederate makes a direct HTTP GET request to the /.well-known/openid-configuration endpoint at the OP and populates the attribute contract and the protocol settings of the connection automatically. Manual adjustments can be made during the connection setup or at a later time.

Additionally, you can refresh the protocol settings by reloading the metadata from the OP at any time. If additional claims are supported, PingFederate adds them to the attribute contract, so that they can be mapped to the target applications later. In the event that the previously supported claims have been dropped by the OP from the metadata, they remain in the attribute contract. While the existing mapping configuration might not be adversely affected, runtime errors might occur if certain attributes are no longer available to the target applications. If runtime errors occur, review the server log and modify the mapping configuration accordingly.

If applicable, administrators can define additional request parameters, which can be included in the authentication requests to support OP-specific use cases. Administrators can restrict the values to those defined in the configuration. Alternatively, administrators can allow the target applications to optionally override the values at runtime. As an added security measure, administrators can protect the requested authentication context, acr_values, and authentication requirement, prompt, so that these parameters in the authentication requests cannot be overridden by the target applications. By default, PingFederate sends these request parameters through multiple query parameters unsigned. Optionally, administrators can configure PingFederate to send request parameters through a request object by value, in which case request parameters are represented by individual claims in a signed JSON Web Token (JWT). When the OP receives the authentication request, it can validate the integrity of the request parameters based on the digital signature in the JWT. For more information, see the section explaining passing a request object by value in the OpenID Connect specification at openid.net/specs/openid-connect-core-1_0.html#RequestObject.

Processing steps

  1. A user starts a browser SSO request at the /sp/startSSO.ping service provider (SP) application endpoint or the /sp/init_login.ping SP protocol endpoint.
  2. The relying party, PingFederate, sends to the OP an authentication request though the browser containing the desired request parameters, such as response_type, scope and redirect_uri, with or without any custom query parameters.
  3. The OP prompts the user to authenticate and authorize, as needed.
  4. The OP sends the user back to PingFederate, at the redirect_uri parameter value, through the browser with an authorization code for the Basic Client profile, or an ID token and an access token if specified in the configuration for the Implicit Client profile.
  5. Applicable only to the Basic Client profile, PingFederate sends a token request with the authorization code to the OP at its token endpoint, directly through a back-channel HTTP POST request. The OP returns to PingFederate an access token and an ID token.
  6. PingFederate validates the ID token.
  7. PingFederate passes the end-user claims to the target application through an SP adapter instance or an authentication policy contract through the browser.

    The access token, if any, can also be passed to the target application, so that API security use cases can be layered on top of the browser-based SSO request.

Note:

If the UserInfo endpoint is included as part of the connection settings and an access token is provided by the OP, PingFederate also retrieves claims from the OP before the last step.

For more information about OpenID Connect, see openid.net/connect.