External OAuth Provider Domain

Configure an External OAuth Provider domain on the platform.

Note: For general information about platform domains, or specific information on a different domain, refer to Domains.

Table of Contents

When would I choose an External OAuth Provider domain?

If your installation uses any external OAuth provider, such as PingFederate or even the Akana OAuth Provider in a different installation, you can choose the External OAuth Provider domain option. Using this option, you can implement multiple OAuth Providers in the platform.

For example, you might have two installations; one has the platform OAuth Provider, and the second does not, but wants to integrate with the platform OAuth Provider. You could use this domain to accomplish that, configuring this domain to reference the external Akana OAuth Provider.

If you are using PingFederate, and were previously using the PingFederate domain option, we recommend that you switch to the External OAuth Provider domain. This domain is more flexible and also offers auto-configure of apps that have active contracts with APIs that reference the External OAuth Provider domain. Manual configuration of the apps in PingFederate is not necessary.

Note: If you are setting up the platform for the first time and want to use the External OAuth Provider domain to support PingFederate, note that the platform Administrator will also need to install the PingFederate options pack. If the PingFederate domain is not available on the domains list, it was not installed.

You can also use this domain type for any other entity that could be an external OAuth provider for your installation; for example, if your APIs offer services to app developers who use Google services, you might want to set up Google as an external OAuth provider. In the External OAuth Provider Domain, under Provider Type, choose Other, and then provide the necessary values provided at the Well-Known Configuration URL (for Google, it is https://accounts.google.com/.well-known/openid-configuration).

Note: If you want to use an External OAuth Provider domain for user login only, and the provider uses OpenID Connect for authentication, you don't need to configure an External OAuth Provider domain. Instead, choose the OpenID Connect Relying Party domain.

What do I need to do to use the External OAuth Provider domain for PingFederate access?

It's best to use the External OAuth Provider domain for your PingFederate implementation, because this domain supports integrated workflow for client registration out of the box. All you need to do is set up the domain: See How do I add an External OAuth Provider domain? below. Certain fields are available only for PingFederate users, as noted.

How do I add an External OAuth Provider domain?

The Business Admin can set up an External OAuth Provider domain in the Community Manager developer portal user interface.

Note: Adding or modifying the domain configuration settings on the platform does not add or modify configuration with the OAuth Provider itself. If you make changes to the configuration settings that are read from the Well-Known Configuration URL, it does change the configuration of the external OAuth provider. You must set up values in the platform to match the configuration of the OAuth Provider.

To configure an external OAuth Provider domain

  1. Log in as a Business Admin and go to the Admin section.
  2. Click Domains.
  3. Click Add Domain and choose External OAuth Provider. The Add External OAuth Provider wizard opens at the Details page. This wizard has five pages:
  4. Enter a name and description for your external OAuth provider (for example, Name=PingFederate, Description=PingFederate Domain).
  5. Click Next to go to the Configure page, where you can specify the type of external provider and how you want to configure the provider. Specify values or choose options.

    For more information, see What are the settings on the External OAuth Provider Configure page and what options should I choose?

  6. Click Next to go to the Provider page. This page includes information about the external OAuth Provider. If you provided a Well-Known Configuration URL to configure your domain, the information is read from the configuration file, but you can remove values if needed. Do not add values; if the provider doesn't support them, they won't work. If you are doing manual configuration you must specify the values.

    For more information, see What are the settings on the Provider page and what options should I choose?

    Note: Whether you upload information from a configuration URL, or enter it manually, be aware that the only effective values you can choose are values supported by the OAuth Provider. If you choose values that your OAuth Provider doesn't support, they will not work, and your choices could result in errors for the users of your API.

  7. Click Next to go to the Access Token Validation page. If you want the access token to be validated by the Resource Server, click the check box and specify values that will be needed for the validation, such as claim names and keys. For more information see What are the settings on the External OAuth Provider Access Token Validation page and what options should I choose?.

    Note: On the Access Token Validation page, additional fields are available for PingFederate users only.

  8. Click Next to go to the Extensions page. If your external OAuth Provider supports one or more extensions, you'll see them in this tab. Check the box if you want your External OAuth Provider domain to support a specific extension that your external OAuth Provider offers, and then enter values associated with the extension. If you need help with any of the fields, check with your external OAuth Provider.

    For an example of the properties you might see if you're using PingFederate, see What are the settings on the External OAuth Provider Access Token Validation page for PingFederate?

  9. Click Save. The External OAuth Provider domain is saved, and is now available for selection by API Admins when setting up OAuth details (API > Details > on right, OAuth Details).

What are the settings on the External OAuth Provider Configure page and what options should I choose?

When you're setting up an External OAuth Provider domain, the Configure page allows you to identify the external provider.

For information about the values set up on the Configure page (Tab 2), refer to the table below.

Option... Meaning...
Provider Type The type of external OAuth Provider. If the OAuth Provider is Akana or PingFederate, choose the applicable option. For any other OAuth Provider, choose Other.
Configuration Method

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.

What are the settings on the Provider page and what options should I choose?

When you're setting up an External OAuth Provider domain, the Provider page allows you to review information that was read in from the Well-Known Configuration URL or add manual configuration information for your external provider. You can choose not to offer options that your provider supports, by removing configuration values.

For information about the values set up on the Provider page (Tab 3), refer to the table below.

Notes re OAuth URLs:

  • In version 2022.1.0 and later, all OAuth URLs must either be on the list of virtual hosts for the tenant (see How do I configure values for a theme?) or must be on the list of trusted hosts in the platform's site settings, Limit forward proxy feature to allow only these hosts field (see How do I configure site settings?).
  • If you provided a Well-Known Configuration URL to configure your domain, the values that the provider supports are read from the provider's configuration file and displayed. If you choose not to support some of those values in your External OAuth Provider domain, you can remove those values by clearing the check boxes. The user interface allows you to check additional values; however, if you choose values that the provider doesn't support, the platform cannot support them. Be sure that your configuration reflects only values that your provider supports.
Option... Meaning...
Issuer The Issuer ID of the provider.
Authorization Endpoint URL Your provider’s authorization endpoint URL. This is where the provider authenticates the user and requests the user’s consent to allow access to their resources.
Token Endpoint URL Your provider’s token endpoint URL. The token endpoint authenticates the relying party’s request for access. Once authentication is complete, it returns an access token.
JWK Set URL The URI for the JSON web key set where the public key can be read and used for ID token signature validation, if your provider supports sending an ID token signed with a private key.
UserInfo Endpoint URL Your provider's UserInfo Endpoint URL. If you chose to have claims returned from the UserInfo endpoint, the client sends the access token to this endpoint, with information about the claims for which the user granted access permission, and the UserInfo Endpoint returns the user information in the form of a JSON object.
Client Registration Endpoint Optional: The provider's Client Registration endpoint. This allows auto-registration of client apps when they connect to APIs that use this domain.
Supported Response Types

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
Supported Response Modes

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

Full set of possible options:

  • query
  • fragment
  • form_post
Supported Grant Types

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.
Supported Token Endpoint Authentication Methods

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?

Token Endpoint Auth Signing Algorithm

Algorithms supported by the token endpoint for signing the token.

Full set of possible options:

  • HS256
  • HS384
  • HS512
  • RS256
  • RS384
  • RS512
D Token Signing Algorithm

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
ID Token Encryption Key Management Algorithm

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
ID Token Content Encryption Algorithm

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
Scopes Supported

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.

What are the settings on the External OAuth Provider Access Token Validation page and what options should I choose?

When you're setting up an External OAuth Provider domain, the Access Token Validation page allows you to enter information applicable to the OAuth Provider's support of access tokens. The platform can support access tokens issued by PingFederate, the platform itself, or any other OAuth Provider.

For information about the values set up on the Access Token Validation page (Tab 4), refer to the table below. For information about the additional fields available when the OAuth Provider is PingFederate, see What are the settings on the External OAuth Provider Access Token Validation page for PingFederate?

Option... Meaning...

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.

Settings for JWT Bearer Access Token

Option... Meaning...
Issuer Specify the issuer name that will be in the iss claim of the token. The Resource Server will validate the issuer name against the value provided in this field.
Audience

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.

Client ID Claim Name Claim name the external OAuth Provider uses for the Client ID in the access token. The Resource Server will use the value from this claim to set up the app identity for the request.
Scope Claim Name Claim name the external OAuth Provider uses for a scope in the access token. This claim contains space-delimited scopes that are in the grant scope. The Resource Server will use the value of this claim to check if the request operation can be authorized with the scope of the token.
Grant ID Claim Name Claim name the external OAuth Provider uses for the Grant ID. Each grant represents the resource owners' authorization to the application. The closest standard claim for this is the jti claim.
Resource Owner UID Claim Name Claim name the external OAuth Provider uses for the Resource Owner ID in the access token.
Allowed Clock Skew (In Seconds) The grace period an access token is allowed before effective timestamp and after expired timestamp, expressed in seconds; for example, 120 seconds. This is to accommodate the clock setting difference between the issuing machine and validating machine. At runtime, if clock skew is exceeded, validation fails.
Signing Keys

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?

Important: In PingFederate, the custom claims must not be mapped to Grant Specific claims such as ClientID Claim Name, Scope Claim Name, Grant ID Claim Name, or Resource Owner UID Claim Name. If the custom claims are mapped to Grant Specific claims, they will be skipped from the ResourceOwnerInfo header.

Note: For additional fields available if the provider is PingFederate, see What are the settings on the External OAuth Provider Access Token Validation page for PingFederate?

What are the settings on the External OAuth Provider Access Token Validation page for PingFederate?

When you're setting up an External OAuth Provider domain, the Access Token Validation page allows you to enter information applicable to the OAuth Provider's support of access tokens. The platform can support access tokens issued by PingFederate, the platform itself, or any other OAuth Provider.

When the OAuth Provider is PingFederate, specific fields are available in the right column of the page, that are not available for other providers, as shown below.

External OAuth Provider, Access Token Validation tab, Bearer Access Token option with PingFederate provider

For information about the values specific to PingFederate on the Access Token Validation page (Tab 4), refer to the table below.

Settings for Referenced Bearer Access Token (PingFederate only)

When you choose to verify a Bearer access token with the Authorization Server, this adds a processing step. However, you might prefer to verify the token with the Authorization Server to ensure that any grant revocations are considered when validating the access token.

Option... Meaning...
Token Validation Endpoint The endpoint for Bearer access token validation.
Resource Owner Subject property name Property name to be used to identify the resource owner in the Bearer access token validation response.
Use Platform Identity Indicates that the resource server identity information is associated with a platform identity in Policy Manager. Enter the identity name exactly as it is set up in Policy Manager. Make sure identity name and password credentials match with the configured identity for this resource server. Also, be sure to associate an appropriate role in the OAuth Provider to validate bearer access tokens.
  Platform Client Identity If you choose to use a platform identity, enter the identity name exactly as it is set up in Policy Manager. Make sure identity name and password credentials match with the configured identity for this resource server. Also, be sure to associate an appropriate role in the OAuth Provider to validate bearer access tokens.

Resource Server Client ID/

Resource Server Client Secret

If you choose not to use a platform identity, enter the Client ID and password credentials for the account with the external OAuth Provider.

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

Note: In version 2022.1.0 and later, all OAuth URLs must either be on the list of virtual hosts for the tenant (see How do I configure values for a theme?) or must be on the list of trusted hosts in the platform's site settings, Limit forward proxy feature to allow only these hosts field (see How do I configure site settings?).

What are the settings on the External OAuth Provider Extensions page for PingFederate, and what options should I choose?

If your external OAuth Provider is PingFederate, you'll see some additional choices available on the Extensions page of the wizard. These settings represent additional functionality supported by PingFederate. The page will look something along the lines of the below.

External OAuth Provider, Extensions tab with PingFederate provider

For information about the values you can set up for your PingFederate OAuth Provider on the Extensions page (Tab 5), refer to the table below.

Option... Meaning...
Version Number

Specify the PingFederate version number you're using, in the format major.minor; for example, 8.0, 8.3, or 9.0.

For information about the PingFederate versions the platform supports, see What versions of PingFederate does the platform support?

Client Registration Enabled Check this box if your implementation is using the client registration endpoint. This allows auto-configuration of apps that have active contracts with APIs that reference the External OAuth Provider domain. Manual configuration of the apps in PingFederate is not necessary.
Authentication Method Choose the authentication method out of the options available.
Use Platform Identity Indicates that the credentials are associated with a platform identity in Policy Manager. For more information, see Should I set up a platform identity, or provide the credentials in the domain configuration?
Platform User Identity Enter the identity name exactly as it is set up in Policy Manager.
Username/Password The username and password credentials that identify the platform with PingFederate
Synchronize Client Certificate

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.

How do I modify an External OAuth Provider domain?

If there are changes to your External OAuth Provider domain configuration, you'll need to update the domain settings in the platform.

Note: The procedure below only updates the platform settings; it doesn't change any external configuration with the external OAuth Provider. To change to the external OAuth Provider configuration, you must first make the changes with the provider itself, and then update the platform settings to match the provider configuration, using the procedure below.

To modify an External OAuth Provider domain in the Community Manager developer portal

  1. Log in as a Business Admin and go to the Admin section.
  2. Click Domains. The Domains Summary page displays.
  3. Find the domain on the list and click Modify. The Edit wizard for the specific domain type displays.
  4. Change values as needed.
  5. Click Save. The changes might take a few minutes to take effect.

How do I delete an External OAuth Provider domain?

To delete an External OAuth Provider domain

  1. Log in as a Business Admin and go to the Admin section.
  2. Click Domains. The Domains Summary page displays.
  3. In the right-hand column of the domain line item, click Delete. At the confirmation message, click OK.

Note: Rather than deleting a domain, you might choose to disable the domain for login. For instructions, see How do I disable a platform login?