Domains

Configure domains that can be used for login or as authentication domains for APIs defined in the platform.

Detailed information about certain domains is in these additional files:

API Platform Version: 8.1 and later

Table of Contents

  1. What domain types are supported on the platform?
  2. How do I add a domain?
  3. How do I modify a domain?
  4. How do I delete a domain?
  5. How do I set up a login domain?
  6. How do I enable a domain for login?
  7. How do I configure a Platform Login domain?
  8. How do I set up an LDAP domain?
  9. How do I set up an OpenID Connect Provider domain?
  10. Do I choose the OpenID Connect Relying Party domain or the External OAuth Provider domain?
  11. Do I choose the PingFederate domain or the External OAuth Provider domain?
  12. Should I set up a platform identity, or provide the credentials in the domain configuration?
  13. How do I set up a platform identity for my domain?
  14. What is JWT?
  15. What are the options for signing and encryption of JWT access tokens?
Facebook Domain:
  1. How do I set up the platform to log in with Facebook (Facebook Connector domain)?
Google Connector Domain:
  1. How do I get Google credentials for a Google Connector domain?
  2. How do I set up a Google Connector domain?
  3. How do I set up the platform to log in with Google?
  4. What value should I use for the Redirect URI for my Google Connector domain?
  5. How do I customize the Google user consent page for my Google Connector domain?
OAuth/OIDC Provider Domain:
  1. Which type of OAuth Provider domain should I set up?
  2. How does the OAuth/OIDC Provider configuration process work?
  3. How do I set up a platform deployment to support a third-party OAuth provider?
  4. How do I set up my deployment to support OAuth?
  5. How do I set up and configure an OAuth/OIDC Provider domain?
  6. What are the settings on the OAuth/OIDC Provider Grant Types page and what options should I choose?
  7. What are the settings on the OAuth/OIDC Provider Token page and what options should I choose?
  8. Should I choose Referenced Bearer or JWT Bearer Access token?
  9. Why choose to include resource owner userinfo in the Bearer Access token?
  10. What JWT signing algorithms are supported?
  11. Should I choose to verify the access token with the Authorization Server?
  12. What is a Grant Property?
  13. What are the settings on the OAuth/OIDC Provider OpenID Connect page and what options should I choose?
  14. What are the settings on the OAuth/OIDC Provider Branding page and what options should I choose?
  15. How can I set up my OAuth/OIDC Provider domain to support end-user login from an external identity provider?
  16. What is an Authorization Server URL?
  17. What is the OAuth Authorization Server URL for the platform?
  18. What are the OAuth custom headers?
  19. What is a Bearer Assertion, and what does the platform support for Bearer Assertions?
  20. What token types should I support?
  21. How does token encryption work?
  22. How does the platform manage validation of the JWT access tokens in the resource server when the grant is revoked or cancelled?
External OAuth Provider Domain:

Refer to detailed information in separate file: External OAuth Provider Domain.

Open ID Connect Domain:

Refer to detailed information in separate file: Open ID Connect Domain.

SAML Web SSO/SLO Domain:
  1. How do I set up the platform to log in with SAML Web SSO?
  2. How do I set up the platform for single logout (SLO) using SAML?
CA SiteMinder Domain:
  1. How do I set up the platform to log in with CA SiteMinder (CA SiteMinder domain)?
PingFederate Domain:
  1. What versions of PingFederate does the platform support?
  2. How do I configure an External OAuth Provider domain for PingFederate? (recommended)
  3. How do I configure a PingFederate Connector domain? (legacy)

What domain types are supported on the platform?

The security domains configured on the platform can be used in multiple contexts, including:

  • Login domain, for logging in to the portal
  • Resource owner domain, for OAuth resource owners
  • App authentication in API runtime, for sending API requests

One domain can be used for multiple purposes, or separate domains can be configured for separate purposes.

When a specific domain is configured for the purpose of developer logins to the portal, it is called a login domain.

The table below shows supported domains and how they are used.

Domain Developer Portal Login? OAuth Resource Owner Login?
Platform Login (no setup required) Yes No
External OAuth Provider No Yes
Facebook® Connector Yes Yes
Google® Connector Yes Yes
OAuth/OIDC Provider No Yes
OpenID Connect Relying Party Yes Yes
PingFederate® Provider No No
LDAP (must first be set up in Policy Manager) Yes Yes
CA SiteMinder (Requires installation, and then setup in Policy Manager) Yes Yes
SAML (requires installation, and then setup in Policy Manager) Yes Yes

Back to top

How do I add a domain?

To add a domain:
  1. Log in as the Business Admin and go to the Admin section.
  2. Click Domains. The Domains Summary page displays.
  3. On the right, click Add Domain.
  4. Choose from the supported domain types, and then follow the applicable setup instructions. See What domain types are supported on the platform? above.
  5. When the domain is set up, if you want to offer it for login you must enable it as a separate configuration step. See How do I enable a domain for login?

Back to top

How do I modify a domain?

To modify a domain:
  1. Log in as the 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. Follow the setup instructions for the specific domain type. The process for editing is similar to the process for adding a domain, although some fields, such as the domain name, cannot be changed. See What domain types are supported on the platform? above.

Back to top

How do I delete a domain?

To delete a domain:
  1. Log in as the 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, in the Config options. For instructions, see How do I disable a platform login?

Back to top

How do I set up a login domain?

To make a login domain available to users for logging in to the platform, you must perform two steps:

  1. Configure the applicable domain: Administration > Domains. Domains applicable to login are:
  2. Enable the domain for login. This is a configuration step: Administration > Config > Logins (Enable check box). For more information, see How do I enable a domain for login?

Once these two steps are complete, the login options you've configured and enabled are available for anyone logging in to the platform.

Back to top

How do I enable a domain for login?

To make a login domain available to users for logging in to the platform, two steps are needed:

  1. Business Admin: Configure the applicable domain: Administration > Domains. For information about domains that are applicable to login, see What domain types are supported on the platform?
  2. Site Admin: Enable the domain for login: Administration > Config > Logins (Enable check box). See How do I enable and customize a platform login domain? (Site Admin help).

Back to top

