Using the OAuth Client Policy

Learn how to use the OAuth Client policy to allow the API Gateway to act as the client, generating the OAuth 2.0 token and sending it to the downstream API.

For information about using policies in the context of the Community Manager developer portal, see Business Policies.

Table of Contents

Introduction

The OAuth Client Policy is an operational policy that allows the API Gateway to send an OAuth 2.0 token downstream.

In general terms, the API Gateway is in the middle, between the consumer and the downstream service. The consumer calls the Gateway, and then the Gateway typically calls the downstream service.

With the OAuth Client policy, the API Gateway acts as the client, generating the token and sending it to the downstream API.

This policy acts as the consumer of the downstream API. It gets a new OAuth token, and passes the token to the downstream service based on the policy configuration.

Note: This policy is available only for two-legged OAuth grant types: Resource Owner (Resource Owner Password Credentials grant type) or Client Credentials.

Creating an OAuth Client Policy

The first step in creating a policy is to define the basic policy information.

To add an operational policy

  1. Go to Workbench > Browse > Organization, and select Policies > Operational Policies. The Policies Summary is displayed.
  2. Click Add Policy.
  3. Choose the policy type and click Next.
  4. Specify a name (required) and description (optional) and click Finish. At the Completion Summary, click Close. The Add Policy Wizard creates a draft policy instance that you can then configure on the Policy Details page.

For more information, see Add Policy.

Configuring the OAuth Client Policy

Once you've created the policy, you can configure the policy details that determine how the policy works. Then you can activate the policy so that it can be used.

To configure an OAuth Client policy in Policy Manager

  1. In the Organization Tree, find the level where the policy was defined. Click to select.
  2. In the center pane, in the OAuth Client Policy section, click Modify. The Specify OAuth Client Policy Options page is displayed, as shown below.

  3. Specify values. For details on field values, see OAuth Client Policy Configuration Options below.
  4. Click Next to go to the Specify OAuth Client Policy Audit Options page. See Configuring OAuth Client Policy Audit Options.
  5. When done, click Finish to save the policy.

Now that the policy is defined, you can activate it and start using it. On the right, under Actions, choose Activate Policy.

OAuth Client Policy Configuration Options

The OAuth Client policy includes the configuration options listed below.

Scope
Update the appropriate scope as provided by the OAuth provider.
Grant Type
Indicate the OAuth 2.0 grant type that the policy will use. Two-legged OAuth grant types are supported: Resource Owner (Resource Owner Password Credentials grant type) or Client Credentials.
OAuth Provider Connection Details
Check the box to provide the OAuth Provider connection details.
HTTP Verb
The HTTP verb for the call to the OAuth Provider. Might be GET or POST, depending on your provider.
Provider Location
Provide the full token endpoint for the OAuth Provider. This is the valid URL for the OAuth Provider's OAuth 2.0 token service. Examples:
  • If you're using the platform's own OAuth provider, the location URL is: https://{akana_oauth_provider_host}:{port}/oauth/oauth20/token.
  • For PingFederate the provider token endpoint is: https://{ping_oauth_provider_host}:{port}/as/token.oauth2.
  • For Google it is: https://www.googleapis.com/oauth2/v4/token.
Provider Content Type
The content-type value specified as required in the call to the OAuth Provider.
HTTP/1.1 Chunked Encoding
Indicate an encoding transformation applied to an entity-body during the transfer through the network. The content is wrapped and transferred as a series of chunks. The call to the OAuth external provider is made based on the policy's selected transfer encoding configured using the HTTP/1.1 Chunked Encoding option. The default value is True.
Service QName
Accept the default value.
Operation QName
Accept the default value.

Configuring OAuth Client Policy Audit Options

Once you've configured the settings for your OAuth Client policy, the next step is the Specify OAuth Client Policy Audit Options page, as shown below.

Specify OAuth Client Policy Audit Actions

Choose from the available options controlling the audit data that's captured:

Generate Audit Data
Captures all message data, whether success or failure, for all message exchanges.
On Error Only
If you choose to generate audit data, you can specify that audit data is captured only when an error occurs on a message exchange.

That completes the policy configuration. Click Finish to close the wizard. You can now assign the policy to a service.

Activating a policy

