Akana OAuth/OIDC Provider Domain

Configure an Akana OAuth/OIDC Provider domain on the platform. For general information about platform domains, or specific information on a different domain, refer to Domains.

Table of Contents

Which type of OAuth Provider domain should I set up?

The platform offers two options for setting up an OAuth Provider domain:

  • Akana OAuth/OIDC Provider Domain

    Choose this option if you are using the Akana API platform as your OAuth/OIDC provider. You can set up a separate provider that you want to use for authentication, such as Google or Facebook, and the platform manages the process of authenticating via the separate provider and manages authorization, token issuance, and API access. For more information, see How do I set up and configure an Akana OAuth/OIDC Provider domain? below.

  • External OAuth Provider Domain

    Choose this option if you want to use an entity other than the Akana API platform as your OAuth/OIDC provider; for example, PingFederate or Google. For more information, see External OAuth Provider Domain.

How do I set up an Akana OAuth/OIDC Provider domain?

If you're using Akana as the OAuth Provider, use the Akana OAuth/OIDC Provider Domain option. See How do I set up and configure an Akana OAuth/OIDC Provider domain? below.

How does the Akana OAuth/OIDC Provider domain configuration process work?

Here's how Akana OAuth/OIDC Provider domain configuration works:

  • The Administrator installs the feature into the platform container via the Akana Administration Console. This process is covered in the installation guide for the platform.
  • After the feature is installed, the Business Admin can configure the domain via More > Admin >Domains > Akana OAuth/OIDC Provider.
  • Once the Akana OAuth/OIDC Provider domain is set up, it is available to the API Admin when configuring the API's OAuth details (API > Details > on right, OAuth Details). The API Admin chooses the Akana OAuth/OIDC Provider domain and OAuth version, selects one or more grant types, and specifies resources relative to the specified OAuth version. If multiple OAuth Provider domains are defined, the API Admin can choose different OAuth providers for different APIs.
  • At runtime, the OAuth Provider manages the OAuth process in the background, directing the app client and the app's user and ensuring authentication and authorization, issuing tokens, and providing API access.

For instructions on setting up the platform as an OAuth Provider, see How do I set up and configure an Akana OAuth/OIDC Provider domain?

To set up an external OAuth Provider, see How do I add an External OAuth Provider domain?

How do I set up a platform deployment to support a third-party OAuth provider?

The OAuth Details function (API > Details > on right, OAuth Details) includes a pre-defined "third-party provider" domain that allows the API Admin to configure grants and resource mapping for OAuth versions 1.0a and 2.0. No setup is required by the Business Admin for this option. The purpose of this option is so that the API Admin can reference an external OAuth provider, if needed, rather than use one of the OAuth provider configurations provided by the platform implementation.

For more information, see How do I configure OAuth Details for my API? in the API Admin help.

Alternatively, you can set up an External OAuth Provider Domain.

How do I set up my deployment to support OAuth?

If you are a Business Admin you can set up one or more OAuth Provider domains by choosing More > Admin >Domains. There are two choices: use the platform as your OAuth/OIDC provider, or set up an external OAuth Provider. For help in determining which one is right for your installation, see Which type of OAuth Provider domain should I set up?

Create a domain for each OAuth Provider scenario you want to support.

API Admins can then choose an OAuth Provider domain in the API OAuth setup page.

For instructions, see:

How do I set up and configure an Akana OAuth/OIDC Provider domain?

The Akana OAuth Provider feature is an add-on. This domain type allows you to use the platform as your OAuth/OIDC provider; you can specify a resource owner authentication domain and configure grant types, access tokens, grant properties, and branding.

Essentially, there are two steps:

  1. Administrator: In the Akana Administration Console, install the Akana OAuth Provider feature. This installs the Akana OAuth/OIDC Provider domain option. The Business Admin can then create and configure the domain in the Community Manager developer portal user interface.
  2. Business Admin: Set up the domain in the Akana API Platform (see below).

Note: When you install the Akana OAuth Provider add-on, it is added to the list of choices in More > Admin >Domains > Add Domain. It is not available as a Login option in the More > Admin >Logins page.