How do I configure a Platform Login domain?

Installation of the platform automatically creates a Platform Login domain. This login domain type allows users who have signed up on the platform to log in via the default platform login page using their email and password login credentials.

Although the Platform Login domain is created automatically, it must still be enabled for login by the Site Admin. This is a configuration step: Administration > Config > Logins page (Enable check box). For more information, see How do I enable a domain for login?

The default Platform Login domain cannot be deleted.

Back to top

How do I set up an LDAP domain?

The platform provides support for users logging in using LDAP credentials.

You must first define the LDAP domain in the Policy Manager Management Console, in Configure > Security > Identity Systems. For more information, refer to the Add Identity System (Active Directory) topic in the Policy Manager Online Help.

Once the domain is defined in Policy Manager, you can enable it for login in Akana API Platform. See To enable a login domain.

Once setup is complete, when users sign in they will see the LDAP icon on the platform login page and will be able to choose LDAP for login.

Back to top

How do I set up an OpenID Connect Provider domain?

If you're setting up an OpenID Connect Provider domain, you'll need to choose the OAuth/OIDC Provider domain option (Admin > Domains > Add Domain > choose OAuth/OIDC Provider). For full instructions, see How do I set up and configure an OAuth/OIDC Provider domain?

There are some differences between an OAuth/OIDC Provider and an OpenID Connect Provider; for example, OpenID Connect has the userinfo endpoint. The platform's OAuth/OIDC Provider domain option accommodates both.

Some points to note:

  • Authentication domain: You must already have set up a resource owner authentication domain, such as an LDAP domain, for user authentication. The OpenID Connect Provider domain you set up will reference the existing authentication domain for user authentication.
  • Tab 4, OpenID Connect, is where you specify that this is an OpenID Connect Provider domain. In addition, if you need to define additional scopes for your domain, add them here.
  • Tab 6, Branding: You'll need to specify the authorization server URL.
  • If you just want to use OpenID Connect to authenticate the resource owner, you don't need a Provider domain at all. Instead, choose the OpenID Relying Party Domain (see How do I configure an OpenID Connect Relying Party domain?). The OAuth / OpenID Connect Provider domain is the one to choose if you want to use the platform as an OpenID Connect Provider, issuing tokens and granting access to resources.
  • The userinfo endpoint for the domain is: {authorization_server_url}/oauth/userinfo. For example, if the authorization server URL is https://www.myauthorizationserver:9800, the userinfo endpoint is https://www.myauthorizationserver:9800/oauth/userinfo. See Authorization Server URL (help for Branding tab).

Once the domain is set up, you can associate it with an API and test it in Test Client to make sure everything is working as expected.

Back to top

Do I choose the OpenID Connect Relying Party domain or the External OAuth Provider domain?

Both these domain options, OpenID Connect Relying Party and External OAuth Provider, allow you to reference an external OAuth / OpenID Connect provider. So, how do you determine which option is best for you?

These two options are used for different purposes, and collect different information. Essentially it depends on your purpose, authenticating users or securing OAuth requests:

  • If you want to use an external OpenID Connect provider to authenticate end users: choose the OpenID Connect Relying Party domain.
  • If you want to use an external OAuth Provider to secure API requests: choose the External OAuth Provider domain.

Back to top

Do I choose the PingFederate domain or the External OAuth Provider domain?

If you are using PingFederate, you have two domain options:

  • PingFederate add-on/PingFederate domain: You can install the PingFederate add-on in Policy Manager and then set up a PingFederate domain in the Akana API Platform
  • External OAuth Provider: You can set up an External OAuth Provider domain in the Akana API Platform (no Policy Manager setup required).

We strongly recommend you choose External OAuth Provider, which requires less setup and includes additional features.

The platform has supported the PingFederate domain for some time. However, the External OAuth Provider has all the features of the PingFederate domain and also includes additional functionality.

Support of the PingFederate domain will be deprecated and removed in the future. We recommend that all PingFederate customers use the External OAuth Provider domain.

An important advantage is that the External OAuth Provider domain supports 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.

Back to top

Should I set up a platform identity, or provide the credentials in the domain configuration?

Many domains, especially OAuth-related domains, require credentials. When you're setting up your domain, you can set up those credentials as part of the domain definition in the developer portal by entering and/or uploading applicable keys and certificates.

However, as an alternative, you have the option of creating an organization identity in the Policy Manager console, and setting up the security information in Policy Manager. You can then reference the organization identity from the domain setup. With this approach, secure information is not included in the domain configuration.

Keeping all secure information in the identity store, rather than setting up the credentials in the domain definition, is the best option for several reasons:

  • Domain configuration is not encrypted in the database, but is encrypted in the identity store.
  • Domain configuration is not transported securely from one machine to another within the platform infrastructure.
  • The identity store has additional security for storing the private keys, passwords, and shared secrets.

Note: In most cases, one OAuth/OIDC Provider or External OAuth Provider domain can support one resource server and one associated platform identity (audience field, certificate, and private key or shared secret). An exception to this is that the External OAuth Provider domain can support multi-valued input in the audience field.

If you want to set up a scenario where multiple resource servers can validate the tokens, use the Referenced Bearer option. A key feature of the bearer access token is that validation can be done at the resource server; but only one resource server can be supported. You can support a scenario of multiple resource servers by choosing to have the bearer access token validated at the Authorization Server; however, in this case you lose the key advantage of Bearer access tokens.

If you have multiple resource servers, and choose the same identity for all resource servers, the platform treats it as a single resource server running on multiple machines.

The table below shows which domains support referencing a platform identity, and in what capacity.

Domain Purpose What configuration properties of the identity store are used?
OAuth/OIDC Provider (Token tab) Bearer Access Token signature (always required, since signature is always enabled)

Depending on the signature algorithm selected, either password/shared secret or the Private Key/certificate options are used:

  • If symmetric signature algorithm is selected, set up shared secret/password in the platform identity.
  • If asymmetric signature algorithm is selected, set up private key with certificate in the platform identity.
