External OAuth Provider Domain

Choose how you want to configure the domain:

• Well-Known Configuration URL: Reads the configuration information from your provider's well-known configuration URL (discovery endpoint), where your provider publishes metadata the platform can use to set up the domain. Provide the URL ({oauth-provider-url}/.well-known/openid-configuration) and then click Load. You'll be able to edit the information afterwards if needed.
• Well-Known Configuration JSON: Reads the JSON you copy from the configuration file. Paste the JSON and then click Load. You'll be able to edit the information afterwards if needed.
• Manually: Choose this option if you want to set up your provider domain by providing all the values yourself, without reference to any external configuration information, or if your provider doesn't support the OpenID Connect Discovery Endpoint.

Indicates the OpenID Connect response types that the external OAuth provider is configured to support. If you provided a well-known configuration URL to configure your domain, the supported values are read from the provider's configuration file.

Full set of possible options:

• code
• id_token
• token
• id_token token
• code id_token
• code token
• code id_token token

Indicates the OpenID Connect response modes that the external OAuth provider is configured to support.

Full set of possible options:

• query
• fragment
• form_post

Indicates the OAuth 2.0 grant types the external OAuth Provider supports.

Full set of possible options:

• Authorization Code
• Implicit
• Resource Owner Credentials
• Client Credentials
• JWT Bearer
• Refresh Token: This option supports external OAuth providers that list refresh token as a separate grant type. The new option appears on the list of default grant types only if you create the domain using manual configuration, and enable this option, or if the provider's well-known configuration includes it. If any domain on the platform includes this option, it will also appear on the default list of grant types in the App OAuth Profile page, so that app developers can choose it when determining how the app with authenticate with the OAuth provider.

Authentication methods supported by the token endpoint.

Full set of possible options:

• Client Secret Basic
• Client Secret Post
• Client Secret JWT
• Private Key JWT

Note: If the platform is using PingFederate 9.0x, the app certificate is available and Private Key JWT is enabled here for the domain and also checked in the App OAuth Profile, the platform uses the app's Client Registration JWKS URL in place of the app's certificate/shared secret when synchronizing the app with PingFederate. This also depends on the settings on the Extensions page. For more information, see What are the settings on the External OAuth Provider Extensions page for PingFederate, and what options should I choose?

Algorithms supported by the token endpoint for signing the token.

Full set of possible options:

• HS256
• HS384
• HS512
• RS256
• RS384
• RS512

The encryption algorithm that the provider will use to encrypt the ID token signature.

Full set of possible options:

• HS256
• HS384
• HS512
• RS256
• RS384
• RS512
• ES256
• ES384
• ES512
• PS256
• PS384
• PS512

Algorithms supported by this provider for encryption of the ID token key.

Full set of possible options:

• RSA1_5
• RSA-OAEP
• RSA-OAEP-256
• A128KW
• A192KW
• A256KW
• A128GCMKW
• A192GCMKW
• A256GCMKW
• dir

Algorithms supported by this provider for encryption of the ID token content.

Full set of possible options:

• A128CBC-HS256
• A192CBC-HS384
• A256CBC-HS512
• A128GCM
• A192GCM
• A256GCM

In the right column, scopes associated with the OAuth Provider are displayed if information was read in. If the OAuth Provider supports additional scopes that are not in the well-known configuration file, you can add those here.

You can also use the asterisk wildcard in scopes. Only include one asterisk.

As with all fields, do not add values that are not supported by the provider.

JWT Bearer Access Token

Referenced Bearer Access Token (PingFederate only)

Check the applicable check box to access fields for setting up values to support either or both of these token types:

• JWT Bearer: An access token that uses the standard and contain all the information the resource server needs to confirm the user’s grant to the application, sent as-is in the API request, in the Authorization header.

  For field descriptions, see Settings for JWT Bearer Access Token below.

