PingOne for Enterprise

Integrating an OIDC application

After you add or update an OIDC application, you need to integrate it with PingOne for Enterprise.

About this task

After adding an application, you need to integrate the application with PingOne for Enterprise, which will act as the provider (OP) for your application. Your application then needs to request authorization from the PingOne for Enterprise OAuth authorization endpoint when users attempt to to the application.

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

PingOne for Enterprise returns OIDC user attributes in different ways depending on the response_type parameter.

The contents of the ID token depend on whether or not the application also returns an access token (If the response_type includes token).

If an access token is returned, the application returns an ID token containing the sub and, if requested, email scopes. The userinfo endpoint contains all of the attributes for the requested scopes, as well as an attributes configured on the User Info tab for the application, if the openid scope was requested.

If an access token is not returned, the ID token contains all of the attributes for the requested scopes, as well as any attributes configured on the User Info tab for the application, if the openid scope was requested. The userinfo endpoint is inaccessible in this case because no access token is issued.

The access token contains attributes configured at Applications → OAuth Settings → Access Token.

For more information, see Configuring your OAuth settings.

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

  1. Go to Applications → My Applications → OIDC.

  2. Click Expand to display the summary page for the OIDC application to integrate.

    Result:

    The PingOne for Enterprise Discovery URL for the application is displayed in the Details section. The application’s client ID value is part of the URL.

  3. In a new browser tab, enter the Discovery URL.

    Result:

    {p14e} returns OIDC configuration information, including the endpoints you will use to integrate the application.

Code grant type

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

PingOne for Enterprise 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 for Enterprise sends the response to the specified redirect URI.

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

  1. 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=5f65fdde-44e2-4d1c-be2b-41d5e0d6b903&response_type=code&redirect_uri=https://localhost&scope=openid

    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.

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

    The HTTPS response will be similar to this:

    https://localhost/?code=I0YAW2EWll_V8xH4m6b7IJ3WWD1wNZ5BnvkCQw7gknp4z2gQkHCM66AHsbCLA7

  3. 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
    shell

    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 for Enterprise. You can find the assigned client secret in the Details tab.

  4. The application validates the id_token returned. For more information see the OpendID Connect Core 1.0 specifications.

  5. 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.