OAuth/OIDC Provider (Token tab) Bearer Access Token encryption (Optional: enabled only if encryption is enabled) If symmetric encryption algorithm is selected, set up shared secret/password in the platform identity. If asymmetric encryption algorithm is selected, set up only X.509 certificate. This is the certificate of the audience of the access token. Obtain the certificate from the entity that is going to validate the access token, and then upload it for this identity.
OpenID Connect Relying Party Domain (App tab) AppID of the relying party application. This domain provides the option to enter the AppID and shared secret within the domain or create a platform identity to represent this AppID. It is best to create a platform identity for the OpenID Connect relying party application rather than entering the AppID and shared secret in the domain configuration. If the ID Token involved is using asymmetric encryption, creating a platform identity is the only choice, since the domain's inline configuration only supports shared secret, not private key.
External OAuth Provider (Access Token Validation tab) Access Token signature validation (Tab 4, Access Token Validation) This domain supports inline configuration for symmetric signing key or shared secret, and also supports configuring these in a platform identity and referencing the platform identity. Shared secret and password are needed only if symmetric signatures are used: certificate is needed only if asymmetric signatures are used. This is the certificate of the provider that is issuing the access token. Obtain the certificate from the provider and configure it in this domain (either inline or associated with a platform identity).
External OAuth Provider (Access Token Validation tab) Bearer Access Token decryption The domain setup doesn't include any inline configuration encryption. If Bearer access tokens are encrypted, you must configure a platform identity. If symmetric encryption is used, associate the shared secret; if asymmetric encryption is used, associate the private key. The corresponding certificate should be provided to the administrator of the External OAuth Provider domain so that the provider configuration can be set up for encryption with this certificate.
External OAuth Provider when provider type is PingFederate (Access Token Validation tab) JWT Bearer Access Token (validation by provider) PingFederate needs to authenticate (with appropriate roles) the resource server that is asking for validating Bearer access tokens (either JWT Bearer or Referenced Bearer). This domain supports both inline configuration as well as platform identity option for the resource server credentials. If setting up platform identity, only configuration needed is shared secret/password.
External OAuth Provider when provider type is PingFederate (Extensions tab) Client registration When client registration is enabled, the application that registers the clients must be set up with PingFederate and must have credentials with an appropriate role. This domain provides inline configuration as well as the platform identity reference option, to collect the application username/password. If setting up a platform identity for this, the platform identity needs only the password.

Back to top

How do I set up a platform identity for my domain?

You might need to coordinate with the platform Sys Admin to set up a platform identity in Policy Manager. The procedure below explains very briefly the steps to be taken. For additional information refer to the Policy Manager online help.

Note: If the Certificate Authority is not yet set up, you'll need to do that before you can complete the steps below. In Policy Manager, click Configure > Security > Certificates > Certificate Authority. Click Configure Certificate Authority and enter the information. You cannot upload the keys and certificates until you've set up the Certificate Authority.

To set up a platform identity in Policy Manager for a domain in the developer portal
  1. In Policy Manager, choose the tenant, and then, on the right, click Add Organization Identity. (You could also choose an existing organization identity and go to Step 4).
  2. Choose a name that will easily identify the purpose, and provide a description.
  3. Set up password information and click Finish.
  4. From the Actions menu, choose Manage PKI Keys.
  5. On the Select Key Management Option page, choose Generate PKI Keys and x.509 Certificate and click Next.
  6. Enter certificate details, click Finish, and then click Close.

Back to top

What is JWT?

A JWT token is a light weight equivalent to SAML for a security token. JWT (JSON Web Token) tokens are based on JSON and are used in new authentication and authorization protocols such as OpenID Connect and OAuth 2.0. There are two kinds of JWT tokens the platform uses in OAuth:

  • JWT ID token. OpenID Connect 1.0 uses id_token to encode all the user's claims. For example, OpenID Connect could return the id_token with all the user attributes from the LDAP server. JWT ID tokens are signed and optionally encrypted. They are consumed by apps and are signed with either the app's shared secret (known to the app) or the OAuth provider's private key (generally rolling PKI keys published at the OAuth/OIDC Provider's JWK Set URL).

    Depending on configuration, the OpenID Connect provider might issue the JWT ID token either from the Authorization Endpoint or the Token Endpoint.

  • JWT Access token. A JWT token that is used as an access token. The JWT Access Token primarily includes the scope of the access token, though it might optionally also include the user's claims. JWT access tokens are issued by the OAuth provider, for consumption by the resource server.

Back to top

What are the options for signing and encryption of JWT access tokens?

The table below shows what happens with different encryption options for signatures.

Signature algorithm ID token signature JWT token signature
asymmetric

The ID token is signed with rolling keys. A separate PKI key is created each day (time period is configurable) and is used to sign the ID token that's issued.

Clients must use the JWKSet endpoint to get the correct certificate/public key needed to verify the signature.

The JWT access token is signed with a fixed PKI key that is assigned to a platform identity. How signature verification works exactly depends on the nature of the resource server:

  • If the Resource Server is the platform (Network Director), it retrieves the certificate/public key from the platform identity and uses it to validate the signature.
  • If the Resource Server is external, it cannot retrieve the certificate/public key dynamically. Instead, the Site Admin must export the certificate/key from Policy Manager and share it with the external Resource Server.
symmetric

The ID token is signed with the client's shared secret.

Since the client has its own shared secret, it can use the shared secret to validate the signature.

The JWT access token is signed with the password/shared secret set up for the associated platform identity. How it works exactly depends on the nature of the resource server:

  • If the Resource Server is the platform (Network Director), it retrieves the key from the platform identity and uses it to validate the signature.
  • If the resource server is an external OAuth Provider, it cannot retrieve the key dynamically. Instead, the Site Admin must provide the signing key that the Resource Server must use to validate the signature.

The table below shows what happens with different encryption options for key management.

Key management option Encryption key for ID token Encryption key for JWT access token

Direct

Client's shared secret is used to derive the encryption key for the ID token.

Password/shared secret set up in the configured platform identity is used to derive the encryption key for the JWT access token.

Symmetric

A random key is used as the encryption key for the ID token. This random key is also included in the ID token after encryption after encryption with a key encryption key or key management key that is derived using the client's shared secret.

