oauth2

description
This page provides the technical details of the OAuth2 policy

OAuth2

Overview

You can use the oauth2 policy to check access token validity during request processing using token introspection.

If the access token is valid, the request is allowed to proceed. If not, the process stops and rejects the request.

The access token must be supplied in the Authorization HTTP request header:

$ curl -H "Authorization: Bearer |accessToken|" \
           http://gateway/api/resource

Functional and implementation information for the oauth2 policy is organized into the following sections:

• Examples
• Configuration
• Compatibility Matrix
• Errors
• Changelogs

Examples

{% hint style="warning" %} This policy can be applied to v2 APIs and v4 HTTP proxy APIs. It cannot be applied to v4 message APIs or v4 TCP proxy APIs. {% endhint %}

{% tabs %} {% tab title="HTTP proxy API example" %} Given the following introspection response payload:

{
    "active": true,
    "client_id": "VDE",
    "exp": 1497536237,
    "jti": "5e075c1c-f4eb-42a5-8b56-fd367133b242",
    "scope": "read write delete",
    "token_type": "bearer",
    "username": "flx"
}

You can extract the username from the payload using the following JsonPath:

{#jsonPath(#context.attributes['oauth.payload'], '$.username')}

{% endtab %} {% endtabs %}

Configuration

The oauth2 policy requires a resource to access an OAuth2 Authorization Server for token introspection. APIM supports two types of authorization server:

• Generic OAuth2 Authorization Server: A resource which can be configured to cover any authorization server.
• Gravitee.io AM Authorization Server: A resource which can be easily plugged into APIM using Gravitee.io Access Management with security domain support.

{% code title="Sample Configuration" %}

{
  "oauth2": {
    "oauthResource": "oauth2-resource-name",
    "oauthCacheResource": "cache-resource-name",
    "extractPayload": true,
    "checkRequiredScopes": true,
    "requiredScopes": ["openid", "resource:read", "resource:write"]
  }
}

{% endcode %}

Phases

The phases checked below are supported by the oauth2 policy:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	false	onResponse	false
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

The oauth2 policy can be configured with the following options:

Property	Required	Description	Type	Default
oauthResource	true	The OAuth2 resource used to validate access_token. This must reference a valid Gravitee.io OAuth2 resource.	string
oauthCacheResource	false	The Cache resource used to store the access_token. This must reference a valid Gravitee.io Cache resource.	string
extractPayload	false	When the access token is validated, the token endpoint payload is saved in the oauth.payload context attribute	boolean	false
checkRequiredScopes	false	Whether the policy needs to check required scopes to access the underlying resource	boolean	false
requiredScopes	false	List of scopes to check to access the resource	boolean	array of string

Attributes

The oauth2 policy can be configured with the following attributes:

Name	Description
oauth.access_token	Access token extracted from Authorization HTTP header.
oauth.payload	Payload from token endpoint / authorization server, useful when you want to parse and extract data from it. Only if extractPayload is enabled in policy configuration.

Compatibility matrix

The following is the compatibility matrix for APIM and the oauth2 policy:

Plugin Version	Supported APIM versions
1.x	Up to 3.19.x
2.0.x	3.20.x
3.x	4.x+

Errors

HTTP Status Code	Message
401	* No OAuth Authorization Server resource has been configured * No OAuth authorization header was supplied * No OAuth access token was supplied * Access token can not be validated by authorization server
403	* Access token can not be validated because of a technical error with authorization server * One of the required scopes was missing while introspecting access token

You can use the response template feature to override the default response provided by the policy. These templates must be defined at the API level (see the API Console Response Templates option in the API Proxy menu).

The error keys sent by this policy are as follows:

Key	Parameters
OAUTH2_MISSING_SERVER	-
OAUTH2_MISSING_HEADER	-
OAUTH2_MISSING_ACCESS_TOKEN	-
OAUTH2_INVALID_ACCESS_TOKEN	-
OAUTH2_INVALID_SERVER_RESPONSE	-
OAUTH2_INSUFFICIENT_SCOPE	-
OAUTH2_SERVER_UNAVAILABLE	-

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-OAuth2/blob/master/CHANGELOG.md" %}