To configure an Akana OAuth/OIDC provider domain

  1. Log in as a Business Admin and go to the Admin section.
  2. On the left menu bar, click Domains. The Domains Summary page displays.
  3. Click Add Domain and choose Akana OAuth/OIDC Provider. The Add Akana OAuth/OIDC Provider wizard opens at the Details page. This wizard has seven pages:
  4. In the Details page, enter a name and description for your Akana OAuth/OIDC provider (for example, Name=OAuth 2-Legged, Description=OAuth 2-Legged Domain).
  5. Click Next to go to the Grant Types page, where you can specify information about one or more OAuth Grant Types that you want the Akana OAuth/OIDC Provider domain to support. Specify values or choose options.

    For more information, see Akana OAuth/OIDC Provider Domain: Tab 2, Grant Types - Configuration Values

  6. Click Next to go to the Token page, where you can specify information about one or more token types that you want the Akana OAuth/OIDC Provider domain to support. Specify values or choose options.

    For more information, see What are the settings on the Akana OAuth/OIDC Provider Token page and what options should I choose?

  7. Click Next to go to the OpenID Connect page. Here, you'll set up the necessary values if you want your Akana OAuth/OIDC Provider domain to use an OpenID Connect Identity Provider for authentication. If not, you can skip this tab.

    For more information, see What are the settings on the Akana OAuth/OIDC Provider OpenID Connect page and what options should I choose?

  8. Click Next to go to the Scopes page. Here you will define OAuth scopes; later, API Admins for APIs that are using this OAuth domain can map specific operations in the API to these scopes and thus control the functions that OAuth will be requesting access to. For example, you might define a scope called Read-Only and map all GET operations to it. For more information, see How does Scope Mapping work? Define one or more scopes, with the following values for each:
    • Name, short description, and full description.
    • Default scope check box: indicates whether this scope is always requested.
    • User Authorization Required: indicates whether user authorization is required for scope access. Usually, it is. However, if an OAuth grant includes all scopes with this option disabled, the provider does not require the resource owner to authorize the grant request.
  9. Click Next to go to the Properties page. If you want to set up grant properties, click +Add and specify details. For more information, see What is a Grant Property? For each property, specify the following values:
    • Property Label: a text description, used only within the platform.
    • Property ID: the object ID that references the property file.
  10. Click Next to go to the Branding page. Here you can customize the page that app users will see when an API that is using this OAuth domain is requesting access to the user's resources.

    For more information, see What are the settings on the Akana OAuth/OIDC Provider Branding page and what options should I choose?

  11. Click Save.

    The Akana OAuth/OIDC Provider domain is saved, and is now available for selection by API Admins when setting up OAuth details (API > Details > on right, OAuth Details).

Note: If your implementation will have a load balancer in front of the OAuth Provider container, there is an additional setup step for the Administrator. As well as setting up the OAuth domain, the load balancer settings on your implementation must be set to the below two headers on the outbound request from the load balancer to the platform containers:

  • X-Forwarded-Host: the hostname used to access the load balancer. You could also keep the Host header as is rather than setting this header.
  • X-Forwarded-Proto: the protocol used to access the load balancer; HTTPS if the VIP (virtual address for the load balancer) is an HTTPS address, HTTP if the VIP is an HTTP address. You can skip this step if the protocol used from the load balancer to the container is the same as the protocol used from the client to the load balancer.

If needed, get help from the Policy Manager Administrator to make sure these settings are correct.

Akana OAuth/OIDC Provider Domain: Tab 2, Grant Types - Configuration Values

When you're setting up an Akana OAuth/OIDC Provider domain to use the platform as an OAuth/OIDC Provider, the Grant Types page allows you to specify details about the grants your domain will support, including such things as the OAuth grant types and their associated settings, and resource owner authentication domain.

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

Option... Meaning...
Supported Grant Types Choose one or more grant types you want your domain to support, and then set values for each.
Supported Grant Types: 3-Legged

Specify values, depending on the grant types you support.

3-legged, Authorization Code:

  • Grant Validity Period (Days): specify the grant validity period.
  • Authorization Code Timeout (seconds): specify the authorization code timeout.
  • Access Token Timeout (seconds): specify access token timeout.
  • Issue Refresh Tokens: Check the box if refresh tokens will be issued.
  • PKCE Support: Check the box if the PKCE security extension will be supported. Two additional options become available: Enforce PKCE, which makes PKCE required, and Support Plain Transformation, a setting that allows compatibility for deployments already existing or that can't use the S256 transformation.

    For more information, see What is PKCE?

3-legged, Implicit:
Supported Grant Types: 2-Legged

Specify values:
Supported Grant Types: Extensions

The platform supports the JWT Bearer Assertion extension grant type. If you choose this, specify the following:

  • Check or leave the Assertions Issued by This Provider box.

    Note: If you clear the box, you must choose an OpenID Connect provider as the Resource Owner Authentication domain.

  • Specify Grant Validity Period (in days).
  • Specify Access Token Timeout (in seconds).
  • Specify clock skew, in seconds. The default is 600 (10 minutes).
  • Specify whether or not to issue refresh tokens.

For more information, see What is a Bearer Assertion, and what does the platform support for Bearer Assertions?
Client Restriction Settings

This field allows you to add a restriction for which clients a token can be issued to, as an added security precaution.

With the default value, All clients, the platform issues an OAuth token even if the app doesn't have an active contract with the API. However, you can choose to limit this to apps that have an active contract with the API. Options:

  • All clients: Default value. Tokens are issued to all clients with a valid ID.
  • Clients with activated connections to secured API implementations: Change to this value if you want to add a restriction so that tokens are issued only to clients that have a valid connection.
Grant Scope Setting

These settings control how scopes are processed. Choose Provider Scope or Client Default Scope.

Provider Scope is the default. With this option, the client app can request any scope configured for the access grant.