A random key is used as the encryption key for the JWT access token. This random key is also included in the JWT access token after encryption with a key encryption key or key management key that is derived using the password/shared secret configured for the applicable platform identity.

Asymmetric

A random key is used as the encryption key for the ID token. This random key is also included in the ID token after encryption with the client's certificate.

Since the client has its own private key, it can use the private key to decrypt the ID token.

A random key is used as the encryption key for the JWT access token. This random key is also included in the JWT access token after encryption with the certificate configured for the applicable platform identity. How it works exactly depends on the nature of the resource server:

  • If the Resource Server is the platform (Network Director), it retrieves the private key from the platform identity and uses it to decrypt the JWT access token.
  • If the resource server is an external OAuth Provider, such as CA SiteMinder, the Admin for the external provider must export the p12 file of the platform identity and provide it.

Back to top

Facebook Domain:

How do I set up the platform to log in with Facebook (Facebook Connector domain)?

The Facebook Connector domain allows users to log into the platform using Facebook credentials. Essentially, the Business Admin registers the platform with Facebook as a Facebook app, and then uses the values provided by Facebook for App ID and App Secret to set up the Facebook Connector domain.

Once this is set up, the Facebook icon appears during signup and users can log in using Facebook credentials.

Note: For certain activities, such as creating an API or using the platform API, users must complete the standard platform signup process. Logging in with Facebook is not adequate for these activities.

Before setting up the domain in the platform, you'll need to register the platform as an app on the Facebook developer site at https://developers.facebook.com/apps and get the Facebook App ID and Shared Secret values for your instance of the platform.

Once the domain is set up, the last step is to enable it.

Once setup is complete, users signing in will see the Facebook icon on the platform login page and can choose Facebook for login.

To set up a Facebook Connector domain:
  1. Log in as the Business Admin and go to the Admin section.
  2. Click Domains. The Domains Summary page displays.
  3. Click Add Domain. The Select Domain Type drop-down menu displays.
  4. Select Facebook Connector and click Select. The Add Connector Domain wizard opens at the Details page.
  5. Specify values for Name and Description and then click Next.
  6. For App ID and App Secret, provide the values that were assigned by Facebook when you registered your instance of the platform as an app at https://developers.facebook.com/apps.
  7. Click Save.
  8. When the domain is set up, you must enable it on the Administration > Config > Logins page. See To enable a login domain. For information on Facebook login button usage, see https://www.facebookbrand.com.

Back to top

Google Connector Domain:

How do I get Google credentials for a Google Connector domain?

Before setting up a Google Connector domain in the platform, you'll need to register the platform as an app on the Google developer site at https://console.developers.google.com/project and get the Google App ID and Shared Secret values for your instance of the platform.

If you're planning to use the Google Connector domain for user login associated with using OAuth, you'll also need to

Once you have your credentials, you can set up your Google Connector domain. See To set up a Google Connector domain in the Akana API Platform below.

Tip: When you're setting up things up in your Google account, remember to enable the Google+ API (Step 3 in the procedure below). If you omit this step, your login won't work.

You can also view a tutorial video on YouTube: Configure the Akana Developer Portal to Use Google Login (external link).

To get credentials for a Google Connector domain:

Note: the instructions below relate to the Google developer site, which might change over time. Even if the details change, the basic steps will remain the same.

  1. Go to the Google Developers Console at https://console.developers.google.com/project and choose Create Project.
  2. Give your project a name and ID. For the ID, you can accept the suggested ID, click the Refresh icon to get a new suggestion, or choose your own ID. Click Create.
  3. The next step is to subscribe to the Google+ API. On the left, click APIs & Auth and then click APIs. Find the Google+ API on the list, and click the button to enable it. This is the API your app will use to allow users to log in with Google on the platform. Make sure the status for the Google+ API shows as ON. If the API status is OFF, your users will see an "Unauthorized" status code when they try to use the Google login.
  4. Next, get the credentials for your app:
    1. On the left, click APIs & Auth and then click Credentials.
    2. In the OAuth section, click Create New Client ID.

      Note: If credentials already exist for your app, find the correct set of credentials and then find the Client ID and Client Secret for the credentials. Your project might have several sets of credentials; for example, there might be different credentials for a web application, service account, Compute Engine, App Engine, and/or different installed applications such as Android, Chrome, or iOS. Some types of credentials might have a Client ID without a Client Secret. You can create additional credentials as needed.

    3. Make sure Application Type is Web Application.
    4. In the Authorized Redirect URI field, enter the applicable redirect URI. For a login domain, enter: {protocol}://{hostname}/api/login/ssoLogin. For example: https://www.example.com/api.ssoLogin. For other types of domain, refer to the table at What value should I use for Redirect URI for my Google Connector domain? below. Google requires that the redirect URL is a public URL.
  5. Save the values on the Google website and also have them available for the next step, setting up your Google Connector domain in the Akana API Platform. See To set up a Google Connector domain in the Akana API Platform below.

Back to top

How do I set up a Google Connector domain?

The Google Connector domain allows users to log in to the platform using Google credentials, and can be used for other activities such as OAuth support. Essentially, the Business Admin registers the platform with Google as a Google app, and then uses the values provided by Google for Google AppID and Google App Shared Secret to set up the Google Connector domain.

Note: Earlier versions of the platform used the OpenID Relying party domain for Google login. It's important to now use Google Connector, which relies on a newer technology recommended and supported by Google; the OpenID Relying party domain uses an older API which Google has scheduled for end of life.

Note: For certain activities, such as creating an API or using the platform API, users must complete the standard platform signup process. Logging in with Google is not adequate for these activities.

You can also view a tutorial video on YouTube: Configure the Akana Developer Portal to Use Google Login (external link).

