Using the OAuth Security Policy

Learn how to configure the OAuth Security Policy to enable API authorization using OAuth 2.0 in Community Manager.

Table of Contents

Introduction

The OAuth Security Policy is a Community Manager policy that enables API authorization using OAuth 2.0. It uses the OAuth configuration assigned to an API when enforcing OAuth tokens in a received request.

  • As part of the Community Manager installation, a default OAuth Security Policy is added to the Policy Manager Management Console.
  • In the Community Manager developer portal, the API Admin first sets up OAuth Details: from the API Details page, from the drop-down list to the right, choose OAuth Details. Specify details such as OAuth Provider, OAuth version, and resource mapping, and save.
  • After the OAuth Details are configured, add the OAuth Security policy to the API implementation: From the API Overview page, click Implementations and choose the implementation. In the Policies section, click Edit. Find the OAuthSecurity policy, click Attach, and click Save.

OAuth Security Policy Configuration Options

The OAuth Security Policy includes three configuration options:

Option Name Details
OAuthSecurity policy: TokenTransformation option

There is an additional configuration option to the OAuth Security policy, TokenTransformation, which you can use to ensure that the OAuth bearer token is relayed to the downstream service, rather than being stripped off from the request message after validation by the API Gateway. You can use this for scenarios where the target endpoint needs access to the original OAuth token that the API Gateway validated. The transform attribute of this policy determines whether to strip the headers or pass them through to the next hop. The possible values of this attribute are strip and pass-through.

An example of the policy configuration with the nested configuration tag is shown below.

<wsp:Policy Name="OAuthSecurity" Description="OAuthSecurity policy uses OAuth
configuration assigned to an API when enforcing OAuth tokens in the received request."
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
  <goap:OAuthSecurity xmlns:goap="http://federatedgovernance.org/policy/oauth">
    <wsp:Policy>
      <goap:TokenTransformation transform="strip"/>
    </wsp:Policy>
  </goap:OAuthSecurity>
</wsp:Policy>

If you change this value to pass-through, the OAuth bearer token is relayed to the downstream service, rather than being stripped off from the request message after validation.
OAuthSecurity policy: IncludeTokenAttributes option

In the IncludeTokenAttributes node of the OAuth Security Policy, you can disable the adding of custom headers. You can then use a custom policy to add the headers however you want to transfer this information to the target endpoint.

If the policy definition does not include the <IncludeTokenAttributes> node, or includes the default value as shown below, the API Gateway platform sends the OAuth grant details to the target endpoint in the custom http request headers.

Default value:

<goap:IncludeTokenAttributes Attributes="all"/>

If the policy definition includes the <IncludeTokenAttributes> assertion with a value of none, as shown below, the API Gateway platform does not include OAuth grant details to the target endpoint.

To disable the adding of custom headers, change the value as shown below:

<goap:IncludeTokenAttributes Attributes="none"/>
OAuthSecurity policy: ScopeRequirement option

Use this to configure how multiple scopes are evaluated:

  • AND (default configuration): if multiple scopes are defined, all must be present in the access token.
  • OR: if multiple scopes are defined and only one is present in the access token, with ScopeRequirement set to OR, the policy condition is met.

An example (the default) is shown below.

<wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy" Description="OAuthSecurity policy uses OAuth configuration assigned to an API when enforcing OAuth tokens in the received request." Name="OAuthSecurity">
  <goap:OAuthSecurity xmlns:goap="http://federatedgovernance.org/policy/oauth">
    <wsp:Policy>
      <goap:TokenTransformation transform="strip" />
    </wsp:Policy>
    <wsp:Policy>
      <goap:IncludeTokenAttributes Attributes="all" />
    </wsp:Policy>
    <wsp:Policy>
      <goap:ScopeRequirement evaluation="AND" />
    </wsp:Policy>
  </goap:OAuthSecurity>
</wsp:Policy>

Configuration Process

Let's take a quick walkthrough of the OAuth Security Policy configuration process to get you started.

Step 1: Review Policy (in Policy Manager Management Console)

Verify that the OAuth Security Policy is present in the Policies folder of the Community Manager Tenant Organization as illustrated below. It should be added automatically as part of the Community Manager feature installation.

Policies Summary page

If the policy does not display or you need an additional instance of the OAuth Security Policy to customize, use Add Policy to create one.

Policy Type list

This policy type creates an XML policy that looks like the following:

Default policy

Step 2: Assign Policy to API in Community Manager

Launch Community Manager perform the following steps:

Configure OAuth Details:

On the API Details page, select OAuth Details, select the OAuth Provider, set the OAuth version to OAuth 2.0, and configure your Resource Mapping based on your requirements.

API options Resource mapping

Assign Policy:

On the API Details page, select Edit, go to the Proxy page, select the OAuthSecuritypolicy, and save the configuration.

API Edit menu Policies list

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 policy, go to the Policies folder in the respective organization and attach the policy to a web service, binding, or binding operation.