Provider Scope: the scope value to be used for a grant is processed as follows:

  1. If the authorization request/token request has a scope parameter and values (space-delimited string values), the Authorization Server validates whether the scopes are defined in the Akana OAuth/OIDC Provider domain. If they are, it uses the scope value as the grant scope.
  2. If the authorization/token request does not have a scope parameter, the Authorization Server takes the default scopes that are set in the Akana OAuth/OIDC Provider domain and uses them as the grant scope. If no default scopes are defined, the Authorization Server rejects the request and sends an error response.

Client Default Scope: the scope value to be used for a grant is processed as follows:

  1. If the authorization request/token request has a scope parameter and values (space-delimited string values), the Authorization Server first validates whether the scopes are defined in the Akana OAuth/OIDC Provider domain. It then checks that the scopes are valid for the OAuth client. First it scans the APIs connected to the client, and then cumulatively collects all the OAuth scopes defined for these APIs. If the requested scopes are a subset of the app connection scopes, the request is valid and the request scope becomes the value of the grant scope.
  2. If the authorization/token request does not have a scope parameter, the Authorization Server scans the APIs connected to the client, and cumulatively all the OAuth scopes defined for these APIs are collected. These scopes are validated against the scope defined in the OAuth/OpenID Connect provider. If they are valid scopes, the request is valid. If they are not valid scopes, the Authorization Server rejects the request and sends an error message.
Grant Provisioning Timeout (seconds) The length of time for which the grant provisioning session is valid. By default, during grant provisioning, the authentication token is created upon successful resource owner authentication, and is valid until authorization (approval/rejection) is complete, or until the token expires, whichever happens first. By default, the token expires after 600 seconds (10 minutes). You can use this field to extend (or reduce) this default time. The token still expires after authorization is complete.
Resource Owner Authentication Domain

This is the domain your Akana OAuth/OIDC Provider domain will use for end-user authentication as part of the OAuth process. It can be any domain set up on the platform. Choose from the drop-down list. If the domain you want isn't on the list, it must be installed and configured (see notes above). Some possible choices:

  • Google: choose this for authentication with Google.
  • Facebook
  • LDAP

What is PKCE?

Valid in Version: 2020.2.0 and later

In version 2020.2.0, the Akana API platform supports the optional PKCE security extension for OAuth, with the Authorization Code grant type.

In an OAuth exchange, when the authorization code is returned to the client, it could be intercepted by a malicious attacker if it not on a secure channel such as TLS. The attacker could then exchange the authorization code for an access token and gain access to resources.

PKCE helps make sure that the authorization code is not intercepted, by adding an additional key that is sent with the authorization code request, and again with the token request. The key is called a Proof Key for Code Exchange (PKCE).

With PKCE, for each authorization request the client generates two additional values:

  • Code verifier—A unique key, generated by the client according to specific rules laid out in the PKCE standard.
  • Code challenge—The transformed value of the code verifier. There are two options:
    • plain: Adds no transformation (code challenge is the same as the code verifier).
    • S256: Adds ASCII encoding, then SHA256 hashing, then Base-64 encoding, according to the following formula: 
      BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

In the authorization request, the client sends one or two additional parameters for PKCE:

  • code_challenge: The code challenge value.
  • code_challenge_method: Indicates the method used to create the code challenge. If included, the value is either S256 (see the formula above) or plain. If not included, defaults to plain.

The authorization server generates the unique authorization code, associates the code_challenge and code_challenge_method values with it, and sends it to the client.

Next, the client sends the authorization code to the token endpoint, and also sends one additional value:

  • code_verifier: The code verifier value.

The token endpoint takes the authorization code and the code_verifier, and validates the code_verifier against the code_challenge that it got previously. If the values match, the token endpoint issues the token.

In the Akana OAuth/OIDC Provider domain setup, if PKCE is enabled, the platform supports the following additional options:

  • Enforce PKCE—Per the PKCE standard, the code challenge can be required or optional. This setting, checked, corresponds to code challenge required.
  • Support Plain Transformation—Adds PKCE, but with code_challenge_method of plain only. In this scenario, S256 is not supported.

For more information, refer to the specification: https://tools.ietf.org/html/rfc7636.

What are the settings on the Akana OAuth/OIDC Provider Token page and what options should I choose?

When you're setting up an Akana OAuth/OIDC Provider domain to use the platform as an OAuth Provider, the Token page allows you to specify details about the types of access token your domain will support.

The platform supports these token types:

  • Bearer: Two types of bearer tokens (bearer tokens are sent as-is in the API request, in the Authorization header):
    • Referenced Bearer
    • JWT Bearer Access Token
  • MAC

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

Option... Meaning...
Referenced Bearer

A short random token that uniquely identifies the grant, sent as-is in the API request, in the Authorization header. If you enable this token type, you can specify the length of the bearer access token that will be generated. A longer token is stronger. Default: 40.