When you create and configure a policy, the policy is in Draft state. When the policy configuration is complete, activate the policy: click Activate Policy and then confirm. See Activate a Policy.

A policy in Draft state is not available for general use. Once you activate the policy, it is in Active state and is available for use.

Attaching a policy

To use the OAuth Client policy, go to the Policies folder in the respective organization and attach the policy to a web service, binding, or binding operation.

OAuth Client Policy: use case

This section provides a usage scenario for using the OAuth Client policy to generate an OAuth token and send it to the downstream service.

It includes the following high-level steps:

  1. Configure New OAuth Client Policy
  2. Create user to be used for Client ID and Shared Secret
  3. Create user to be used for Resource Owner
  4. Configure Service to use OAuth Client Policy
  5. Configure outbound identity
  6. Cache Configuration
  7. Test
  8. Validate

Configure New OAuth Client Policy

First, create and configure a new OAuth Client Policy. Follow the steps below.

To create and configure the OAuth Client policy

  1. Log in to the Policy Manager workbench.
  2. Choose the organization that the policy will belong to, and go to the Policies > Operational Policies folder.
  3. Click Add Policy.
  4. On the Select Policy Creation Option page, from the Type drop-down, choose OAuth Client Policy and click Next.
  5. Specify a value for Policy Name and click Finish.
  6. At the completion summary, click Close. The OAuth Client Policy Details page is displayed.
  7. The next step is to configure the policy details. In the center section, click Modify.
  8. On the Specify OAuth Client Policy Options page, specify values for the following properties:
    • Scope: specify the scope provided by the OAuth Provider.
    • Choose the OAuth 2.0 grant type that the policy will support: Resource Owner (Resource Owner Password Credentials grant type) or Client Credentials.
    • Check the OAuth Provider Connection Details box.
    • Choose the HTTP verb that the OAuth Provider's token endpoint uses: GET or POST.
    • Specify the Location of the OAuth provider. For examples, see OAuth Client Policy Configuration Options.
    • Set the required Content-Type that will be set to the OAuth Provider.

      OAuth Client Policy Options

    • Click Finish.
  9. Click Close.
  10. Under the Workflow actions, click the Activate Policy link.
  11. Click OK to activate the policy.

Create user to be used for Client ID and Shared Secret

The client id and shared secret is used when invoking the OAuth provider. The gateway will send these to identify itself with the OAuth provider. The first step would be obtaining this information by registering this service in the OAuth provider. See the documentation provided by the OAuth provider for these steps.

If you are using the Akana OAuth Provider, follow these steps:

  1. Log in to the Community Manager developer portal.
  2. Create a new app: From the Plus icon (+), select Add App. To create an app in the context of a child organization, choose the organization first.
  3. Define the app, and then click Finish.
  4. On the App Details page, under Security, note the App ID.
  5. Click Show Keys to view the Shared Secret. An example is shown below.

    Viewing the Shared Secret

  6. Copy the Shared Secret.

Store the Client ID and Shared Secret values as an outbound identity for the invoked service. For instructions, see To configure the client outbound identity.

To create the Client user

Note: If you're using the platform's OAuth Provider, you can skip this step. The platform uses the credentials for the app you created. If you're using an external OAuth Provider, follow the steps below.

  1. Log in to the Policy Manager workbench.
  2. Click the Security tab.
  3. From the Users sub-tab, on the bottom of the screen, click Add User.
  4. Populate the information: username, full name, and password. The Client Id from the OAuth Provider will be the user ID and the Shared Secret will be the password.

    Adding a User

  5. Click Finish.

Create user to be used for Resource Owner

When using the Resource Owner flow, a user name and password is required to be passed to the OAuth Provider. Even though the username and password exist in the LDAP domain, you must set the user up as a local user and then add it to the service as an outbound identity. The policy uses these credentials to put in the request when calling the OAuth Provider.

To create the Resource Owner user

  1. Log in to the Policy Manager workbench.
  2. Click the Security tab.
  3. From the Users sub-tab, on the bottom of the screen, click Add User.
  4. Populate the information: username, full name, and password.

    Creating the Resource Owner user

  5. Click Finish.

Configure Service to use OAuth Client Policy

