Integrating an OIDC application

After you Add or update an OIDC application, you need to integrate it with PingOne SSO for SaaS Apps.

Before you begin

See Adding or updating an OIDC application to add an application to PingOne SSO for SaaS Apps.

About this task

When you integrate an OpenID Connect (OIDC) application, PingOne SSO for SaaS Apps will act as the OAuth provider for your application. Your application then needs to request authorization from the PingOne SSO for SaaS Apps OAuth authorization endpoint when users attempt to single sign-on (SSO) to the application.

See the OpenID Connect Core 1.0 specification for reference when integrating the application.

The authorization request flow depends on the grant type you have selected for the application. The grant type can be Authorization code, Implicit, or a hybrid (both code and implicit).

For more information, see OIDC application grant types.

Steps

Go to Applications → My Applications → OIDC.
Expand the details to display the summary page for the OIDC application to integrate.

Result:

The unique Client ID and Discovery URL for the application is displayed in the Details section.
Copy the Discovery URL and enter it in a new browser tab.

Result:

PingOne SSO for SaaS Apps returns OIDC configuration information, including the endpoints you will use to integrate the application.

Code
Implicit
Hybrid

Code grant type

For any grant type, the application needs to send the authorization request to the PingOne SSO for SaaS Apps authorization endpoint returned by the Discovery URL(https://sso.connect.pingidentity.com/sso/as/authorization.oauth2).

PingOne SSO for SaaS Apps sends the response to the authorization request to the URL you assigned to the Redirect (Callback) URI setting when you created the application. You can find this URL in the Authentication Flow section on the application summary page.

PingOne SSO for SaaS Apps validates the redirect_uri parameter against the list of redirect URIs specified in the application’s configuration. You can find these URIs in the Authentication Flow section on the application summary page. If the redirect_uri is valid, PingOne SSO for SaaS Apps sends the response to the specified redirect URI.

If your application uses an authorization code grant type, PingOne SSO for SaaS Apps uses the following process to complete the authorization request:

The application sends an authorization request for a code grant type.

Here is an example of an authorization request URI:

https://sso.connect.pingidentity.com/sso/as/authorization.oauth2?client_id=cdd237bb-3404-4ad4-90eb-d2e2528xxxxx&scope=openid&response_type=code

The following table describes the parameters that make up the authorization request URI.

Parameter Description

client_id

Your client ID, assigned by PingOne for Enterprise. You can find this value on the Details tab.

scope

The user resources that can be accessed by the application. The openid scope is expected to be specified, either as the sole scope value or one of the scope values.

response_type

This must be code. An authorization code is then returned in the response.

code_challenge

This PKCE parameter is either plain text or a cryptographic hash of a random string. The random string or plain text must be a code_verifier value that you will include in the subsequent token request.

Use PKCE only when you aren’t using a client secret, including client_secret in the token request.

For more information, see OAuth 2.0 RFC 7636.

code_challenge_method

This PKCE parameter is required only when code_challenge is specified.

This can be either:

plain When the code_challenge_method value is plain text
S256 When the code_challenge_method value is an SHA-256 cryptographic hash

When you subsequently include the code_verifier value in the token request, the code_challenge value and the code_verifier value must match.

For more information, see OAuth 2.0 RFC 7636.

login_hint

Used to specify either the idpid or an email domain.

If you specify the idpid, the user is redirected to the IdP associated with the idpid value for the current application, identified in PingOne SSO for SaaS Apps by the saasid parameter.

If you specify an email domain as the login_hint value, the domain must be included in the IdP Discovery configuration for the application and tenant.

For more information about IdP Discovery for your connection type, see:

The PingOne for Enterprise authorization endpoint returns the authorization code to the application.

The HTTPS response will be similar to this:
```
https://example.com/#code=IDa4e54a98b90b234476819295a791e4a95bbb9a6e1a3095b50200000164fbeb8b43
```
The application uses the authorization code returned in the response to request an access token and ID token from the PingOne for Enterprise token endpoint, https://sso.connect.pingidentity.com/sso/as/token.oauth2.

Here is an example request using cURL:
```
curl -k -X POST -H "Accept: application/json" -d 'client_id=cdd237bb-3404-4ad4-90eb-d2e2528xxxxx&client_secret=CpquMknCg9An9Up1Ys2mnVEdKkCDaxtJcJG4adFPBDnPU6SBp7VNGUhyTmaJXXmpR&grant_type=authorization_code&code=ID5d7d1770409374639980ce161952fda57b21db562ff8320b020000016543fxxxxx&redirect_uri=https://example.com\' https://sso.connect.pingidentity.com/sso/as/token.oauth2
```
Because the authorization request did not include PKCE parameters, the token request must use the client secret value assigned when the application was added to PingOne SSO for SaaS Apps. You can find the assigned client secret in the Details tab.
The application validates the id_token returned. For more information see the OpendID Connect Core 1.0 specifications.
The application can also optionally validate the token or access token returned.

Use the PingOne for Enterprise introspection endpoint returned by the Discovery URL https://sso.connect.pingidentity.com/sso/as/introspect.oauth2 to validate the access token.

For access tokens that are signed rather than encrypted, you can also use the JWKS URI returned by the Discovery URL https://sso.connect.pingidentity.com/sso/as/jwks.

You can see your access token settings at Applications → My Applications → OAuth Settings.

For more information, see Configuring your OAuth settings.

Implicit grant type

If your application uses an authorization implicit grant type, PingOne SSO for SaaS Apps uses the following process to complete the authorization request:

The application sends an authorization request for an implicit grant type.

Here is an example of an authorization request URI:

https://sso.connect.pingidentity.com/sso/as/authorization.oauth2?client_id=930bc6bc-4bee-4ad4-90eb-d2e2528xxxxx&scope=openid&response_type=id_token%20token&nonce=Q4CLVJYiQbfLKoEovYyg

The following table describes the parameters that make up the authorization request URI.

Parameter Description

client_id

Your client ID, assigned by PingOne SSO for SaaS Apps. You can find this value on the Details tab.

scope

The user resources that can be accessed by the application. The openid scope is expected to be specified, either as the sole scope value or one of the scope values.

When openid is not specified and the response_type value indicates id_token, an id_token is not returned.

response_type

This can either be id_token, token (access token), or both. The token or tokens specified are returned in the response.

nonce

This is used to securely associate client_id with id_token.

For more information, see OpenID Connect Core 1.0 Nonce Implementation Notes.

login_hint

Used to specify either the idpid or an email domain.

If you specify the idpid, the user is redirected to the IdP associated with the idpid value for the current application, identified in PingOne SSO for SaaS Apps by the saasid parameter.

If you specify an email domain as the login_hint value, the domain must be included in the IdP Discovery configuration for the application and tenant.

For more information about IdP Discovery for your connection type, see:

The PingOne SSO for SaaS Apps authorization endpoint returns the response_type value to the application.

If you included id_token and token in the authorization request, as in the example, an access token is returned with the id_token value in the response.

The HTTPS response will be similar to this:

https://example.com/#access_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjQ4RUU0RjNGRDEyQTcwMUFERjYzMzEwMTRENzIzMzUyRDE3QjBFNUUifQ.eyJzdWIiOiJtZG9yZXkrYWRtaW5hdWRpdEBwaW5naWRlbnRpdHkuY29tIiwiaWRwaWQiOiIyNGFkOWJjNi1hNjlmLTQ0OTgtYTliZS0yNTgxMjZiZWFhNmYiLCJzY29wZSI6Im9wZW5pZCIsImlzcyI6Imh0dHBzOi8vdGVzdC1zc28uY29ubmVjdC5waW5naWRlbnRpdHkuY29tL2NkZDIzN2JiLTM0MDQtNGFkNC05MGViLWQyZTI1MjgwODAzNyIsIm1lbWJlck9mIjpbIkRvbWFpbiBBZG1pbmlzdHJhdG9yc0BkaXJlY3RvcnkiLCJVc2Vyc0BkaXJlY3RvcnkiLCJQSU5HT05FLkNMT1VELkRJUkVDVE9SWS5HUk9VUC5VSS5FTlRJVExFTUVOVC5PS1JHU0tZSFhSR0ZLSkdCTk9HSUtSU0FaWlFKTllGQ01LSEZVTE1KUFRGUkJJIl0sImV4cCI6MTUzMzgzMjQyMSwianRpIjoiSURhNTdlZjIzZmI4OTA5ZDQ1MTAwODgyYTg5ZDI5ZDU2Y2ZkZjk4MWZjNmQ3ZmUyYzYwMjAwMDAwMTY1MWY4OTVlYTAiLCJjbGllbnRfaWQiOiJjZGQyMzdiYi0zNDA0LTRhZDQtOTBlYi1kMmUyNTI4MDgwMzcifQ.653sxLCeTx8u_QD84fTPv8guFjir2iDylqi9vV2t-O6F_HfPJCank7IqWv50V7Apum3BnDpD1OBJtwlHNFmb2NGDgydDEegCCrlaEfHNjTogiqGISdoDsPAbUGWelRoGRrYmNt-aJGACwqqfiVVVRux7DARB8rF4opMwXRJM3FmjuA3_hVDbldl48NoA3TGJukmWg-2risFxUTuFnQmHgv1JZQhSiCH30YJtIleih9J1XnvrtHxCRAKDn83a6SYYUkc4SubfoLsjQMPbx8RO25SDVgJM_5CgdQGQp3AMZeAcZu8oFmFsoD1RZWphlkgenLyNGA0aht_1VlZ6MeAW6Q&token_type=Bearer&id_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjQ4RUU0RjNGRDEyQTcwMUFERjYzMzEwMTRENzIzMzUyRDE3QjBFNUUifQ.eyJhdF9oYXNoIjoia1hsTE1LM2cyQWxZSE42MEY2SVJjdyIsInN1YiI6Im1kb3JleSthZG1pbmF1ZGl0QHBpbmdpZGVudGl0eS5jb20iLCJhdWQiOiJjZGQyMzdiYi0zNDA0LTRhZDQtOTBlYi1kMmUyNTI4MDgwMzciLCJhY3IiOiJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZCIsImlkcGlkIjoiMjRhZDliYzYtYTY5Zi00NDk4LWE5YmUtMjU4MTI2YmVhYTZmIiwiYXV0aF90aW1lIjoxNTMzODI4NTg0LCJpc3MiOiJodHRwczovL3Rlc3Qtc3NvLmNvbm5lY3QucGluZ2lkZW50aXR5LmNvbS9jZGQyMzdiYi0zNDA0LTRhZDQtOTBlYi1kMmUyNTI4MDgwMzciLCJleHAiOjE1MzM4MjkxMjEsImlhdCI6MTUzMzgyODgyMSwibm9uY2UiOiJRNENMVkpZaVFiZkxLb0Vvdll5ZyIsImVtYWlsIjoibWRvcmV5K2FkbWluYXVkaXRAcGluZ2lkZW50aXR5LmNvbSJ9.HFNygcG4R26DpMsucfqjjbu53dZH7f_Tk1HH5aw1LziHTXMdiuT9F8lJDr3qLEVQcOe_Hy4MWTo4KrXHm6zQ31mW9bOiNQCl2RONxh83kGT_Z5X276fsMCNlUVeOxZyhJnHbXXLz8iAestf9LJ7r5R2eFM-te2W-sc3RcelpRAIUi6lbBmmDrj2cvaTThSVzin-8Ho9PAZTJcUHHLnyPyOxFgaN7OO8T1WRCsEc_loCuTNdyYThxbepkd1m8Q9BwcK3w-VG0GEomQI4yKDp7FvqDjt4pbupMWjSujBYwDjARdL05nUAvvWFnXrNMaYY0aWxm793qG-VlXhm1WYmLgA

If an id_token was included in the authorization request, the application validates the id_token returned.

For more information, see the OpenID Connect Core 1.0 specifications.
The application can also optionally validate the token (access token) returned.

Use the PingOne SSO for SaaS Apps introspection endpoint returned by the Discovery URL https://sso.connect.pingidentity.com/sso/as/introspect.oauth2 to validate the access token.

For access tokens that are signed rather than encrypted, you can also use the JWKS URI returned by the Discovery URL https://sso.connect.pingidentity.com/sso/as/jwks.

You can see your access token settings at Applications → My Applications → OAuth Settings.

For more information, see Configuring your OAuth settings.

Hybrid grant type

If your application uses both code and implicit grant types, PingOne SSO for SaaS Apps uses the following process to complete the authorization request:

Your applications sends an authorization request for a hybrid grant type.

Here’s an example of an authorization request URI:

https://sso.connect.pingidentity.com/sso/as/authorization.oauth2?client_id=cdd237bb-3404-4ad4-90eb-d2e2528xxxxx&scope=openid&response_type=code%20id_token%20token&nonce=Q4CLVJYiQbfLKoEovYyg

The following table describes the parameters contained in the authorization request URI.

Parameter Description

client_id

Your client ID, assigned by PingOne SSO for SaaS Apps. You can find this value on the Details tab.

scope

The user resources that can be accessed by the application. The openid scope is expected to be specified, either as the sole scope value or one of the scope values.

When openid is not specified and the response_type value indicates id_token, an id_token is not returned.

response_type

This can be any or all of the following:

code
id_token (as in the above example)
token (access token)

The specified tokens are returned in the response along with the authorization code.

nonce

Required when id_token is included in response_type. It is used to securely associate client_id with id_token.

For more information, see OpenID Connect Core 1.0 Nonce Implementation Notes.

code_challenge

This PKCE parameter is either plain text or a cryptographic hash of a random string. The random string or the plain text must be the code_verifier value that you will include in the subsequent token request.

Use PKCE only when you aren’t using a client secret, including client_secret in the token request.

code_challenge_method

This PKCE parameter is required only when code_challenge is specified. This can be either:

plain When the code_challenge value is plain text.
S256 When the code_challenge value is an SHA-256 cryptographic hash.

When you subsequently include the code_verifier value in the token request, the code_challenge value and the code_verifier value must match.

login_hint

Used to specify either the idpid or an email domain.

If you specify the idpid, the user is redirected to the IdP associated with the idpid value for the current application, identified in PingOne SSO for SaaS Apps by the saasid parameter.

If you specify an email domain as the login_hint value, the domain must be included in the IdP Discovery configuration for the application and tenant.

For more information about IdP Discovery for your connection type, see:

The PingOne SSO for SaaS Apps authorization endpoint returns the response_type value or values to the application. If you included code, id_token, and token in the authorization request, as in the example, an authorization code, access_token, and id_token are all returned in the response.

The HTTPS response will be similar to this (using the fragment response method):

https://example.com/#code=ID453b3dfe58d55eed052373d0dc8dcfe2b0f03c234f569fc50200000165483652ee&access_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjQ4RUU0RjNGRDEyQTcwMUFERjYzMzEwMTRENzIzMzUyRDE3QjBFNUUifQ.eyJzdWIiOiJtZG9yZXkrYWRtaW5hdWRpdEBwaW5naWRlbnRpdHkuY29tIiwiaWRwaWQiOiIyNGFkOWJjNi1hNjlmLTQ0OTgtYTliZS0yNTgxMjZiZWFhNmYiLCJzY29wZSI6Im9wZW5pZCIsImlzcyI6Imh0dHBzOi8vdGVzdC1zc28uY29ubmVjdC5waW5naWRlbnRpdHkuY29tL2NkZDIzN2JiLTM0MDQtNGFkNC05MGViLWQyZTI1MjgwODAzNyIsIm1lbWJlck9mIjpbIkRvbWFpbiBBZG1pbmlzdHJhdG9yc0BkaXJlY3RvcnkiLCJVc2Vyc0BkaXJlY3RvcnkiLCJQSU5HT05FLkNMT1VELkRJUkVDVE9SWS5HUk9VUC5VSS5FTlRJVExFTUVOVC5PS1JHU0tZSFhSR0ZLSkdCTk9HSUtSU0FaWlFKTllGQ01LSEZVTE1KUFRGUkJJIl0sImV4cCI6MTUzNDUxODE0NCwianRpIjoiSUQ5NjQ0OGU0MDhiYWFlZDUzYzgyMTBjM2EzNzg4Zjk1ODA5NjA3M2NiNGQ3ZmZlNDYwMjAwMDAwMTY1NDg2OGFkOTAiLCJjbGllbnRfaWQiOiJjZGQyMzdiYi0zNDA0LTRhZDQtOTBlYi1kMmUyNTI4MDgwMzcifQ.KHWFl9Y4sEFKrPkjuUOET-hgmJb_ZVXFEbFred-L-LBIagLCdqppUUSYLrdXPM7W-XIhiR0rlLiWYtlk9S2g2wAzVyFv-JG1J-OUp555Vh3QJvedXll0l3MM42UTrSn3D0QuZQDWLYFiMB730FVhXWWyTaDpaYOCX0JnMWv_TYaJhxGj5tngWr7pBNYWqINpk4PrNlDfp65aesHtUh9W00-BYoepgBawThLIy948h7Z3LTtPmfYzGsmVkBAfNCg8DXKvJXlRvEnVn3XZ5_D4uNHBwT6yfZf4GYQylq-hwITvN_c_OTCaPOP97bnRt6yGwWul40DBrR5xBGhphbh5qA&token_type=Bearer&id_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjQ4RUU0RjNGRDEyQTcwMUFERjYzMzEwMTRENzIzMzUyRDE3QjBFNUUifQ.eyJhdF9oYXNoIjoiRVBCeTVtSEZzN3BJdlpzQ2NhX29vZyIsInN1YiI6Im1kb3JleSthZG1pbmF1ZGl0QHBpbmdpZGVudGl0eS5jb20iLCJhdWQiOiJjZGQyMzdiYi0zNDA0LTRhZDQtOTBlYi1kMmUyNTI4MDgwMzciLCJhY3IiOiJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZCIsImNfaGFzaCI6InJCRV9mZjdBanBGR0psZlltaU52amciLCJpZHBpZCI6IjI0YWQ5YmM2LWE2OWYtNDQ5OC1hOWJlLTI1ODEyNmJlYWE2ZiIsImF1dGhfdGltZSI6MTUzNDUxNDQ0OSwiaXNzIjoiaHR0cHM6Ly90ZXN0LXNzby5jb25uZWN0LnBpbmdpZGVudGl0eS5jb20vY2RkMjM3YmItMzQwNC00YWQ0LTkwZWItZDJlMjUyODA4MDM3IiwiZXhwIjoxNTM0NTE0ODQ0LCJpYXQiOjE1MzQ1MTQ1NDQsIm5vbmNlIjoiUTRDTFZKWWlRYmZMS29Fb3ZZeWciLCJlbWFpbCI6Im1kb3JleSthZG1pbmF1ZGl0QHBpbmdpZGVudGl0eS5jb20ifQ.oK40CUWIUXpDDd_Xy8yqQiyn9cml3EMooWrOr2il2bbm783V_1vQdrpA3tB92vpGD3a2Wc1b9zDImvPpBbL09rMyuqsNSbqkOBgfSir-3jyN23yDHUDEZQ3NdDPBDuS5ObowY0AcRefhu9FqzWjGnRA-AfiwYeEuQpH6Lm7bhLPP-hMCplWw9UG01pTcHNsujq07ybUNOTGBFjF8FgXuKU3GUkp1-MY1fWf8bPNf0OOWwKS7nb6ISqUN-gGWMaQrjrBs0JCLPwaHabqhdjGGc_GtJaUFY4W-B-mol-2_SoVhxU-eDSNlbWF21jNYlJUkPyOTXJIkj3hjPXNUyUspDA

If an id_token was included in the authorization request, the application validates the id_token returned.

For more information, see the OpendID Connect Core 1.0 specifications.
If a token (access token) was included in the authorization request, the application can also optionally validate the access token returned.

Use the PingOne SSO for SaaS Apps introspection endpoint returned by the Discovery URL,https://sso.connect.pingidentity.com/sso/as/introspect.oauth2, to validate the access token.

For access tokens that are signed rather than encrypted, you can also use the JKWS URI returned by the Discovery URL, https://sso.connect.pingidentity.com/sso/as/jwks.

You can see your access token settings at Applications → My Applications → OAuth Settings.

For more information, see Configuring your OAuth settings.

PingOne for Enterprise

Integrating an OIDC application

Before you begin

About this task

Steps

Result:

Result:

Code grant type

Implicit grant type

Hybrid grant type