For more information, see Should I choose Referenced Bearer or JWT Bearer Access token?
JWT Bearer Access Token

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. An advantage of the JWT Bearer Access Token is that the Resource Server can validate by itself without having to go back to the Authorization Server. A JWT Bearer Access Token includes more information and can be significantly longer than a referenced bearer token. For more information, see Should I choose Referenced Bearer or JWT Bearer Access token? If you choose this option, specify values associated with support of this token type:

  • Issuer: The ID of the OAuth Provider that will be included in the access token.
  • ClientID Claim Name: Claim name the OAuth Provider uses for the Client ID in the access token.
  • Scope Claim Name: Claim name the OAuth Provider uses for a scope in the access token. This claim contains space-delimited scopes that are in the grant scope.
  • Resource Owner UID Claim Name: Claim name the OAuth Provider uses for the Resource Owner ID in the access token.
  • Include Resource Owner UserInfo: Indicates whether the resource owner UserInfo should be included in the JWT Bearer Access Token. For more information, see Why choose to include resource owner userinfo in the JWT Bearer Access token?
  • JWT Signing Algorithm: The algorithm used to sign the JWT Bearer access token. For choices, see What JWT signing algorithms are supported? below.
  • Reference Signing Key from Platform Identity: Indicates that the signing key is stored in Policy Manager, associated with a platform identity. Enter the platform identity name exactly as it is set up in Policy Manager. For shared secret, setting up a platform identity is optional but recommended. However, if you are using an asymmetric signature algorithm for signing the access token, you must use a platform identity, and make sure the certificate and private key are set up for this identity. For more information, see Should I set up a platform identity, or provide the credentials in the domain configuration?
  • Encrypt JWT Access Token: Indicates that the JWT Bearer access token should be encrypted. Check the box and specify applicable values. Indicates that the token should be encrypted. If resource owner user information is included in the access token, encryption is important. If you check this box, the following additional fields are available:
    • Reference Encryption Key from Platform Identity: Indicates that the encryption key is stored in Policy Manager, associated with a platform identity. Enter the platform identity name exactly as it is set up in Policy Manager. This identity represents the identity of the application that will be decrypting the access token. To support multiple resource servers, check the Verify JWT Access Token with Authorization Server option and enter the same identity used for signing. For more information, see Should I set up a platform identity, or provide the credentials in the domain configuration?
    • JWT Encryption Key Management Algorithm: The algorithm used to encrypt the encryption key. If you are using symmetric encryption, and when using the shared secret as the encryption key, choose Direct.
    • JWT Content Encryption Algorithm: The algorithm used to encrypt the token body.
MAC The MAC token type. A MAC token includes a digital signature and a nonce, and is more secure than a bearer token. Use of a MAC token by a client is more complex than using a Bearer token; however, the MAC token offers non-repudiation and message replay attack prevention options to the API requests.
Default Access Token Type The access token type that will be used if more than one type is enabled and the client doesn’t select the preferred access token type.
Can Client Override Access Token Type If checked, the app developer can select the specific type of access token for the application's grants.
Access Token Validation

