PingOne for Enterprise

Configuring your OAuth settings

The OAuth settings enable you to configure the access token and any refresh tokens issued for your OpenID Connect (OIDC) applications when requesting user authorization.

About this task

PingOne for Enterprise supports OAuth authorization code, refresh token, implicit and hybrid (both code and implicit) grant types. PingOne for Enterprise issues an OAuth access token for an application only when token is one of the response_type values specified in the application’s authorization request.

When PingOne for Enterprise issues an access token, it contains attributes required by the OIDC specification and any other attributes you assign for the OAuth attributes contract.

As part of the authorization request, PingOne for Enterprise requires the scopes (permissable user resources) you assign when authorizing users.

You can also specify attribute mappings (OAuth claims to identity repository attributes) both at the account level and at the application level. The account-level settings can be overridden when you configure the attribute mapping at the application level (when you are adding the OIDC application).

For implicit grant types, PingOne for Enterprise issues an OAuth access token specifying the attribute contracts that your OIDC applications use to request user authorization. The OAuth access token settings govern how the access token is issued, such as whether it’s signed or encrypted. The issued access token is used in your application’s authorization requests to PingOne for Enterprise.

Additionally, all authorization request include the user scopes (permissable user resources) you assign here. The scopes are granted after the user is authenticated. You can also specify any attribute mappings that you want to be inherited by OIDC applications. Optionally, you can assign trusted origins for Cross-Origin Resource Sharing (CORS).

For managed accounts, the OAuth settings apply only to your managed applications, not to applications supplied by a service provider (SP).

Steps

  1. Go to Applications → OAuth Settings → Access Token.

  2. On the Access Token page:

    1. Select the Format to use for the access token:

      • Signed: The access token is signed using the PingOne for Enterprise OIDC signing key. The PingOne for Enterprisesigning key is available at the PingOne for Enterprise OAuth endpoint https://sso.connect.pingidentity.com/sso/as/jwks.

      • Encrypted: The content of the access token is hidden from both the application and from any API.

    2. Enter the number of minutes for the access token’s Lifetime.

    This is the duration an access token is valid before expiring. The valid range is 1 - 60 minutes.

    1. Enter any additional Attribute Contracts that are to be included in the access token:

      • The sub (Subject) attribute is always required for the access token.

      • The idpid attribute can be removed, but is assigned by default. This is a PingOne for Enterprise attribute used to identify the identity repository used. When included, the idpid attribute is automatically mapped to the idpid of the identity repository when you configure an application that uses this access token.

        These attributes and any others you specify here are available in the attribute mapping used for the connection to an application that uses this access token.

        Only attributes that are marked as required must be mapped to a valid attribute for your identity repository for applications using this access token.

    2. Click Save.

  3. Click the Refresh Token tab.

    Refresh tokens are available only when you’re using the Authorization Code grant type. In this case, a refresh token is automatically exchanged for an access token if the access token expires.

    The refresh token settings control the duration for which a refresh token is valid. Together, these settings help ensure the security of your refresh tokens.

    1. Select a value for Idle Lifetime.

      This is the maximum number of minutes that a refresh token can be idle (unused) before being used again. The default value is 10 minutes.

    2. Select a value for Max Lifetime.

      This is the maximum number of minutes that a refresh token can be valid. The default value is 10 minutes.

  4. Click the Scopes tab.

    The scopes identify the permissible user resources that are to be included in the OAuth authorization request. You can do any of the following actions with the scopes.

    Option Description

    Add a scope

    1. Click Add New Scope.

    2. Enter a Scope supported by your OIDC provider.

    3. Enter a Name to use for the scope.

    4. Enter a claim for the scope. The claims are attributes of the scope that you want to be included in the authorization request.

    5. Click Add Claim for each additional claim to include.

    6. Click Save.

    Edit existing scopes

    1. Expand the details for the scope to modify and click the Pencil icon.

    2. Click Add Claim for each additional claim to include.

    3. Click the Delete icon for each claim you want to delete.

    4. Click Save when you’re finished.

    Delete a custom scope

    1. Expand the details of a custom scope.

    2. Click the Delete icon.

    The default scopes can’t be deleted.

  5. To configure the mapping of identity repository attributes to OIDC scope claims click the Attribute Mapping tab.

    The Attribute Mapping page is an account-level mapping of identity repository attributes to OIDC scope claims. When you are configuring an application that uses this access token, the mappings you specify here are inherited at the application configuration level (where you can override the settings as needed). Doing this mapping at the account level streamlines the attribute to claims mapping you might need to do when configuring applications.

    The listing of claims applies to all scopes. Claims that exist in more than one scope use the same attribute mapping that you specify here.

    1. For the desired OAuth claim, in the Mapping list, select the identity repository attribute to use for the mapping.

    2. If you want to further customize the mapping, click Advanced to display the advanced attribute mapping mode.

    For detailed instructions, see Assign advanced attribute mappings.

    1. To exit advanced attribute mapping mode, click Close Advanced.

    2. Continue mapping any further OAuth claims to identity repository attributes.

    3. Click Save.

  6. To configure Cross-Origin Resource Sharing (CORS), click Additional Settings.

    When configured, applications from the trusted origins are allowed to make requests to the supported PingOne for Enterprise authorization server endpoints.

    1. In the Allowed Origin field, enter a valid URI for one or more of the trusted origins.

      The maximum number of trusted origins is 100.

      Example:

      For example:

      https://www.example.com

      CORS requests originating from this URI are allowed.

      https://www.example.com:8080

      CORS requests originating from port 8080 of this URI are allowed.

      https://www.example.com:*

      CORS requests originating from any port for this URI are allowed.

      The specified origin or origins must be available at SSO runtime to all of your managed OIDC applications. OIDC applications originating at a service provider or (for PingOne for Managed Service Providers) customer accounts are not supported as trusted origins.

    Requests from the trusted origins apply to the following PingOne for Enterprise OAuth endpoints:

    • /sso/as/token.oauth2

    • /sso/as/introspect.oauth2

    • /sso/idp/userinfo.openid

    • /sso/as/jwks

    • /.well-known/openid-configuration

    • /{client_id}/.well-known/openid-configuration