Assumption is that an API has been properly created in the platform.

The OAuth Client Policy is done on the Outbound side, so this policy needs to be added to the Physical Service (target) object that was created. The users that were created above will also need to be added to this service as Outbound Identities. Follow these steps to properly configure a service to use the OAuth Client Policy.

To configure the service to use the OAuth Client policy

  1. Log in to the Policy Manager workbench to configure the Physical Service.
  2. Navigate to the proper organization structure where this service was created.
  3. Select the physical service (the service with the name of target on it).
  4. Scroll down to the Policy Attachments section. In the Operational sub-section, click Manage.
  5. From the pop-up screen, navigate to the Policy -> Operational directory under the organization that the OAuth Client Policy was created and select it.

    Manage Operational Policy Attachments page

  6. Click Apply.

Configure outbound identity

At this point, the Outbound Identities need to be configured. This can be done from either the Policy Manager Workbench or the Community Manager developer portal. These directions describe the steps using the Community Manager developer portal.

If the Resource Owner flow is being used, two outbound identities are required, one for the end user and the other for the client identity.

Note: While you're modifying the implementation, it's a good idea to enable debug mode, on the Implementation Details page, so that you get transaction logging. For instructions, see How do I turn on debug mode for my implementation?

To configure the end-user identity

  1. Log in to the Community Manager developer portal.
  2. Navigate to the API that will be used for this configuration.
  3. On the left navigation, click Implementations.
  4. Choose the endpoint that will be configured.
  5. Scroll down to the Identities section and click Edit.
  6. Select Specify Outbound Identities and click Add.
  7. On the Source Identity, select Static User.
  8. Make sure the domain is set to Local Domain, and then populate the resource owner username and password that you created in To create the Resource Owner user above.
  9. Under Outbound Identity, select End User.

    Configuring the end-user identity

  10. Click Finish.

To configure the client outbound identity

  1. Using the client identity created above, on the same API where the end-user outbound identity was configured, click Implementations.
  2. Choose the endpoint that will be configured.
  3. Scroll down to the Identities section and click Edit.
  4. Select Specify Outbound Identities and click Add.
  5. On the Source Identity, select Static User.
  6. Make sure the domain is set to Local Domain, and then populate the username and password for the client identity that you created in To create the Client user above. If you're using the platform as an OAuth provider, the values are the AppID and Secret.
  7. In the User Defined Category field, enter: GrantTypeCredentials, as shown below.

    Add Outbound Identity

  8. Click Finish.

Cache Configuration

Tokens can be stored in a local cache to the Network Director. Tokens are cached based on a concatenation of the client id and scope. If you're using the Resource Owner grant type, the user ID is appended to the cache key. Cache values can be controlled with a configuration category in the Akana Administration Console. To configure the cache, follow the steps below.

To set cache configuration values

  1. Log in to Akana Administration Console for the Network Director container.
  2. Select the Configuration tab.
  3. Under Configuration Categories, select com.akana.policy.oauth.client.
  4. Set values for the following (see Cache configuration properties below):
    • Cache Expiration Time
    • Cache Idle Time

Cache configuration properties

Cache configuration property settings are shown below.

Cache Expiration Time
The local cache expiration time. When this cache expires, the Client OAuth Policy requests a new token.
The configured time should be less than the OAuth Provider token expiration time, to make sure that expired tokens are not sent downstream.
Cache Idle Time
The expiration time if the cache is idle. When a token is idle in the cache for the configured time, the Client OAuth Policy requests a new token.
The configured time should be less than the OAuth Provider token expiration time, to make sure that expired tokens are not sent downstream.

Test

Invoke the API to test. The backend service should be properly invoked with an OAuth Token.

Validate

Follow these steps to validate that a proper OAuth Token has been added to the downstream API.

  1. Log in to the Policy Manager Workbench.
  2. Navigate the that API that was invoked during the testing. This will be the same API that the OAuth Client Policy was added too.
  3. In the top right tab, select the Monitoring tab, followed by the Logs tab.
  4. Select the latest transaction.
  5. Select the Recorded Messages tab.
  6. Select the Downstream Message and select the Raw Format checkbox.
  7. On this screen, the Authorization token should be shown. See example below.

    Viewing the downstream message