Specify general values relating to validating all types of access tokens. This configuration is used when the resource server validates the access token received in the requests. Values:

  • Clock Skew (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.
  • Verify JWT Access Token with Authorization Server: As an alternative to including userinfo in the token, you might choose to verify the token with the Authorization Server. This adds a processing step, but means that you can keep the token size fairly small, without the userinfo and the associated encryption that might be needed to protect it. There are other advantages. For more information, see Should I choose to verify the access token with the Authorization Server?

Should I choose Referenced Bearer or JWT Bearer Access token?

A Referenced Bearer access token is just an opaque string, with no intrinsic meaning, that is used for authorization (otherwise known as an opaque token). A Referenced Bearer access token has a format that is not intended to be read by you, and is much smaller in size than a JWT Bearer access token. Only the issuer knows the format. The token must be validated by the Authorization server. This comes with the cost of adding latency in your application because you need to add an HTTP request to the Authorization server every time you need to validate the token.

A JWT Bearer access token has readable content; you can decode the token and read the information in it. The recipient of the token (the API Gateway) can validate the token locally by decrypting the message and verifying the signature of the token, or, optionally, the Authorization server can validate the token.

Both of these methods to validate access tokens offer different benefits such as ease of use, cost, and performance. One should find a balanced security that matches the enterprise security standards.

Why choose to include resource owner userinfo in the JWT Bearer Access token?

When you're setting up the Akana OAuth/OIDC Provider domain, Token tab, and choose the JWT Bearer Access token type, you can choose to include resource owner userinfo in the token.

If you want resource owner userinfo to be available, either to the resource server or to the downstream service (target endpoint), and do not want to place an additional call to get the userinfo, you can check the Include Resource Owner User Info box.

If you are including resource user info in the JWT Bearer Access token, it's important to be sure that your network is completely secure, or that the data is encrypted, so that there are no concerns about the userinfo being compromised.

Including the resource owner userinfo in the JWT Bearer Access token increases the size of the token, which is already larger than a Referenced Bearer token. In addition, if the information is encrypted, this further increases the message size. If token size is a potential issue you might choose not to include the resource owner userinfo in the token, and instead make an additional call for the userinfo.

What JWT signing algorithms are supported?

The platform supports the following algorithms for signing Bearer tokens:

  • HmacSHA256
  • HmacSHA384
  • HmacSHA512
  • SHA256withRSA
  • SHA384withRSA
  • SHA512withRSA
  • SHA256withECDSA
  • SHA384withECDSA
  • SHA512withECDSA
  • SHA256withRSAandMGF1
  • SHA384withRSAandMGF1
  • SHA512withRSAandMGF1

The first three are symmetric; the rest are asymmetric.

For more information on the algorithms, refer to the glossary: HMAC, SHA-256, RSA, ECDSA, MGF1.

Should I choose to verify the access token with the Authorization Server?

As an alternative to including userinfo in the token, you might choose to verify the token with the Authorization Server. When you include userinfo in the token, a call to the Authorization Server is not needed; however, this approach has drawbacks of its own, including size and the need for encryption (see Why choose to include resource owner userinfo in the JWT Bearer Access token?).

If you choose to verify the access token with the Authorization Server, this adds a processing step, but means that you can keep the token size fairly small, without the userinfo and the associated encryption that might be needed to protect it.

In this scenario, you are no longer taking advantage of a key feature of the access token, which is the ability for the Resource Server to validate the token. For this reason, you might consider choosing the Referenced Bearer option instead, which has a more compact token size.

One reason why you might prefer to place a call with the Authorization Server is to ensure any grant revocations are considered when validating the access token. In a scenario where the user has revoked the grant, that information might be at the Authorization Server but not at the Resource Server. For more information, see How does the platform manage validation of the JWT access tokens in the resource server when the grant is revoked or cancelled?

Each approach has different advantages. The choice that's best for you will depend on your unique scenario.

What are the settings on the Akana OAuth/OIDC Provider OpenID Connect page and what options should I choose?

When you're setting up an Akana OAuth/OIDC Provider domain, and want to use OpenID Connect as the identity provider, the OpenID Connect page allows you to set up the values that will be needed to act as an OpenID Connect Relying Party to your Identity Provider.

For information about the values set up on the OpenID Connect page (Tab 4), refer to the table below.

Option... Meaning...
OpenID Connect 1.0 Enabled If your Akana OAuth/OIDC Provider Domain will be a relying party for an OpenID Connect Identity Provider, check the box. If not, skip this tab.
Reserved Scopes

Scopes defined by OpenID Connect. Two are selected by default as required:

  • openid: Every OpenID Connect request must have this scope.
  • scope: The ID token doesn't normally include information about OAuth grant scopes. However, when this scope is present, it enables the client to request that when the domain issues an ID token the grant scope is included in the ID token. If an app's grant access request does not specify scopes, all scopes that have the Default scope option checked are included in the scope of the grant. If the app developer wants the scope information returned, he/she can include the scope parameter as part of the authorization request (API > Details > on right, OAuth Details).
  • profile
  • email
  • address
  • phone
ID Token Signing Algorithm Defaults to SHA256withRSA, but many other algorithms are supported. For more information on available options, see What signature algorithms are supported by the platform's Akana OAuth/OIDC Provider?
ID Token Encryption Key Management Algorithm Select the encryption algorithm that the provider will use to encrypt the ID token key.
ID Token Content Encryption Algorithm Select the encryption algorithm that the provider will use to encrypt the ID token content.
ID Token Validity (seconds) The expiration time on or after which the ID Token must not be accepted for processing. Defaults to 3600 seconds.
JSON Web Key Validity (seconds) The time, in seconds, indicating how often the asymmetric signature/encryption keys are rotated.

What is a Grant Property?

Grant Properties are custom values that you can define at the domain level to support collecting information from resource owners (end users) that could be used in the context of giving the app access to the user's resources.

Grant properties are not exposed to apps. They can be used to enhance the user experience when an app invokes the API using the grant.

Examples of grant properties might be: "Notify me when the app uses this grant," or "Only allow withdrawals up to $500."

Downstream from the domain, grant properties allow the API to configure how an app will use the API access permissions that are granted to it. For example, in a banking app, grant properties could be used to allow access to transaction details or current balance, but not allow a withdrawal.

Grant properties are set up in the Akana OAuth/OIDC Provider domain, Tab 6, Properties.

At runtime, the end-user authenticates with the API and then sees the app authorization page. Typically, if there are grant properties, this page will include fields where the end-user can authorize specific access options to the app.

Based on the user's specific authorization, an access token is sent to the app, allowing access to the user's resources that are accessible via the API, as authorized by the user. Any limitations determined by the grant properties are part of the access token.

The app can then use this token to start sending requests. The grant properties are sent back to the client application for validation.

Example (money transfer API):

If the API being secured is a money transfer API, the resource owner might want a restriction to limit the maximum value of a transaction to $100, with a maximum of only one transaction per month (for example, magazine subscription application).

  • To support this, the OAuth provider could define a "Maximum transaction amount" property and a “Maximum number of transactions" per month property in the application, and specify the Property ID (tag) for each of these in the Akana OAuth/OIDC Provider domain definition on Tab 6, Properties.
  • As part of the OAuth approval process, the end-user first authenticates with the identity provider. The user then sees the Authorization page for authorization of the client app to access the user's resources protected by the API. The grant property labels are displayed with text entry fields. The user enters the values for the grant properties and clicks Authorize.
  • The app is granted the requested permissions, but the specific limitations specified by the end-user are applied to the app's permission to limit the app's access to the user's resources.

Navigation: More > Admin >Domains > add or modify Akana OAuth/OIDC Provider domain > Tab 6, Properties

What are the settings on the Akana OAuth/OIDC Provider Branding page and what options should I choose?

When an end-user logs into an app that's connected to an API that uses the Akana OAuth/OIDC Provider domain configuration, the user sees a Resource Owner Authentication page (login page) that is custom branded for the app and for the OAuth provider. That page is configured in the Akana OAuth/OIDC Provider domain setup, on the Branding page.

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

Option... Meaning...
Site Logo Optionally, you can upload a logo to display on the login page. It should be 50px high. For more information, see How do I upload and crop icons?
Footer Text Custom text for the footer of the login page.
Requires SSL Select this check box if your OAuth provider should only accept requests over HTTPS.
Authorization Server URL

The Authorization Server URL set up in your Akana OAuth/OIDC Provider domain configuration; for example, https://www.myauthorizationserver:9800. This is the public URL that apps will use to access this OAuth provider. Can be HTTP or HTTPS. If the Requires SSL box is checked (see above), must be HTTPS.

Based on the Authorization Server URL specified, the platform derives these endpoints:

  • Authorization Endpoint (for OAuth 1.0a and OAuth 2.0): {Authorization Server URL}/oauth/auz/authorize
  • OAuth 2.0 Token Endpoint: {Authorization Server URL}/oauth/oauth20/token
  • OAuth 1.0 Token Endpoint: {Authorization Server URL}/oauth/oauth10/token

If the Akana OAuth/OIDC Provider domain uses OpenID Connect for authentication (OpenID Connect support is checked in the Akana OAuth/OIDC Provider domain configuration, Tab 3):

  • Userinfo Endpoint: {Authorization Server URL}/oauth/userinfo
  • JWKS Endpoint: {Authorization Server URL}/oauth/jwks

For an OpenID Connect provider, all the endpoints and provider details are available via the discovery URL/well-known configuration URL:

  • {Authorization Server URL}/.well-known/openid-configuration

Firewalls and DNS servers must be set up for this URL so that end users and apps can access the URL. This protocol/host/path should resolve to one or more containers with the Akana OAuth Provider feature installed.

For more information, including the specific paths for different OAuth URLs for the OAuth provider, see What are the OAuth endpoints for the platform?

Notes re OAuth URLs:

  • In versions prior to 2020.1.0, a trailing slash on the Authorization Server URL results in failure to validate a Private Key JWT token (private_key_jwt), with an error that the aud claim does not match the intended audience. In version 2020.1.0 and later, the Community Manager developer portal resolves this internally.
  • 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?).
