Configure custom API Manager routing policies

This topic explains the advanced use of case of how to configure custom API Manager routing policies. It shows examples of using API key and OAuth as the outbound authentication types.

Note   This topic assumes that you are already familiar with basic API Manager tasks such as importing an existing back-end API and virtualizing a front-end API and with authentication mechanisms such as API key and OAuth.

Configure a custom routing policy with API key authentication

This section explains how to setup a custom API Manager routing policy that uses API key as the outbound authentication type. It shows how to create the policy in Policy Studio, and how to configure it for use in API Manager.

Create the custom routing policy in Policy Studio

You must first create a new policy in Policy Studio that will be used as the custom routing policy in API Manager.

Perform the following steps:

  1. Right-click the Policies node in the tree, and select Add Policy.
  2. Enter a meaningful Name for the new policy (for example, Custom routing policy for PetStore API).
  3. Click the new policy in the tree to start configuring its filters. You can do this by dragging the required filters from the filter palette on the right, and dropping them on to the policy canvas. This example includes Trace and Connect to URL filters:

Create custom routing policy for API key

  1. Open the Connect to URL filter, and in the URL field, enter ${destinationURL}.
  2. On the Authentication tab, you will need to set the client credential profile to the ${params.authn} selector. To do this, click Finish, press Shift, and double-click the filter on the policy canvas to reopen it in advanced mode:

Edit Connect to URL filter in advanced mode

  1. In the ^profile field, enter ${params.authn}, click Save Changes, and Close.

The Authentication tab should now display this setting as follows:

Connect to URL with Authentication set to selector

For more details on how to configure policies, see the API Gateway Policy Developer Guide.

Configure the list of API Manager routing policies in Policy Studio

You must add the new custom routing policy to the list of available routing policies that APIs registered in API Manager can use.

Perform the following steps:

  1. Select Server Settings in the tree, and select API Manager > Routing Policies.
  2. Click Add on the right, and select the custom routing policy that you created (for example, Custom routing policy for PetStore API).
  3. Click OK, and click Save at the bottom right.

Configure an API Manager routing policy

Configure the custom routing policy using API key in API Manager

When the custom routing policy has been added to the list of available routing policies in Policy Studio, perform the following steps in API Manager:

  1. Click API > Backend > New API to import a back-end API, and ensure the Base path URL is set to the API on the remote server. For more details, see Register REST APIs in API Manager.
  2. Click API > Frontend > New API to create a front-end virtualized API from the back-end API. For more details, see Virtualize REST APIs in API Manager.
  3. On the Inbound tab, set Inbound security to Pass Through.
  4. On the Outbound tab , set Outbound authentication profile to API Key, click Edit and configure the following settings:
    • API key field name: Use the default value of KeyId.
    • API key: Enter the API key for your API.
    • Pass credentials as HTTP: Select Header from the list.

Configure API key authentication in API Manager

  1. Click Advanced on the right, and set Default method routing to use your custom routing policy. For example:
  1. Configure custom routing policy in API Manager

Invoke the registered API and view the API key in the request

You can now invoke the API registered in API Manager and view that the API key header is specified in the outbound request and that a successful response is returned. The following example in the API Gateway Manager web console shows the KeyId in the request at the bottom left:

Invoke API and view API key in header

For more details on the API Gateway Manager web console, see the API Gateway Administrator Guide.

Configure a custom routing policy with OAuth authentication

This section describes how to use API Manager to invoke an API with outbound OAuth authentication using a custom routing policy. In this scenario, one API Gateway instance acts as an OAuth client and the other API Gateway instance acts as an OAuth server. This section shows how to configure both API Gateway instances appropriately using the Client Credentials OAuth flow.

Note   This section assumes that you are already familiar with the Client Credentials OAuth flow. For more details on configuring OAuth flows, see the API Gateway OAuth User Guide.

Configure the remote API Gateway as OAuth server in API Manager

To configure a remote API Gateway instance to act as an OAuth server, perform the following steps in API Manager:

  1. Click Clients > Applications > New application. For more details, see Consume APIs in API Manager.
  2. On the Authentication tab, under OAuth Credentials, click New client ID > Create, and use the default settings:
  3. Create new OAuth credentials for API Manager application
  4. Click API > Backend > New API to import a back-end API. For more details, see Register REST APIs in API Manager.
  5. Click API > Frontend > New API to create a front-end virtualized API from the back-end API. For more details, see Virtualize REST APIs in API Manager.
  6. Set the Inbound security to OAuth. This example uses the default setting to obtain the access token from the header:
  7. API Manager OAuth authorization settings
Tip   You must select an OAuth access token store on the General tab. For details on how to add OAuth access token stores, see Configure API Manager settings in Policy Studio.
  1. Click Clients > Applications > API Access > Add API to add the virtualized front-end API to the list of APIs that the application can access.
  2. Click Settings > API Manager Settings >General settings, and ensure that Enable OAuth scopes per application is set.
  3. Click Clients > Applications > Authentication > OAuth Scopes > Add scopes, and select the resource.READ and resource.WRITE scopes:
