Creating an OpenID Connect IdP connection

In the IdP Connections window, create an OpenID Connect (OIDC) identity provider (IdP) connection to take advantage of your existing last-mile integration and expand the horizon of your applications to additional partners using the OpenID Connect protocol.

Steps

Go to Authentication → Integration → IdP Connections, and then create a new IdP connection.
On the Connection Type tab, select the Browser SSO Profiles check box, and in the Protocol list, select OpenID Connect. Click Next.

When OpenID Connect is the chosen protocol, the other types become unavailable.
On the Connection Options tab, you can enable just-in-time (JIT) provisioning, OAuth attribute mapping, which requires the OAuth 2.0 authorization server role, or both. Click Next.

For simplicity, this topic focuses on managing OpenID Connect IdP connection settings.
On the General Info tab:
1. Provide the required information, including:
  
  Issuer
  
  The Issuer Identifier of the OpenID Provider (OP).
  
  Connection Name
  
  A plain-language identifier for the connection; for example, a company or department name. This name is displayed in the connection list on the administrative console.
  
  Client ID
  
  The client ID to communicate with the OP.
  
  This client represents PingFederate and is created and managed at the OP. For more information, see the documentation provided by the OP.
  
  Client Secret
  
  The client secret to communicate with the OP.Applicable only when the client representing PingFederate supports the Basic Client profile. For more information, see [pf_step_configureOpenIdProviderInfo].
2. Optional: Click Load Metadata.
  
  Loading metadata from the OpenID Provider (OP) expedites the connection setup. You can also update an existing connection by reloading metadata.
On the Browser SSO tab, click Configure Browser SSO.
On the User-Session Creation tab, click Configure User-Session Creation.
On the Identity Mapping tab, you have three choices:

Choose from:
- Select the No Mapping check box if you plan on passing end-user claims to the target application through an authentication policy contract in an SP authentication policy.
- Select the Account Mapping check box if you plan on passing end-user claims to the target application through an SP adapter instance or an authentication policy contract if your PingFederate server is a federation hub that bridges an OP to an SP.
- Select the Account Linking check box if your target application requires account linking.
  
  End-user claims are basically user attributes found in ID tokens or obtained from the UserInfo endpoint at the OP.
For illustration, this topic uses the Account Mapping configuration.
On the Attribute Contract tab, extend the attribute contract.

To mask the attribute values in the log, select the relevant check box for each applicable end-user claim.

If you have chosen to load the metadata from the OP on the General Info tab, the attribute contract is populated automatically.

On the Target Session Mapping tab, click Map New Adapter Instance to map end-user claims to the target application through an SP adapter instance or an authentication policy contract.

Follow the administrative console to fulfill the SP adapter contract or the authentication policy contract. Like other IdP connections, you can query additional attributes from a datastore, specify issuance criteria, or both. When mapping an attribute, select Provider Claims from the Source list to map the attribute to an end-user claim.

If your target application requires the associated access token, select Context as the source and Access Token as the value.

If the client representing PingFederate supports the Basic Client profile, PingFederate always receives an access token from the OP to retrieve an ID token.

If the client supports the Implicit Client profile, you must select the Form POST with access token option in [pf_step_configureOpenIdProviderInfo], such that the OP will return an access token and an ID token as part of the authentication and authorization flow.

The Target Session Mapping configuration does not apply when the No Mapping option is selected on the Identity Mapping tab.

On the Protocol Settings tab, click Configure Protocol Settings.

On the OpenID Provider Info tab, provide the scopes, the endpoints, and the authentication scheme.

Screen capture of the OpenIDProvider Info tab. There are fields for Scopes, Authorization Endpoint, OpenID Connect Login Type, Authentication Scheme, Authentication Signing Algorithm, Enable Proof Key for Code Exchange. OpenID Connect Login has Code selected. Authentication Scheme has Client Secret JWT selected. The text field for Authentication Signing Algorithm is filled in with the value HMAC using SHA-256. There is a check box for Enable Proof Key for Code Exchange, which is selected.

If you clicked Load Metadata from the OpenID Provider (OP) on the General Info tab, the Scopes field and all endpoints are pre-populated, provided that the metadata contains the information.

Field Description

Scopes

The scopes to be included in the OpenID Connect authentication and OAuth token requests to the OP. Multiple space-separated values are allowed.

The default value, without loading metadata from the OP, is openid.

For a list of OpenID Connect defined scopes, see the section about requesting claims using scope values in the OpenID Connection specification at openid.net/specs/openid-connect-core-1_0.html#ScopeClaims.

Authorization Endpoint

The authorization endpoint at the OP.