Additional Virtual Hosts

If your OAuth provider has one or more additional virtual hosts, as well as the hostname in the Authorization Server URL, enter the additional hostnames, separated by commas.

Note: The Authorization Server must be able to resolve these virtual hosts to an IP address.
Grant Provisioning UI URL The URL for your OAuth provider’s grant provisioning UI, if your provider has its own UI. To send the grant as a parameter in the URL, include the {GrantID} placeholder in the URL. If you want your OAuth provider to use the grant provisioning UI provided by the platform, leave this field blank.
Grant Workflow Definition The workflow definition that will apply to all new OAuth grants. You can use this field to implement a custom workflow for OAuth. 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.
Grant Administration Session Timeout (seconds) The length of time for which the grant administration session is valid. By default, for grant administration, the authentication token is set upon successful authentication and is valid until the token expires, the token is renewed, or the user logs out, whichever happens first. By default, the token expires after 600 seconds (10 minutes). You can use this field to extend (or reduce) this default time.

How can I set up my Akana OAuth/OIDC Provider domain to support end-user login from an external identity provider?

You can set up an Akana OAuth/OIDC Provider domain to support SSO with an external identity provider with these two types of identity provider:

  • An identity provider that only has APIs rather than offering a user interface for login—such as LDAP or CA SiteMinder
  • An identity provider that provides a login application—such as OpenID Connect or SAML Web SSO Identity Provider. In this scenario, the platform can redirect the user to the login application and then have the login application redirect the user back to the OAuth Provider after authentication.

Using this approach, depending on where your end-user identities are, you can configure different domains and use the appropriate domain as the resource owner authentication domain in the OAuth Provider configuration (Grant Types tab). For example, you would configure an OpenID Connect Relying Party domain, a SAML Web SSO domain, an LDAP domain, or a CA SiteMinder domain.