Tip   You may need to refresh your browser if OAuth Scopes are not displayed.

Configure the client credentials in Policy Studio

When using the Client Credentials OAuth flow for the client, you must first configure the client credentials correctly in Policy Studio. This ensures that the client can request an OAuth access token using only its client credentials and that the authorization is specified in the header as expected.

Perform the following steps:

  1. In the Policy Studio tree, select Policies > OAuth 2.0 > Access Token Service > Client Credentials.
  2. Right-click the Access Token using client credentials filter, and select Edit.
  3. On the Application Validation tab, select the In Authorization Header option:

Configure OAuth Client Credentials in Policy Studio

For more details on OAuth flows, see the API Gateway OAuth User Guide.

Configure the local API Gateway as OAuth client in Policy Studio

To configure a local API Gateway instance to act as an OAuth client, perform the following steps:

  1. To create an OAuth2 credentials application using the Client Credentials flow, select Environment Configuration > External Connections > Client Credentials > OAuth2, right-click and select Add OAuth2 Client Credential. For more details, see the API Gateway OAuth User Guide.
  2. Click Add OAuth2 Application Settings on the right, and ensure the following settings are configured:
  3. Configure OAuth2 Application Settings in Policy Studio
  4. On the Advanced tab, you must also ensure that In Authorization Header is selected for the location of the client ID and client secret:
  5. Configure Advanced OAuth2 Application Settings in Policy Studio
  6. Click Save on the right to save the application.
  7. On the OAuth2 Provider Settings tab, enter the IP address of the remote instance in the Authorization Endpoint and Token Endpoint:

Create the custom routing policy using OAuth in Policy Studio

To create a new policy to use as the OAuth custom routing policy in API Manager, perform the following steps in Policy Studio:

  1. Right-click the Policies node in the tree, and select Add Policy.
  2. Enter a meaningful Name for the new policy (for example, Custom routing policy with OAuth).
  3. Click the new policy in the tree to start configuring the filters for this policy. You can do this by dragging the required filters from the filter palette on the right, and dropping them on to the policy canvas. This example includes Get OAuth Access Token and Connect to URL filters:
  4. Create custom routing policy using OAuth in Policy Studio
  5. In the Get OAuth Access Token filter, the client credentials profile is obtained from the message whiteboard by default, so the token should now be available.
  6. In the Connect to URL filter, you must specify that the destination URL and the client credentials application is obtained from the message whiteboard using the ${params.authn} selector. To do this, press Shift, and double-click the filter on the policy canvas to reopen it in advanced mode:
  7. Edit Connect to URL filter in advanced mode
  8. In the ^profile field, enter ${params.authn}. and click Save Changes and Close.

For more details on how to configure policies, see the API Gateway Policy Developer Guide.

Configure the list of API Manager routing policies and OAuth outbound credentials in Policy Studio

You must add the new custom routing policy and OAuth credentials to the lists of available routing policies and credentials that APIs registered in API Manager can use.

Perform the following steps:

  1. Select Server Settings in the tree, and select API Manager > Routing Policies.
  2. Click Add on the right, and select the custom routing policy that you created (for example, Custom routing policy with OAuth).
  3. Select API Manager > OAuth Outbound Credentials.
  4. Click Add on the right, and select the OAuth client credentials that you created (for example, Test OAuth).
  5. Click OK, and click Save at the bottom right.

Configure API Manager OAuth Outbound Credentials in Policy Studio

Configure the custom routing policy using OAuth in API Manager

When the custom routing policy and OAuth outbound credentials have been added in Policy Studio, perform the following steps in API Manager:

  1. Click API > Backend > New API to import a back-end API, and ensure the Base path URL is set to the API on the remote server. For more details, see Register REST APIs in API Manager.
  2. Click API > Frontend > New API to create a front-end virtualized API from the back-end API. For more details, see Virtualize REST APIs in API Manager.
  3. On the Inbound tab, set the Inbound security to Pass Through.
  4. On the Outbound tab, set the Outbound authentication profile to OAuth, and configure the following:
    • Provider profile: Enter the OAuth outbound credentials profile that you created in Policy Studio (for example, Test OAuth).
    • Token Key (Owner ID): Use the default ${authentication.subject.id} selector setting to obtain this value.
  1. Click Advanced at the top right, and set the Default method routing to use your custom routing policy. For example:

Configure the OAuth custom routing policy in API Manager

Invoke the registered API with OAuth authorization header in request

You can now invoke the API registered in API Manager and view that the authorization header is specified in the outbound request and that a successful response is returned. The following example in the API Gateway Manager web console shows the OAuth custom routing policy in the execution path:

OAuth custom routing policy displayed in API Gateway Manager

The following example shows the Authorization Bearer header correctly displayed in the request in the bottom panel in API Gateway Manager:

 Authorization Bearer header displayed in API Gateway Manager

For more details on the API Gateway Manager web console, see the API Gateway Administrator Guide.

Related Links