To set up a Google Connector domain in the Akana API Platform:
  1. First, get your credentials from the Google Developers Console. See To get credentials for a Google Connector domain above.
  2. Log in as the Business Admin and go to the Admin section.
  3. Click Domains. The Domains Summary page displays.
  4. Click Add Domain. The Select Domain Type drop-down menu displays.
  5. Select Google Connector and click Select. The Add Connector Domain wizard opens at the Details page.
  6. Specify values for Name and Description and then click Next to go to the App Details page of the wizard.
  7. For Google Client ID and Google Client Secret, provide the values that were assigned by Google when you registered your instance of the platform as a web application at https://console.developers.google.com/project.
  8. Click Next to go to the Realm Details page.
  9. Conditional: if you were using OpenID for Google login in an earlier version of the platform (OpenID Relying Party connector), and want to map values between the old and the new connectors, set up the following:
    • To map user accounts to your Google Connector domain, enter the Realm value for your OpenID Connector. It must be a fully qualified URL, including protocol, and must match the value set up on the Client Details page for your OpenID Relying Party domain.
    • Use email address of the user to map the user login sessions with existing user accounts using Google domain: If your Realm values do not match, but you still want to map user login sessions using your existing OpenID Connect domain, click the Yes button. *See note below.
  10. If you are using the domain for login, you must enable it on the Administration > Config > Logins page. See below.
  11. When the domain is set up, you must enable it on the Administration > Config > Logins page. See To enable a login domain. For information on Google login button usage, see Google+ Sign-In button branding guidelines.

*Use email address field: there is one side effect to using this option. Google allows users to create accounts using a non-Google email address, and to change the email address whenever they want. If a user creates an account on the portal using login with Google, and then changes the email address on Google, and the email mapping option is in place, the portal might interpret the new email address as a new user account. However, since we always give the preference to the OpenID identifier to map the user to the profile, using email mapping will work smoothly in most cases.

Back to top

How do I set up the platform to log in with Google?

If you want to allow your users to log in to the platform using Google credentials, follow these steps:

  1. Register your platform as an app on the Google Developers Console and get credentials. See How do I get Google credentials for a Google Connector domain?
  2. Set up a domain on the platform. You have two choices:
  3. Enable the Google platform login. See To enable a login domain.

Once setup is complete, when users sign in they will see the Google icon on the platform login page and can log in using Google credentials.

You can also view a tutorial video on YouTube: Configure the Akana Developer Portal to Use Google Login (external link).

Back to top

What value should I use for the Redirect URI for my Google Connector domain?

The redirect URI that you set in the Google Developers Console determines where Google sends responses to your authentication requests.

Depending on how you will be using the Google Connector domain, there are three possible redirect URI values that you could use when registering your platform as an app in the Google Developers Console. To find the redirect URIs for your login domain, or OAuth 2.0 domain using the Google+ API for authentication, choose the applicable value from the table below.

Note: Google requires that the redirect URL be a public URL. The Google Connector domain can only work if the portal is on a public URL.

Environment Scenario Redirect URL
Akana API Platform Login {CMConsoleAddress}/api/login/ssoLogin
OAuth Provider Resource Owner domain when OAuth/OIDC Provider is deployed in the same container as the platform {OAuthProviderAuthorizationServer}/oauth/auz/grants/provider/authcomplete
OAuth Provider Resource Owner domain when OAuth/OIDC Provider is deployed in the same container as the Network Director (OAuth Provider Agent scenario) {NDHostAddress}/oauth/auz/grants/provider/authcomplete

For information on setting up your platform as an app in the Google Developers Console, refer to How do I set up the platform to log in with Google? above.

If you will be using your Google Connector domain for OAuth, you will also need to customize the user consent page. See How do I customize the Google user consent page for my Google Connector domain?

Back to top

If you want to use a Google Connector domain to support OAuth 2.0 authentication on the platform, you will need to provide values for customization of the user consent page that's presented to users when your app is asking for approval to access the user's data.

If you haven't already done so, register your app on the Google Developers Console. For instructions, see To get credentials for a Google Connector domain. Then follow the instructions below.

  1. Log in to the Google Developers Console and go to the page where you registered your platform as an app.
  2. On the left, click APIs & Auth and then click APIs. Make sure the status for the Google+ API shows as ON.
  3. On the left, click APIs & Auth > Consent Screen.
  4. Provide values you want your users to see, such as product name, homepage URL, and logo, and click Save.

Back to top

OAuth Provider Domain:

Which type of OAuth Provider domain should I set up?

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

  • OAuth/OICD 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 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.

Back to top

How does the OAuth/OIDC Provider configuration process work?

Here's how OAuth/OIDC Provider domain configuration process 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 Administration > Domains > OAuth/OIDC Provider Domain.
  • Once the 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 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 OAuth/OIDC Provider domain?

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

Back to top

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 my API with an OAuth Provider? in the API Admin help.

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

Back to top

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 Administration > 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:

Back to top

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

The Akana API Platform 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: Install the OAuth Provider feature via the Akana Administration Console. This installs the OAuth/OIDC Provider feature. The Business Admin can then create and configure an OAuth/OIDC Provider domain in the developer portal user interface.
  2. Business Admin: Set up the domain in the Akana API Platform (see below).

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

To configure an OAuth/OIDC provider domain:
  1. Log in as the 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 OAuth/OIDC Provider. The Add OAuth/OIDC Provider wizard opens at the Details page. This wizard has seven pages:
    • 1 Details
    • 2 Grant Types
    • 3 Token
    • 4 OpenID Connect
    • 5 Scopes
    • 6 Properties
    • 7 Branding
  4. Enter a name and description for your 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 OAuth/OIDC Provider domain to support. Specify values or choose options. For more information, see What are the settings on the OAuth/OIDC Provider Grant Types page and what options should I choose?
  6. Click Next to go to the Token page, where you can specify information about one or more token types that you want the OAuth/OIDC Provider domain to support. Specify values or choose options. For more information, see What are the settings on the 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 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 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 OAuth/OIDC Provider Branding page and what options should I choose?
  11. Click Save. The 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.

Back to top

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

When you're setting up an 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:

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 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 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 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 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 Automation
  • Google Automation: this is present for backwards compatibility only. Choose Google.

Back to top

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

When you're setting up an 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
    • Bearer
  • 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 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.
  • 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?

Back to top

Should I choose Referenced Bearer or JWT Bearer Access token?

A key advantage of the Bearer token is that the Resource Server can validate the token, without having to go to the Authorization Server. This is more efficient in terms of performance, especially when the Resource Server and OAuth Provider are different vendors.

