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
- OAuth Security Policy Configuration Options
- Configuration Process
- Activating a policy
- Attaching a policy
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:
|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.
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:
|OAuthSecurity policy: ScopeRequirement option||
Use this to configure how multiple scopes are evaluated:
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>
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.
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.
This policy type creates an XML policy that looks like the following:
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.
On the API Details page, select Edit, go to the Proxy page, select the OAuthSecuritypolicy, and save the configuration.
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.