What is an Authorization Server URL?

As part of setting up the OAuth Provider domain to use the platform as an OAuth provider, the Business Admin must specify the Authorization Server URL for the platform. This is the URL for the server designated by the OAuth provider to perform the authorization steps to a) authenticate the resource owner (or to delegate the authentication process to a trusted identity provider), and b) get the resource owner's permission for the app to access the resources. The app directs the resource owner (user) to the Authorization Server URL; when the authorization steps are complete, the Authorization Server returns the user to the app, using the redirect URL provided by the app.

The Authorization Server URL is the URL at which the OAuth Provider accesses the requests, for both Authorization Endpoint and Token Endpoint.

Note: One deployment can support more than one OAuth Provider. If there is more than one, it is important that each OAuth Provider has a different Authorization Server URL, for both Authorization Endpoint and Token Endpoint.

When setting up an Akana OAuth/OIDC Provider domain on the platform, once you have specified the Authorization Server URL it is important to make sure that requests are directed to this URL where the Akana OAuth Provider feature is installed. This might include additional actions; for example, adding a DNS entry or configuring the load balancer if the URL is a virtual endpoint on F5. If you are setting up an External OAuth Provider domain, this is not necessary.

The URL you provide for the Authorization Server is the base of the URL for the Request Token URL, Access Token URL, and Authorize URL, with additional parts of the paths as shown below. The Callback URL is the Redirect URL that an app developer would provide in the App details page.

For specific Authorization Server URLs for the platform, see What is the OAuth Authorization Server URL for the platform? below.

Note: In most cases, when setting up an Authorization Server URL in domain configuration, make sure there are no training characters on the URL, including a training slash.

What is the OAuth Authorization Server URL for the platform?

When you are setting up an Akana OAuth/OIDC Provider domain on the platform, the URL you provide for the Authorization Server (OAuth endpoint) is the base of the URL for the Request Token URL, Access Token URL, and Authorize URL, with additional parts of the paths as shown below.

When setting up the OAuth Authorization Server URL in the platform, enter only the base of the URL, including protocol, host, and port if needed. The platform appends the appropriate path as listed below after the {oauth.provider.url} variable.

For example, let's say the Authorization Server URL you specify in the provider configuration is:

https://www.acmepaymentscorp.com:9800

Use that value in place of the {oauth.provider.url} placeholder. The platform appends the rest of the URL in each case.

For OAuth 2.0, the OAuth Authorization Endpoint URL becomes:

https://www.acmepaymentscorp.com:9800/oauth/auz/authorize

OAuth Token Endpoint URL becomes:

https://www.acmepaymentscorp.com:9800/oauth/oauth20/token

For general information on Authorization Server URLs, see What is an Authorization Server URL? above.

Notes:

  • App developers need to know the Authorization Server URL in order to set up their apps to use the OAuth domain. This information must be made available to API Admins, who must make sure it is included in API documentation.
  • If you are setting up an External OAuth Provider domain, you'll need to provide the Authorization Server URL of your provider. Generally, this is available at the well-known configuration endpoint. See When would I choose an External OAuth Provider domain?
  • In most cases, when setting up an Authorization Server URL in domain configuration, make sure there are no training characters on the URL, including a training slash.

What are the OAuth endpoints for the platform?

The full URLs for both supported OAuth versions are shown below.

OAuth endpoints for 1.0a:

  • OAuth Authorization Endpoint URL: {oauth.provider.url}/oauth/auz/authorize
  • OAuth Token Endpoint Request Token URL: {oauth.provider.url}/oauth/oauth10/initiate
  • OAuth Token Endpoint Access Token URL: {oauth.provider.url}/oauth/oauth10/token

OAuth endpoints for 2.0:

  • OAuth Authorization Endpoint URL: {oauth.provider.url}/oauth/auz/authorize
  • OAuth Token Endpoint URL: {oauth.provider.url}/oauth/oauth20/token

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 OAuth custom headers?

When an API uses the platform as a proxy, in the API setup the API is the Target API and the platform is the Proxy API.

When an app sends a request, if the API is using the platform as a proxy API and is using the OAuth policy, the platform adds custom headers in the outbound request from the proxy API. These custom headers include key information necessary for the transaction, such as resource owner identity and grant properties.

For more detailed information about these headers, refer to How does the proxy API send OAuth-related information to my API? (API Admin documentation).

What is a Bearer Assertion, and what does the platform support for Bearer Assertions?

The platform supports the Token, or Bearer Assertion, which is an extension grant type that is generally used when the app already has an Assertion that represents the resource owner. The app sends the Assertion to the Authorization Server’s Token Endpoint to get an access token for later use.

The Bearer Assertion is generally issued by an Identity Provider and consumed by a Relying Party that relies on its content to identify the subject—that is, the user being authenticated.

