--- title: Creating an OpenID Connect IdP connection description: In the IdP Connections page, create an OpenID Connect (OIDC) identity provider (IdP) connection to take advantage of your existing last-mile integration. This connection expands your applications to additional partners using the OIDC protocol. component: pingfederate version: 13.0 page_id: pingfederate:administrators_reference_guide:pf_creating_oidc_idp_connection canonical_url: https://docs.pingidentity.com/pingfederate/13.0/administrators_reference_guide/pf_creating_oidc_idp_connection.html revdate: March 13, 2024 page_aliases: ["pf_creat_openid_connect_idp_connect.adoc"] section_ids: steps: Steps choose-from: Choose from: next-steps: Next steps register-pingfederate-with-the-op: Register PingFederate with the OP invoke-single-sign-on-sso: Invoke single sign-on (SSO) manage-connection-status: Manage connection status --- # Creating an OpenID Connect IdP connection In the **IdP Connections** page, create an OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* identity provider (IdP) *(tooltip: \
\

A service that manages identity information and provides authentication services to relying clients or SPs within a federated or distributed network.\

\
)* connection to take advantage of your existing last-mile integration. This connection expands your applications to additional partners using the OIDC protocol. ## Steps 1. In the PingFederate admin console, go to **Authentication > Integration > IdP Connections**, and create a new IdP connection. 2. On the **Connection Type** tab, select the **Browser SSO Profiles** checkbox. 3. In the **Protocol** list, select **OpenID Connect**. | | | | - | ---------------------------------------------------------------------------------- | | | When you select **OpenID Connect**, the other connection types become unavailable. | 4. Click **Next**. 5. On the **Connection Options** tab, you can enable just-in-time (JIT) provisioning, OAuth *(tooltip: \
\

A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server.\