You can enter a relative path, starting with a forward slash, if you provide base URL on the General Info tab.

There is no default value without loading metadata from the OP.

OpenID Connect Login Type

The OpenID Connect client profile of the client. This client represents PingFederate and is created and managed at the OP.

If the client is configured to support the Basic Client profile, select Code.

The resulting value of the response_type parameter is code. * If the client is configured to support the Implicit Client profile, select Form POST.

The resulting value of the response_type parameter is id_token. * If the client is configured to support the Implicit Client profile and the target application requires the associated access token, select Form POST with access token.

The resulting values of the response_type parameter are id_token token.

The default selection, without loading metadata from the OP, is Code.

JWT Secured Authorization Response Mode (JARM)

JARM is supported when sending authorization requests as a relying party to the OpenID Provider using IdP Connections.

These values map to:

Disabled: Authorization responses will not be encoded using JARM. This is the default value.
Query JWT: query.jwt
Form Post JWT: form_post.jwt

You should only use Query JWT with OpenID Connect Login Type Code unless the response JWT is encrypted to prevent token leakage in the URL.

Authentication Scheme

The client authentication method that PingFederate uses. Applicable and visible only to clients supporting the Basic Client profile.

Select Basic to submit credentials with HTTP Basic authentication.
Select POST to submit credentials with POST.
Select Private Key JWT to authenticate with the private_key_jwt Client Authentication method. For more information, see Client Authentication in the OpenID Connect specification.
Select Client Secret JWT to authenticate with the client_secret_jwt Client Authentication method. For more information, see Client Authentication in the OpenID Connect specification.

The default selection, without loading metadata from the OP, is Basic.

Authentication Signing Algorithm

If Private Key JWT or Client Secret JWT is the chosen authentication scheme, select the algorithm that PingFederate uses to sign the JSON Web Token (JWT).

If PingFederate is deployed to run in a Java 8 or Java 11 runtime environment, or is integrated with a hardware security module (HSM) and configured to use static keys for OAuth and OIDC, additional RSASSA-PSS signing algorithms become available for selection. For more information on HSM integration and static keys, see Supported hardware security modules and Keys for OAuth and OpenID Connect.

If static keys for OAuth and OpenID Connect are enabled, Elliptic-curve cryptography (EC) algorithms that have not been configured with an active static keys are hidden.

Changes made in the static-key configuration might affect runtime transactions and require additional changes here. For more information, see Keys for OAuth and OpenID Connect.

Based on the chosen signing algorithm, PingFederate selects the signing JSON Web Key (JWK) from its JWK Set (JWKS) at runtime.

For the OP to validate the signed JWT, ensure that the OP can access the PingFederate JWKS endpoint, which returns the current JWKS. The PingFederate JWKS endpoint is located at <Base URL>/pf/JWKS, where Base URL is defined on System → Server → Protocol Settings → Federation Info.

For example, if the Base URL field value is https://www.example.com, the PingFederate JWKS endpoint is https://www.example.com/pf/JWKS. You can pass the PingFederate JWKS endpoint directly to the OP or have the OP contact the PingFederate OP configuration endpoint to obtain the information.

For more information, see OpenID Provider configuration endpoint.

If Client Secret JWT is the chosen authentication scheme, the signing algorithms are HS256, HS384, and HS512.

Enable Proof Key for Code Exchange (PKCE)

Select this check box to enable PingFederate to send a SHA256 code challenge and corresponding code verifier as a Proof Key for Code Exchange (PKCE) to the OP during the Code authentication flow.

This check box is applicable and visible only when the OpenID Connect Login Type is Code.

When Load Metadata on the General Info tab is clicked, PingFederate displays the Enable PKCE check box if S256 is listed as a supported method in the code_challenge_methods_supported by the OP.

Pushed Authorization Request Endpoint

The Pushed Authorization Request (PAR) endpoint at the OP. When you configure a PAR endpoint, the IdP connection sends authorization requests directly to this endpoint. All parameters associated with an authorization request are transmitted to the PAR endpoint. For more information about the PAR protocol, see OAuth 2.0 Pushed Authorization Requests on the IETF website.

You can enter the relative path, /par, starting with a forward slash if you provide the base URL on the General Info tab.

If you clicked Load Metadata from the OP on the General Info tab, the Pushed Authorization Request Endpoint field is pre-populated, provided that the metadata contains the information. As such, PAR requests are the new default behavior.

Token Endpoint, UserInfo Endpoint, and JWKS URL

OAuth 2.0 and OpenID Connect 1.0 endpoints at the OP. For more information, see openid.net/connect.

