After you Add or update an OIDC application, you need to integrate it with PingOne SSO for SaaS Apps.
See Adding or updating an OIDC application to add an application to PingOne SSO for SaaS Apps.
When you integrate an 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.
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.
Note: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
Note: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
.Note:You can see your access token settings at
.For more information, see Configuring your OAuth settings.
Implicit 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 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.
Note: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
.Note:You can see your access token settings at
.For more information, see Configuring your OAuth settings.
Hybrid 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 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.
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 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.
Note: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.
Note: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.
Note: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
.Note:You can see your access token settings at
.For more information, see Configuring your OAuth settings.