If you have different vendors for Authorization Server and Resource Server, and want to be able to validate the token at the Resource Server, that is a key reason to choose JWT Bearer Access Token, so there is no need for a proprietary call to the OAuth Provider. In this scenario, you can write a piece of code to decrypt the message, verify the signature, and then validate.

The Referenced Bearer token is much smaller in size. If header size might be an issue, that would be a reason to choose Referenced Bearer, or at least to support it so that API Admins can choose this option if they want to.

If you want to validate the token at the Authorization Server, you can choose to do that with your access tokens by checking the check box, Verify JWT Access Token with Authorization Server. However, by doing so you lose some of the advantage of using an access token and might therefore prefer to go with the smaller Referenced Bearer token.

Back to top

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

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

  • Choose yes if:
    • You want the 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 the Authorization Server (see Should I choose to verify the access token with the Authorization Server?).
    • Your network is completely secure and you have no concerns about the userinfo being compromised. In this scenario, it might be acceptable to include userinfo without encryption. However, if there is any possibility that userinfo might be exposed in an insecure environment, encryption is extremely important.
  • Choose no if:
    • You have concerns about the size of the bearer token. The user information increases the size of the bearer token, which is already larger than a Referenced Bearer token would be. In addition, if you include the userinfo in the token you should encrypt the information, which further increases the message size.
    • It's acceptable in your implementation for the Resource Server to make an additional call to the Authorization Server for the userinfo.

Back to top

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.

Back to top

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 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?

There are advantages to either approach; which decision is best depends on your unique scenario.

Back to top

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

When you're setting up an 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 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, this 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).
ID Token Signing Algorithm Defaults to HmacSHA256, but many other algorithms are supported. For more information on available options, see What signature algorithms are supported by the platform's OpenID Connect OAuth 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.

Back to top

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 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 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: Administration > Domains > Configure OAuth/OIDC Provider > Tab 6, Properties

Back to top

What are the settings on the 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 platform's OAuth/OIDC Provider 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 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 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 OAuth/OIDC Provider domain uses OpenID Connect for authentication (OpenID Connect support is checked in the 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 either the OAuth Provider or OAuth Provider Agent feature installed.

For more information, including the specific paths for different OAuth URLs for the OAuth provider, see What is the OAuth Authorization Server URL for the platform?

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.

Back to top

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

You can set up an 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, SAML Web SSO domain, or LDAP or CA SiteMinder domain.

Back to top

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 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 either OAuth Provider or OAuth Provider Agent features are 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.

Back to top

What is the OAuth Authorization Server URL for the platform?

When you are setting up an 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, if the Authorization Server URL you specified in the provider configuration was 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, OAuth Authorization Endpoint URL becomes https://www.acmepaymentscorp.com:9800/oauth/auz/authorize and OAuth Token Endpoint URL becomes https://www.acmepaymentscorp.com:9800/oauth/oauth20/token.

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

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

Note: 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?

Back to top

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

Back to top

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 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 platform's OAuth/OIDC Provider 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.

Back to top

What token types should I support?

When setting up your 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.

Back to top

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.