Token Endpoint: The Token Endpoint field is only visible and required for clients supporting the Basic Client profile. In other words, the OpenID Connect Login Type field is set to Code.
UserInfo Endpoint: The UserInfo Endpoint field is optional. If omitted, PingFederate only has access to the end-user claims from the ID tokens.
JWKS URL: The JWKS URL is required for PingFederate to validate the inbound ID tokens from the OP. If the OP signs its JWTs using an RSASSA-PSS signing algorithm, PingFederate must be deployed to run in a Java 8 or Java 11 runtime environment, or integrated with a hardware security module (HSM) and a static-key configuration for OAuth and OpenID Connect. include:::partial$pf_rc_hsm_integration.adoc[tags=pf_ph_seeSupportedSecurityModulesAndStaticKeys].The JWKS URL is also required to validate the JARM response.

There are no default values without loading metadata from the OP.

Sign Request

Select this check box to send request parameters as claims in a request object, a self-contained, signed JWT as one request query parameter to the OP.

When this optional configuration is enabled, the OP can validate the integrity of the request parameters based on the digital signature found in the signed 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.

When this optional configuration is enabled, the JWT signed request object includes the jti (JWT ID) value.

This check box is not selected by default, in which case PingFederate sends request parameters with multiple query parameters, unsigned.

Request Signing Algorithm

Select the algorithm that PingFederate uses to sign the request object.

Applicable and visible only when the Sign Request check box is selected.

If static keys for OAuth and OpenID Connect are enabled, Elliptic-curve cryptography (EC) algorithms that have not been configured with an active static keys are hidden.

Changes made in the static-key configuration might affect runtime transactions and require additional changes here. For more information, see Keys for OAuth and OpenID Connect.

PingFederate automatically selects the signing JSON web key (JWK) based on the selected signing algorithm from its JWK Set (JWKS).

In order for the OP to validate the signed request object, ensure that the OP can access your PingFederate’s JWKS URL, which returns the current set of JSON web keys. The PingFederate JWKS URL is located at <Base URL>/pf/JWKS, where Base URL is defined on System → Server → Protocol Settings → Federation Info.

For example, if the Base URL field value is https://www.example.com, the PingFederate JWKS URL is https://www.example.com/pf/JWKS. You can pass the JWKS URL directly to the OP or have the OP contact the PingFederate OpenID Provider configuration endpoint for it. For more information, see OpenID Provider configuration endpoint.

Track User Sessions for Logout

When selected, PingFederate tracks logout entries in the user session so that PingFederate can handle and initiate logout requests. Also, when selected, the Logout Endpoint field is displayed, and the IdP Connection window’s Activation & Summary tab displays the connection’s Front-Channel Logout URI and Back-Channel Logout URI. The check box is cleared by default.

Logout Endpoint

The endpoint to which PingFederate will redirect the user in order to terminate their session at the OpenID Provider. This field is only displayed if Track User Sessions for Logout is selected. When this field is populated, theIdP Connection window’s Activation & Summary tab displays the connection’s Post-Logout Redirect URI.

+ Remain on the OpenID Provider Info tab and specify the request parameters that are allowed to be included in the authentication requests to the OP under Request Parameters. For more information, see Configuring request parameters and SSO URLs.

Optional: On the Overrides tab, specify a default target URL and authentication context overrides.
On the Activation & Summary tab, review your connection settings.

When you finish setting up a connection, you can choose to activate it immediately.

Regardless of whether you choose to activate a new connection now or later, you must click Save on the Summary & Activation tab for a new connection if you want to keep the configuration.

You can deactivate a connection at any time. When a connection is inactive, all transactions to or from this partner are disabled.

In this use case, because PingFederate is an OAuth client, you are likely required by the authorization server at the OP to register the Redirect URI, Front-Channel Logout URI, Back-Channel Logout URI, and Post-Logout Redirect URI as shown on the Summary & Activation tab. This registration should be associated with the client that represents PingFederate, the client that you have provided on the General Info tab. For more information, see the documentation provided by the OP.

The SSO Application Endpoint provides a sample URL at the /sp/startSSO.ping application endpoint that webmasters or web application developers at your site can use to invoke single sign-on (SSO) for the connection. For a list of supported parameters, see Viewing SP application endpoints.

If you have selected the No Mapping option on the Identity Mapping tab, the Summary & Activation tab does not show the SSO Application Endpoint sample URL.

The target application can also invoke SSO requests by contacting the /sp/init_login.ping SP protocol endpoint. For more information, see Configuring request parameters and SSO URLs.

PingFederate Server

Creating an OpenID Connect IdP connection

Steps

Choose from: