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:

Table of Contents

Facebook Domain:

Google Connector Domain (deprecated in version: 2020.1.0):

Akana OAuth/OIDC Provider Domain:

Refer to detailed information in separate file: Akana OAuth/OIDC Provider Domain.

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:

CA SiteMinder Domain:

PingFederate Domain:

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 Community Manager 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 (deprecated in version: 2020.1.0) Yes Yes

2019.1.4 and later: Akana OAuth/OIDC Provider

Prior to 2019.1.4: OAuth/OIDC Provider (same link)

 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

How do I add a domain?

To add a domain

  1. Log in as a 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?

Note: In some implementations of the platform, there could be a custom Business Admin role that can view domains but cannot add, modify, or delete. For more information, see Why can't I add a domain?

How do I modify a domain?

To modify a domain

  1. Log in as a Business Admin and go to the Admin section.
  2. Click Domains. The Domains Summary page displays.
  3. Find the domain on the list and click Modify. The Edit wizard for the specific domain type displays.
  4. 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.

Note: In some implementations of the platform, there could be a custom Business Admin role that can view domains but cannot add, modify, or delete. For more information, see Why can't I add a domain?

How do I delete a domain?

To delete a domain

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

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

Note: In some implementations of the platform, there could be a custom Business Admin role that can view domains but cannot add, modify, or delete. For more information, see Why can't I add a domain?

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: More > Admin >Domains. Domains applicable to login are:
  2. Enable the domain for login. This is a configuration step: More > Admin >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.

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: More > Admin >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: More > Admin >Logins (Enable check box). See How do I enable and customize a platform login domain? (Site Admin help).

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

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, see Identity Systems Overview (Policy Manager 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.

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 Akana OAuth/OIDC Provider domain option (More > Admin > Domains > Add Domain > choose Akana OAuth/OIDC Provider). For full instructions, see How do I set up and configure an Akana OAuth/OIDC Provider domain?

There are some differences between an Akana OAuth/OIDC Provider and an OpenID Connect Provider; for example, OpenID Connect has the userinfo endpoint. The platform's Akana 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.

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.

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.

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 Community Manager 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 Akana 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?
Akana 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.
Akana 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.

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 more information, see Identity Systems Overview (Policy Manager 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 Community Manager 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.

What is a 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 Akana 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.

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.

Why can't I add a domain?

In some implementations of the platform, there could be a custom Business Admin role that has limited permissions. In this scenario, you might be able to access the Domains page but not be able to add, edit, or delete domains.

In this scenario, you'll see a View button and will be able to view information for each domain.

If you have questions or concerns about your platform role, ask a Site Admin.

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 a 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 More > Admin >Logins page. See To enable a login domain. For information on Facebook login button usage, see https://www.facebookbrand.com.

Google Connector Domain (deprecated in version: 2020.1.0):

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

Note: The Google Connector domain is deprecated in version: 2020.1.0. Use the OpenID Connect Relying Party domain instead. See OpenID Connect Support.

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 create an account and get credentials for your domain. 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 Community Manager 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 Redirection 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.

How do I set up a Google Connector domain?

Note: The Google Connector domain is deprecated in version: 2020.1.0. Use the OpenID Connect Relying Party domain instead. See OpenID Connect Support.

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 Community Manager 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 a 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 More > Admin >Logins page. See below.
  11. When the domain is set up, you must enable it on the More > Admin >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.

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

Note: The Google Connector domain is deprecated in version: 2020.1.0. Use the OpenID Connect Relying Party domain instead. See OpenID Connect Support.

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 Community Manager developer portal to Use Google Login (external link).

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

Note: The Google Connector domain is deprecated in version: 2020.1.0. Use the OpenID Connect Relying Party domain instead. See OpenID Connect Support.

The Client Redirection 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 Akana OAuth/OIDC Provider is deployed in the same container as the platform {OAuthProviderAuthorizationServer}/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?

Note: The Google Connector domain is deprecated in version: 2020.1.0. Use the OpenID Connect Relying Party domain instead. See OpenID Connect Support.

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.

To customize the Google user consent page

  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.

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:

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: More > Admin >Logins (Enable check box). For more information, see How do I enable a domain for login?
  3. Click Save.

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.

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:

  • Information on adding an identity system. See Identity Systems Overview (Policy Manager help).
  • For information about integrating CA SiteMinder with Policy Manager, see Integrate CA SiteMinder with Policy Manager. 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: More > Admin >Logins (Enable check box). For more information, see How do I enable a domain for login?
  3. Click Save.

PingFederate Domain:

What versions of PingFederate does the platform support?

For details about the PingFederate versions supported, go to the System Requirements doc, Third-party identity and access management (IAM) technologies section.

The information below is for versions earlier than 2020.1.0.

The platform supports the following versions of PingFederate:

  • 7.1.3x
  • 7.3.x to 8.3.x
  • 9.3.x
  • 10.0.x (2019.1.19 and later)

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

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.

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