Back to top

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 OAuth/OIDC Provider domain to have the gateway verify JWT Access Tokens with the Authorization Server as well (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.

Back to top

SAML Web SSO/SLO Domain:

How do I set up the platform to log in with SAML Web SSO?

The SAML Web SSO domain allows you to set up the platform so that users can log in via a SAML Identity Provider, using SAML Web SSO.

First, you’ll need to install the following optional plug-ins in the Akana Administration Console to one or more containers in your implementation:

  • Akana SAML 2.0 Web Browser SSO Service Provider
  • Akana SAML 2.0 Web Browser SSO Service Provider UI

The next step is to define the SAML Web SSO domain in the Policy Manager Management Console (Configure > Security > Identity Systems). For more information, refer to the following external documentation:

  • The Add Identity System (Active Directory) topic in the Policy Manager Online Help.
  • White paper: Using SAML for Single Sign-On in the Akana Platform.

Once the domain is defined in Policy Manager, you can configure and enable it in the Akana API Platform:

Once setup is complete, when users sign in they will see the icon for your login domain on the platform login page and will be able to choose to log in by authenticating with your Identity Provider.

To set up a SAML Web SSO login domain in the Akana API Platform:
  1. Define the SAML Web SSO domain in the Configure > Security > Identity Systems section of Policy Manager. See notes above.
  2. In the platform, enable the domain for login. This is a configuration step: Administration > Config > Logins (Enable check box). For more information, see How do I enable a domain for login?
  3. Click Save.

Back to top

How do I set up the platform for single logout (SLO) using SAML?

The platform supports single logout (SLO) with an identity provider, using SAML.

You can use the SAML domain to set up the platform so that users can log in via a SAML Identity Provider, using SAML Web SSO, and then also when the user logs out of the platform the user is also logged out of the SAML domain (SLO).

You must first define the SAML Web SSO domain in the Policy Manager Management Console (Configure > Security > Identity Systems).

Refer to the supporting documentation referenced in How do I set up the platform to log in with SAML Web SSO? above.

Back to top

CA SiteMinder Domain:

How do I set up the platform to log in with CA SiteMinder (CA SiteMinder domain)?

The CA SiteMinder domain allows users to log into the platform using CA SiteMinder credentials.

You must first define the CA SiteMinder domain via the Configure > Security > Identity Systems section of the Policy Manager Management Console. For more information, refer to the following external documentation:

  • The Add Identity System (Active Directory) topic in the Policy Manager Online Help.
  • For information about integrating CA SiteMinder with Policy Manager, see http://docs.akana.com/ag/ca_siteminder/ca_siteminder_integrate_with_pm.htm. This includes instructions on how to set up CA SiteMinder and install the identity system (domain) in Policy Manager.
  • The Enterprise API Platform Installation Guide (for information on how to install a CA SiteMinder Identity System).

Once the domain is defined in Policy Manager, you can configure and enable it in the Akana API Platform:

Once setup is complete, when users sign in they will see the CA SiteMinder icon on the platform login page and will be able to choose CA SiteMinder for login.

To set up a CA SiteMinder login domain in the Akana API Platform:
  1. Define the CA SiteMinder domain in the Configure > Security > Identity Systems section of Policy Manager. See notes above.
  2. In the platform, enable the domain for login. This is a configuration step: Administration > Config > Logins (Enable check box). For more information, see How do I enable a domain for login?
  3. Click Save.

Back to top

PingFederate Domain:

What versions of PingFederate does the platform support?

The platform supports the following versions of PingFederate:

  • 7.1.3x
  • 7.3.x to 8.3.x
  • 9.x (8.4.18 and later)

Back to top

How do I configure an External OAuth Provider domain for PingFederate?

To get everything configured correctly, you must perform some setup steps in PingFederate and Policy Manager before going ahead with the Akana API Platform setup. Follow the procedures listed below, in sequence:

  1. PingFederate Configuration
  2. Policy Manager Configuration
  3. Akana API Platform Configuration

1: PingFederate Configuration

You must have a working PingFederate installation.

In your PingFederate server configuration, do the following:

  • In Server Configuration > System Settings > Server Settings, in the Federation Info section, make sure the base URL value is defined and is accessible from the Akana API Platform.

    Note: you will use this value in the Akana API Platform later on, in the PingFederate domain setup, on the Provider Details page.

  • Validate and export the server certificate: In Server Configuration > Security > SSL Server Certificates, make sure there is a valid, activated certificate defined. The PingFederate server certificate must have a "Common Name" matching the hostname in the base URL. If necessary, create a new certificate. When you know the certificate is valid, click the Export link to export the certificate.

In PingFederate, create a client (application) to represent the Akana API Platform. You must set up the client as a resource server in your PingFederate instance so that the Akana API Platform can communicate with PingFederate. Follow the instructions below.

To create the Akana API Platform client in PingFederate
  1. In PingFederate, click OAuth Settings > Client Management, and choose Add Client.
  2. For Client Authentication, choose Client Secret.
  3. Configure the client with the following settings:
    • Client ID: enter a unique ID for your Akana API Platform client. This is the equivalent of a login. For example, PingFederate.
    • Client Secret: click Generate Secret and copy the secret so that you can set up the same value in the Akana API Platform in a later step.
  4. Choose a name.
  5. Under Allowed Grant Types, choose Access Token Validation (Client is a Resource Server).
  6. Save your settings.

In PingFederate, set up the password credential validator. This validates the credentials provided through the OAuth user interface when a token is requested. See below.

To set up password credential validation in PingFederate
  1. In PingFederate, in the settings for your Akana API Platform client, click Authentication > Password Credential Validators.
  2. Choose Create New Instance.
  3. Specify Instance Name, Instance ID, and Type, and save the values.

That completes the initial PingFederate setup. The next step is to set up the PingFederate credentials in Policy Manager so that PingFederate is trusted.

2: Policy Manager Configuration (HTTPS only)

In Policy Manager, depending on the exact scenario, you might need to complete either or both of these steps:

Note: It's important to complete any steps in Policy Manager before setting up the domain in the Akana API Platform.

To set up the PingFederate server certificate in Policy Manager

This step is needed if your PingFederate implementation is expecting HTTPS connections.

  1. Add the issuer of the PingFederate server certificate in the platform trust store. In Policy Manager: Console > Configure > Security > Certificates > Trusted CA Certificates tab. This step is needed so that the Akana API Platform will trust the PingFederate Authorization Server endpoints. Note that when you upload the certificate, it generally takes a couple of minutes to take effect. Allow some time after uploading the certificates before setting up the domain in the Akana API Platform.
  2. For more information about setting up CA certificates in Policy Manager, see Trusted CA Certificates (Policy Manager help).
  3. Required only if you uploaded the CA certificate after configuring the domain: After waiting for five minutes for the trusted CA certificate information to get refreshed, update the PingFederate domain (even though there were no changes). This triggers each of the containers to re-initialize the provider with the new trusted CA certificates. Alternatively, you can restart each of the containers where the API platform is installed.

3: Akana API Platform Configuration

When the PingFederate setup steps and Policy Manager setup steps are done, it's time to set up the PingFederate domain in the Akana API Platform.

To set up an External OAuth Provider domain in the Akana API Platform for PingFederate

Note: Instructions for setting up an External OAuth Provider domain are provided in How do I add an External OAuth Provider domain? Specifically for PingFederate, there are two sections that include additional information, specifically for PingFederate, when you choose PingFederate as the provider and read in the configuration information. The additional information is on Tab 4, Access Token Validation, in the right column, and on Tab 5, Extensions.

  1. Log in as the Business Admin and go to the Admin section.
  2. Click Domains. The Domains Summary page displays.
  3. Click Add Domain. The Select Domain Type drop-down menu displays.
  4. Select External OAuth Provider and then click Select. The Add Connector Domain wizard opens.
  5. Details page: Specify values for Name and Description and then click Next.
  6. Configure page: For Provider Type, choose PingFederate. Choose to provide the well-known configuration URL, paste the configuration JSON, or set up manually. If you read or paste the information, all the PingFederate values are read in automatically. Click Next.
  7. Provider page: Review the values that were read in from the configuration, and adjust as needed. Click Next.
  8. Access Token Validation page: Review the values that were read in from the configuration, and adjust as needed. For information on the specific values relating to PingFederate, see What are the settings on the External OAuth Provider Access Token Validation page for PingFederate? Click Next.
  9. Extensions page: the PingFederate extension information is displayed. For more information, see What are the settings on the External OAuth Provider Extensions page for PingFederate, and what options should I choose? Review the values and adjust as needed.
  10. Click Save.

The above steps complete the setup of the PingFederate domain. Once these steps are complete, authorized platform users can create APIs that use the PingFederate domain, and business admins or app developers can create apps that subscribe to those APIs.

Note: With the older PingFederate connector domain, for each app using an API that uses PingFederate as an OAuth provider, the PingFederate Admin had to set up the app as a PingFederate client so that the app can be authenticated. With the External OAuth Provider domain, this activity is automated.

Back to top

How do I configure a PingFederate Connector domain?

Note: We recommend that PingFederate users choose the External OAuth Provider domain rather than the legacy PingFederate domain. See External OAuth Provider Domain. PingFederate configuration is still required, as covered in PingFederate Usage Scenario: End to End.

The PingFederate® Connector domain allows you to use PingFederate as an OAuth provider. Essentially, the Business Admin registers the platform with PingFederate as the resource server, and then uses the values provided by PingFederate to set up the PingFederate Provider domain in the Akana API Platform.

For a walkthrough of the end-to-end sequence of steps, including API and app setup, refer to PingFederate Usage Scenario: End to End.

To get everything configured correctly, you must perform some setup steps in PingFederate and Policy Manager before going ahead with the Akana API Platform setup. Follow the procedures listed below, in sequence:

  1. PingFederate Configuration
  2. Policy Manager Configuration
  3. Akana API Platform Configuration

1: PingFederate Configuration

You must have a working PingFederate installation, including installation of the Akana PingFederate Integration Add-on Feature (Plug-In). The Administrator must install the PingFederate plug-in on the following containers:

  • Network Director: All Network Director containers
  • Community Manager: All containers that have the OAuth Provider and CM APIs features installed.
  • Policy Manager for DataPower: In a PMDP scenario, for a standalone configuration, the feature must be installed on the container. If there is a master/slave configuration, the features must be installed on both the master and the slave.

Note: This document addresses integration with PingFederate version 7.1.3.x. For information about later supported versions, see What versions of PingFederate does the platform support?

In your PingFederate server configuration, do the following:

  • In Server Configuration > System Settings > Server Settings, in the Federation Info section, make sure the base URL value is defined and is accessible from the Akana API Platform.

    Note: you will use this value in the Akana API Platform later on, in the PingFederate domain setup, on the Provider Details page.

  • Validate and export the server certificate: In Server Configuration > Security > SSL Server Certificates, make sure there is a valid, activated certificate defined. The PingFederate server certificate must have a "Common Name" matching the hostname in the base URL. If necessary, create a new certificate. When you know the certificate is valid, click the Export link to export the certificate.

In PingFederate, create a client (application) to represent the Akana API Platform. You must set up the client as a resource server in your PingFederate instance so that the Akana API Platform can communicate with PingFederate. Follow the instructions below.

To create the Akana API Platform client in PingFederate
  1. In PingFederate, click OAuth Settings > Client Management, and choose Add Client.
  2. For Client Authentication, choose Client Secret.
  3. Configure the client with the following settings:
    • Client ID: enter a unique ID for your Akana API Platform client. This is the equivalent of a login. For example, PingFederate.
    • Client Secret: click Generate Secret and copy the secret so that you can set up the same value in the Akana API Platform in a later step.
  4. Choose a name.
  5. Under Allowed Grant Types, choose Access Token Validation (Client is a Resource Server).
  6. Save your settings.

In PingFederate, set up the password credential validator. This validates the credentials provided through the OAuth user interface when a token is requested. See below.

To set up password credential validation in PingFederate
  1. In PingFederate, in the settings for your Akana API Platform client, click Authentication > Password Credential Validators.
  2. Choose Create New Instance.
  3. Specify Instance Name, Instance ID, and Type, and save the values.

That completes the initial PingFederate setup. The next step is to make sure Policy Manager configuration steps are in place.

2: Policy Manager Configuration (HTTPS only)

In Policy Manager, depending on the exact scenario, you might need to complete either or both of these steps:

Note: It's important to complete any steps in Policy Manager before setting up the domain in the Akana API Platform.

To set up the PingFederate server certificate in Policy Manager

This step is needed if your PingFederate implementation is expecting HTTPS connections.

  1. Add the issuer of the PingFederate server certificate in the platform trust store. In Policy Manager: Console > Configure > Security > Certificates > Trusted CA Certificates tab. This step is needed so that the Akana API Platform will trust the PingFederate Authorization Server endpoints. Note that when you upload the certificate, it generally takes a couple of minutes to take effect. Allow some time after uploading the certificates before setting up the domain in the Akana API Platform.
  2. Required only if you uploaded the CA certificate after configuring the domain: After waiting for five minutes for the trusted CA certificate information to get refreshed, update the PingFederate domain (even though there were no changes). This triggers each of the containers to re-initialize the provider with the new trusted CA certificates. Alternatively, you can restart each of the containers where the API platform is installed.

3: Akana API Platform Configuration

When the PingFederate setup steps and Policy Manager setup steps are done, it's time to set up the PingFederate domain in the Akana API Platform.

To set up a PingFederate Provider domain in the Akana API Platform:
  1. Log in as the Business Admin and go to the Admin section.
  2. Click Domains. The Domains Summary page displays.
  3. Click Add Domain. The Select Domain Type drop-down menu displays.
  4. Select PingFederate Provider and then click Select. The Add Connector Domain wizard opens.
  5. Details page: Specify values for Name and Description and then click Next.
  6. Provider Details page: Enter the base URL from the PingFederate server setup's Federation Info system settings; for example, https://{hostname}:{port}/{basepath}. The base URL is used to construct the OpenID Connect Well-Known Configuration URL to read the PingFederate OAuth 2.0 provider configuration. If PingFederate is expecting HTTPS connections, make sure you've added the issuer of the PingFederate server certificate in the platform trust store. Click Next.
  7. Provider Details page: Enter the following values:
    • Client ID: The unique identifier that you specified when you created the OAuth client for this platform within PingFederate.
    • Client Secret: The Client Secret value from the OAuth client setup in PingFederate.
    • Subject Attribute Name: the attribute from the OAuth access token that should be used as the subject; for example, username. At runtime, the attribute's value is used as the Subject field for API resources with policies that validate access tokens.
  8. Click Save.

The above steps complete the setup of the PingFederate domain. Once these steps are complete, authorized platform users can create APIs that use the PingFederate domain, and business admins or app developers can create apps that subscribe to those APIs.

Note: For each app that is using an API that uses PingFederate as an OAuth provider, the PingFederate Admin must set up the app as a PingFederate client so that the app can be authenticated. For an overview of the entire process, end to end, see PingFederate Usage Scenario: End to End.

Back to top