\
)* attribute mapping, or both. OAuth attribute mapping requires the OAuth 2.0 authorization server role. 6. Click **Next**. | | | | - | ---------------------------------------------------------------------------- | | | For simplicity, this topic focuses on managing OIDC IdP connection settings. | 7. On the **General Info** tab, provide the required information, including: * **Issuer** The Issuer Identifier of the OpenID Provider (OP) *(tooltip: \
\

In OAuth terms, an authorization server (AS). The OP/AS issues access tokens to protected resources for approved clients (relying parties). The clients use the access token to access the protected resources hosted by the OAuth resource server.\

\
)*. * **Connection Name** A plain-language identifier for the connection. For example, a company or department name. The admin console displays this name in the connection list. * **Client ID** The client ID to communicate with the OP. This client represents PingFederate. The OP creates and manages this client at the OP. Learn more in the documentation provided by the OP. * **Client Secret** The client secret to communicate with the OP. This applies only when the client representing PingFederate supports the Basic Client profile. Learn more in [step 10](#pf_step_configureOpenIdProviderInfo). 1. (Optional) Click **Load Metadata**. | | | | - | ------------------------------------------------------------------------------------------------------------------------------ | | | Loading metadata from the OP expedites the connection setup. You can also update an existing connection by reloading metadata. | 8. Click **Next**. 9. On the **Browser SSO** tab, click **Configure Browser SSO**. 10. On the **User-Session Creation** tab, click **Configure User-Session Creation**. 11. On the **Identity Mapping** tab, choose from the following options: ### Choose from: * Select the **No Mapping** checkbox if you plan to pass end-user claims to the target application. You pass these claims through an authentication policy contract in an service provider (SP) *(tooltip: \
\

In SAML, an entity that receives and accepts an authentication assertion issued by an IdP, typically for the purpose of allowing access to a protected resource.\

\
)* authentication policy. * Select the **Account Mapping** checkbox if you plan to pass end-user claims to the target application through an SP adapter instance or an authentication policy contract. Use this if your PingFederate server is a federation hub that bridges an OP to an SP. * Select the **Account Linking** checkbox if your target application requires account linking. | | | | - | ---------------------------------------------------------------------------------------------------------- | | | End-user claims are user attributes found in ID tokens or obtained from the `UserInfo` endpoint at the OP. | This topic uses the **Account Mapping** configuration as an example. 12. On the **Attribute Contract** tab, extend the attribute contract. To mask the attribute values in the log, select the relevant checkbox for each applicable end-user claim. | | | | - | ------------------------------------------------------------------------------------------------------------------- | | | If you loaded the metadata from the OP on the **General Info** tab, the attribute contract populates automatically. | 13. Click **Next**. 14. On the **Target Session Mapping** tab, click **Map New Adapter Instance**. This maps end-user claims to the target application through an SP adapter instance or an authentication policy contract. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------- | | | The **Target Session Mapping** configuration does not apply when you select the **No Mapping** option on the **Identity Mapping** tab. | 15. Follow the admin 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. 16. On the **Adapter Contract Fulfillment** tab, select `Provider Claims` from the **Source** list to map the attribute to an end-user claim. 17. 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 [step 10](#pf_step_configureOpenIdProviderInfo). The OP returns an access token and an ID token as part of the authentication and authorization flow. | 18. Click **Done**. 19. To save the connection settings and go to the **Protocol Settings** tab, click **Done**. 20. On the **Protocol Settings** tab, click **Configure Protocol Settings**. 21. 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 checkbox for Enable Proof Key for Code Exchange, which is selected.](_images/jil1678988834376.png) | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you clicked **Load Metadata** from the OP on the **General Info** tab, the system pre-populates the **Scopes** field and all endpoints if the metadata contains the information. | | Field | Description | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Scopes** | The scopes to include in the OIDC 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`. You can find a list of OIDC defined scopes in the Requesting Claims using Scope Values section of the OpenID Connection specification. | | **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 OIDC client profile. The OP creates and manages this client, which represents PingFederate.- If the client supports the Basic Client profile, select **Code**. The resulting value of the `response_type` parameter is `code`. - If the client supports the Implicit Client profile, select **Form POST**. The resulting value of the `response_type` parameter is `id_token`. - If the client supports 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` and `token`.The default selection, without loading metadata from the OP, is **Code**. | | **JWT Secured Authorization Response Mode (JARM)** | IdP connections support JARM when sending authorization requests as a relying party (RP) *(tooltip: \
\

An OAuth 2.0 client that requires end-user's authenticity and claims (attributes) from an OpenID provider.\

\
)* to the OP.These values map to:- **Disabled**: The OP does not encode authorization responses using JARM. This is the default value. - **Query JWT**: `query.jwt` - **Form Post JWT**: `form_post.jwt` You should only use Query JWT when the OpenID Connect Login Type is set to Code. Use it with other types only if the response JSON Web Token (JWT) is encrypted to prevent token leakage in the URL. | | **Authentication Scheme** | The client authentication method that PingFederate uses. This applies and is 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. Learn more in [Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) in the OpenID Connect specification. - Select **Client Secret JWT** to authenticate with the `client_secret_jwt` Client Authentication method. Learn more in [Client Authentication](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) in the OpenID Connect specification.The default selection, without loading metadata from the OP, is **Basic**. | | **Authentication Signing Algorithm** | If you choose **Private Key JWT** or **Client Secret JWT** as the authentication scheme, select the algorithm that PingFederate uses to sign the JWT *(tooltip: \
\

An IETF standard container format for a JSON object used for the secure exchange of content, such as identity or entitlement information. You can find the industry standard in \RFC 7519\.\

\
)*.If PingFederate is deployed to run in a Java 8 or Java 11 runtime environment, or is integrated with a g and configured to use static keys for OAuth and OIDC, additional RSASSA-PSS signing algorithms become available to select. Learn more about HSM integration and static keys in [Supported hardware security modules](../getting_started_with_pingfederate/pf_supported_hardware_security_modules.html) and [Keys for OAuth and OpenID Connect](help_jwksendpointtasklet_jwksendpointkeysstate.html). If you enable static keys for OAuth and OIDC, the system hides elliptic-curve cryptography (ECC) algorithms lacking active static keys. Changes made in the static-key configuration might affect runtime transactions and require additional changes to the Authentication Signing Algorithm selection. Learn more in 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 \/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. Learn more in 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 checkbox to enable PingFederate to send a SHA256 code challenge and corresponding code verifier to the OP. It sends these as a Proof Key for Code Exchange (PKCE) during the authorization code flow\.This checkbox applies and is visible only when the **OpenID Connect Login Type** is **Code**. When you click Load Metadata on the General Info tab, PingFederate displays the Enable PKCE checkbox 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. Learn more about the PAR protocol in [OAuth 2.0 Pushed Authorization Requests](https://datatracker.ietf.org/doc/html/rfc9126) 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 system prepopulates the Pushed Authorization Request Endpoint field if the metadata contains the information. 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. Learn more in [openid.net/connect](https://openid.net/developers/connect/).- Token Endpoint The **Token Endpoint** field is only visible and required for clients supporting the Basic Client profile. This applies when the **OpenID Connect Login Type** field is set to **Code**. - UserInfo Endpoint The **UserInfo Endpoint** field is optional. If you omit it, 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 an HSM and a static-key configuration for OAuth and OIDC.Learn more about HSM integration and static keys in [Supported hardware security modules](../getting_started_with_pingfederate/pf_supported_hardware_security_modules.html) and [Keys for OAuth and OpenID Connect](help_jwksendpointtasklet_jwksendpointkeysstate.html), respectively. 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 checkbox to send request parameters as claims in a request object. This is a self-contained, signed JWT sent 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. Learn more about passing a request object by value in the [OpenID Connect specification](https://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 checkbox is cleared by default. If cleared, PingFederate sends request parameters with multiple query parameters, unsigned. | | **Request Signing Algorithm** | Select the algorithm that PingFederate uses to sign the request object.This applies and is visible only when you select the **Sign Request** checkbox.If PingFederate is deployed to run in a Java 8 or Java 11 runtime environment, or is integrated with an HSM and configured to use static keys for OAuth and OIDC, additional RSASSA-PSS signing algorithms are available for selection. Learn more about HSM integration and static keys in [Supported hardware security modules](../getting_started_with_pingfederate/pf_supported_hardware_security_modules.html) and [Keys for OAuth and OpenID Connect](help_jwksendpointtasklet_jwksendpointkeysstate.html). 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 JWK based on the selected signing algorithm from its JWKS. 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 JWKs. The PingFederate JWKS URL is located at \/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. Learn more in OpenID Provider configuration endpoint. | | **Track User Sessions for Logout** | When selected, PingFederate tracks logout entries in the user session to handle and initiate logout requests. Additionally, 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 checkbox is cleared by default. | | **Logout Endpoint** | The endpoint where PingFederate redirects the user to terminate their session at the OpenID Provider. This field displays only if you select **Track User Sessions for Logout**. When you populate this field, the **IdP Connection** window's **Activation & Summary** tab displays the connection's **Post-Logout Redirect URI**. | On the **OpenID Provider Info** tab, in the **Request Parameters** section, specify the request parameters allowed in the authentication requests to the OP. Learn more in [Configuring request parameters and SSO URLs](pf_config_request_parameter_sso_url.html). 22. (Optional) On the **Overrides** tab, specify a default target URL and authentication context overrides. 23. On the **Activation & Summary** tab, review your connection settings. When you finish setting up a connection, you can activate it immediately. You can deactivate a connection at any time. When a connection is inactive, all transactions to or from this partner are disabled. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | 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. | ## Next steps After saving the connection, complete the following registration and integration tasks. ### Register PingFederate with the OP In this use case, because PingFederate acts as an OAuth client, you are likely required by the authorization server at the OP to register the following URIs. You can find these URIs on the **Summary & Activation** tab: * **Redirect URI** * **Front-Channel Logout URI** * **Back-Channel Logout URI** * **Post-Logout Redirect URI** This registration must be associated with the client representing PingFederate that you provided on the **General Info** tab. Learn more in the documentation provided by your OP. ### Invoke single sign-on (SSO) You can invoke single sign-on (SSO) *(tooltip: \
\

The process of authenticating an identity (signing on) at one website (usually with a user ID and password) and then accessing resources secured by other domains without reauthenticating.\

\
)* for the connection using the following endpoints: * **SSO Application Endpoint**: Use the sample URL at the `/sp/startSSO.ping` application endpoint. Webmasters or developers can use this to initiate SSO. Learn more about supported parameters in [Viewing SP application endpoints](pf_viewing_sp_applicat_endpoints.html). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | If you selected the **No Mapping** option on the **Identity Mapping** tab, the **Summary & Activation** tab does not display the **SSO Application Endpoint** sample URL. | * **SP Protocol Endpoint**: Target applications can also invoke SSO requests by contacting the `/sp/init_login.ping` protocol endpoint. Learn more in [Configuring request parameters and SSO URLs](pf_config_request_parameter_sso_url.html). ### Manage connection status You can deactivate a connection at any time. When a connection is inactive, all transactions to or from this partner are disabled.