The platform supports Bearer Assertions:

  • Issued by the platform. To use Bearer Assertions issued by the platform, they must be issued by the same OAuth Provider. If there are multiple Akana OAuth/OIDC Provider domains, you cannot use Bearer Assertions issued by a different platform OAuth Provider. It must be the same OAuth Provider producing and consuming the Bearer Assertion.
  • Issued by a different provider. To use Bearer Assertions issued by a different provider, the Resource Owner authentication domain must be an OpenID Connect Relying Party domain. The Akana OAuth/OIDC Provider domain can use the Bearer Assertions issued by the external OpenID Connect Provider.

In the context of the platform, when the token is used as an access token, all the information needed for the access token is already part of the token. This is efficient in terms of processing.

This grant type supports refresh tokens.

What token types should I support?

When setting up your Akana OAuth/OIDC Provider domain, on the Token tab, there are three key choices for tokens:

  • Bearer: Two types of bearer tokens (bearer tokens are sent as-is in the API request, in the Authorization header):
    • Referenced Bearer
    • JWT Bearer Access Token
  • MAC

Below is some information about the different types of access tokens, to help you decide which one to choose, or whether you should support more than one option.

Note: If you are using an External OAuth Provider domain, the available possibilities depend on the token types your provider supports

Referenced Bearer

A short random token that uniquely identifies the grant, sent as-is in the API request, in the Authorization header. If you enable this token type, you can specify the length of the bearer access token that will be generated. A longer token is stronger. Default: 40.

Referenced Bearer tokens and JWT bearer access tokens are similar, but validating a Referenced Bearer token requires a round trip to the OAuth provider to validate the bearer token and to obtain the scope and the user's claims.

For more information, see Should I choose Referenced Bearer or JWT Bearer Access token?

JWT Bearer Access Token

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. An advantage of the Bearer access token is that the Resource Server can validate by itself without having to go back to the Authorization Server.

This token type provides the fastest option for security. However, a Bearer token includes more information and can be significantly longer than a Referenced Bearer token. In addition, it does not include protection against a replay attack (the nonce in the MAC token), and there is no specification governing how to check whether a specific access token has been revoked.

For more information, see Should I choose Referenced Bearer or JWT Bearer Access token?

MAC

A MAC token includes a digital signature and a nonce, and is more secure than a bearer token. Use of a MAC token by a client is more complex than using a Bearer token; however, the MAC token offers non-repudiation and message replay attack prevention options to the API requests.

Supporting multiple token types

Supporting multiple token types requires a more complex implementation but offers users more options.

When you specify more than one token type, you can specify a default. You can also choose whether or not to allow users to override the default.

How does token encryption work?

In general, most OAuth messages include some level of encryption, for security purposes.

Symmetric is a lower level of security, implemented in the platform with the app Shared Secret. Asymmetric is a higher level of security, implemented with a public/private key pair and certificate. Within those two divisions there are different levels of security according to factors such as the specific algorithm used and the length of the token.

Normally, encryption is a two-step process as covered below.

Encryption process

  1. The entire message is encrypted using a symmetric encryption algorithm.
  2. For extra security, the second step is encryption of the random symmetric message key. There are three possible levels:
    • Maximum security: encryption of the message key with an asymmetric encryption algorithm.
    • Less secure but still very secure: encryption of the message key with a symmetric encryption algorithm (either the same one, or a different one).
    • Least security: no encryption of the key.

Decryption process

Decrypting the message is an exact reversal of the encryption process:

  1. Decryption of the message key (assuming it was encrypted).
  2. Decryption of the entire message using the decrypted message key.

How does the platform manage validation of the JWT access tokens in the resource server when the grant is revoked or cancelled?

By default, JWT access tokens are always validated at the gateway (Network Director). The gateway periodically downloads all revoked and cancelled grants that have unexpired access tokens, and keeps this information in local memory, to be used while processing a JWT token. It can then reject JWT access tokens for grants that have been revoked or cancelled.

This is also true of other token types such as Referenced Bearer or MAC tokens.

Initially, the grant corresponding to the token is stored in local memory at the resource server, for faster processing. If a grant is modified (via workflow, revocation, or any other means), the modified grant is updated in the local memory asynchronously, via the scheduled job, which runs at an interval of 1 minute. Until that time, requests continue to be successful.

A possible drawback to this approach is that the JWT access token continues to be successful at the gateway until the scheduled job updates the local cache with cancelled/revoked grant information. This could mean that JWT access tokens for revoked grants could be accepted for a short period of time before they start to be rejected. The scheduled job runs at an interval of 1 minute.

This scenario is similar to browsers downloading the Certificate Revocation List (CRL) from the certificate authorities (CAs).

Note: The Business Admin can configure the Akana OAuth/OIDC Provider domain to have the gateway verify JWT Access Tokens with the Authorization Server as well (Akana OAuth/OIDC Provider Domain, Tab 3, Token: Verify JWT Access Token with Authorization Server). In this scenario, validation is similar to that of the Referenced Bearer token. However, with this approach you lose a key feature of the JWT Access Token, the ability for the Resource Server to validate the token.