OAuth2 Policy

Phase

onRequest	onResponse
X

Description

The OAuth2 policy checks access token validity during request processing by doing 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 supply in the Authorization HTTP request header :

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

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 from policy configuration.

Extract data from OAuth2 token introspection response

If the introspection response payload is as follow:

{
    "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 payload by using JSON-path:

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

Configuration

OAuth2 policy requires a resource to access an OAuth2 Authorization Server for token introspection. Currently, Gravitee.io API Management supports two types of authorization server:

• Generic OAuth2 Authorization Server: a resource which can be configured to cover any authorization server.

• Gravitee.io Access Management: a resource which can be used to plugged easily Gravitee.io API Management with Gravitee.io Access Management with security domain support.

Property	Required	Description	Type	Default
oauthResource	X	The OAuth2 resource used to validate access_token. This must reference a valid Gravitee.io OAuth2 resource.	string
extractPayload	-	When access token is validated, the token endpoint payload is saved under the oauth.payload context attribute.	boolean	false
checkRequiredScopes	-	Should the policy check required scopes to access underlying resource ?	boolean	false
requiredScopes	-	The list of scopes to check to access the resource.	boolean	array of string

OAuth2 Policy example:

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

Http Status Code

Code	Message
401	In case of: * 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	In case of: * Access token can not be validated because of a technical error with authorization server. * One of the required scopes is missing while introspecting access token.