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.

API Platform Version: 8.1 and later

Table of Contents

  1. When would I choose an External OAuth Provider domain?
  2. What do I need to do to use the External OAuth Provider domain for PingFederate access?
  3. How do I add an External OAuth Provider domain?
  4. What are the settings on the External OAuth Provider Configure page and what options should I choose?
  5. What are the settings on the Provider page and what options should I choose?
  6. What are the settings on the External OAuth Provider Access Token Validation page and what options should I choose?
  7. What are the settings on the External OAuth Provider Access Token Validation page for PingFederate?
  8. What are the settings on the External OAuth Provider Extensions page for PingFederate, and what options should I choose?
  9. How do I modify an External OAuth Provider domain?
  10. How do I delete an External OAuth Provider domain?
  11. Related Topics

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.

Back to top

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 for your PingFederate implementation, because this domain supports client registration.

To do this, follow these steps:

  • Set up the domain: See How do I add an External OAuth Provider domain? below.
  • If you want to support Client Registration, implement a custom workflow. This allows auto-registration of client apps when they connect to APIs that use this domain. For information on uploading a custom workflow, see to upload a custom workflow. For help with developing a custom OAuth workflow, contact your Akana representative.

Back to top

How do I add an External OAuth Provider domain?

The Business Admin can set up an External OAuth Provider domain in the developer portal UI.

Note: adding or modifying the domain configuration on the platform does not add or modify configuration with the OAuth Provider itself. You must set up values in the platform to match configuration at the OAuth Provider.

To configure an external OAuth provider domain:
  1. Click the Administration quick filter (wrench icon).
  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:
    • Details
    • Configure
    • Provider
    • Token Validation
    • Extensions
  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, the information is read from the configuration file, but you can modify if needed. 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?
  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?
  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.
  9. Click Save. The 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).

Back to top

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.

Back to top

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.

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

Option... Meaning...
Issuer The Issuer ID of the provider. If you provided a well-known configuration URL, the value is read from the provider's configuration file and displayed.
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. If you provided a well-known configuration URL, the value is read from the provider's configuration file and displayed.
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. If you provided a well-known configuration URL, the value is read from the provider's configuration file and displayed.
JWK Set URL If your provider will send an ID token signed with a private key, provide the URI for the JSON web key set where the corresponding public key can be read and used for ID token signature validation. If you provided a well-known configuration URL, the value is read from the provider's configuration file and displayed.
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. If you provided a well-known configuration URL, the value is read from the provider's configuration file and displayed.
Client Registration Endpoint Optional: The provider's Dynamic Client Registration endpoint. This allows auto-registration of client apps when they connect to APIs that use this domain. If you provided a Well-Known Configuration URL, the value is read from the provider's configuration file and displayed. If you are doing manual setup, provide the value if it's available.
Supported Response Types Indicates the OpenID Connect response types that the external OAuth Provider supports.
Supported Response Modes Indicates the OpenID Connect response modes that the external OAuth Provider supports.
Supported Grant Types

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

  • Authorization Code
  • Implicit
  • Resource Owner Credentials
  • Client Credentials
  • JWT Bearer
  • Refresh Token (8.4.17 and later). 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.

    Note: This option doesn't appear in the user interface for domains that were created before upgrading to 8.4.17. To make sure the new option is available for app developers in the App OAuth Profile page, you can create a new domain and select the Refresh Token option. It will then appear in the App OAuth Profile page, and will work for pre-existing domains even though the setting doesn’t appear in the user interface for those domains. Using this approach means you don’t need to re-create existing domains.

Supported Token Endpoint Authentication Methods Authentication methods supported by the token endpoint.
Token Endpoint Auth Signing Algorithm Algorithms supported by the token endpoint for signing the token.
D Token Signing Algorithm The encryption algorithm that the provider will use to encrypt the ID token signature.
ID Token Encryption Key Management Algorithm Algorithms supported by this provider for encryption of the ID token key.
ID Token Content Encryption Algorithm Algorithms supported by this provider for encryption of the ID token content.
Scopes 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.

Back to top

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

Check the applicable checkbox 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.
  • Referenced Bearer: A short random token that uniquely identifies the grant, sent as-is in the API request, in the Authorization header.
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.
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. jti is the closest standard claim for this.
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 box), X.509 Certificate URL (paste the URL in the box), or 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 Choose this option if you want to read in the certificate from the URL.
Reference encryption keys from an existing platform identity 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?
Settings for Referenced Bearer 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.

Back to top

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, that are not available for other providers.

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

Option... Meaning...
Validate Bearer Access Token by Authorization Server You can choose to verify a Bearer access token with the Authorization Server. This adds a processing step, but you might prefer to verify the token with the Authorization Server to ensure that any grant revocations are considered when validating the access token.
Token Validation Endpoint The endpoint for Bearer access token validation.
Resource Owner Subject 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/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.

Back to top

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.

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 (8.4.19 and later)

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 (8.4.17 and later)

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 (8.4.18 and later): 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.

Back to top

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 developer portal
  1. Log in as the Business Admin and click the Administration quick filter (wrench icon).
  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.

Back to top

How do I delete an External OAuth Provider domain?

To delete an External OAuth Provider domain
  1. Log in as the Business Admin and click the Administration quick filter (wrench icon).
  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, in the Config options. For instructions, see How do I disable a platform login?

Back to top