• Referenced Bearer (for PingFederate only: A short random token that uniquely identifies the grant, sent as-is in the API request, in the Authorization header.

  For field descriptions, see Settings for Referenced Bearer Access Token (PingFederate only) below.

The value that should be included in the aud (audience) claim in the token. This identifies the entity that will be consuming the token. Enter the value exactly as it is set up in the configuration of your external OAuth Provider. The Resource Server will validate the audience name against the value provided in this field.

For multiple values, use a space or comma delimiter.

Choose one of the following:

• Reference signing keys from an existing platform identity: Indicates that the signing key is associated with an identity in Policy Manager. Enter the identity name exactly as it is set up in Policy Manager. For more information, see Should I set up a platform identity, or provide the credentials in the domain configuration?
• Symmetric key inline: Used when the access token is signed with a symmetric signature algorithm such as HMAC. Click the button, and then enter the symmetric key.
• Asymmetric key inline: Used when the access token is signed with an asymmetric signature algorithm such as RSA. Click the button, specify the Asymmetric Key Source field, and provide the details. There are three choices:
  • X.509 Certificate: Paste the certificate in the X.509 Certificate Content box.
  • X.509 Certificate URL: Paste the URL in the X.509 Certificate URL field. The platform requests the certificate using a POST request; the X.509 certificate URL must support this.
  • JWK Set URL (used if the domain supports the JWK standard): There might be multiple public keys published at the URL; the platform determines the correct public key and uses it to verify the message. To use this option, you must first set up the JWK Set URL in the Provider tab, JWK Set URL field. For information on JWK, refer to the specification: https://tools.ietf.org/html/rfc7517.

Supports Encryption /

Reference encryption keys from an existing platform identity

Choose this option if you want to read in the certificate from the URL.

If you choose Supports Encryption you'll see the Reference encryption keys from an existing platform identity option, which indicates that the encryption key is stored in Policy Manager, associated with a platform identity. Enter the identity name exactly as it is set up in Policy Manager. Make sure the correct shared secret and/or private key are assigned to this identity. For symmetric encryption, shared secret/password credentials are required for the identity. For asymmetric encryption, make sure the private key needed for decryption is assigned to the platform identity. For more information, see Should I set up a platform identity, or provide the credentials in the domain configuration?

Resource Server Client ID/

Resource Server Client Secret

ATM ID

Resource URI

Additional fields needed for PingFederate's support of multiple access token management (ATM) instances. The client can specify an ATM instance by providing either of the following in requests to the PingFederate OAuth Authorization Server:

• Access Token Manager ID (access_token_manager_id): The instance ID of the ATM instance that you want to access.

  If a value is provided for this field, the Resource URI value (below) is ignored. PingFederate uses the desired ATM instance for the request if it is eligible; otherwise, it aborts the request.

  Note: When the ATM ID is specified, PingFederate ignores the Resource URI (aud) parameter.

• Resource URI (aud): The resource URI that the client wants to access. The PingFederate Authorization Server matches the value provided against valid resource URIs configured in access token management instances. When a match is found, PingFederate uses the corresponding access token management instance for the request if it is eligible. If an eligible match is not found, the request fails.

For more information on these two fields, see https://documentation.pingidentity.com/pingfederate/pf92/index.shtml#adminGuide/tokenEndpoint.html (OAuth access token management parameters section).

Determines whether apps contracted with APIs that use this OAuth domain can authenticate with PingFederate using a certificate uploaded to the app's OAuth Profile page. Options are as follows:

• Checked: For APIs that are using this domain and have the OAuth Security policy attached, apps that have a contract with the API can authenticate with PingFederate via the app's certificate. The app must have a valid certificate that is trusted by PingFederate and is also uploaded in the app's OAuth Profile page (see How do I configure my app's OAuth profile settings?). If the box is checked but the app doesn't have a certificate, PingFederate authentication is done via the app credentials (Client ID and secret).
• Cleared (the default): For APIs that are using this domain and have the OAuth Security policy attached, apps contracted with the API must authenticate with PingFederate using the app credentials (Client ID and secret). Even if the app has a certificate uploaded, the certificate is ignored unless this setting is checked in the domain setup.

Note: If you're using PingFederate 9.x and Client Registration and the Synchronize Client Certificate settings are both enabled, the app certificate is available and Private Key JWT is checked in the app's OAuth Profile page, the platform uses the app's Client Registration JWKS URL in place of the app's certificate/shared secret when synchronizing the app with PingFederate. This also requires that Private Key JWT is enabled in the External OAuth Provider Domain setup, Provider tab, in the Supported Token Endpoint Authentication Methods field.