Documentation

Policies Reference

OAuth 2.0 Introspection

Description

The OAuth 2.0 Introspection policy implements a client leveraging the Introspection extension for the oAuth 2.0 authorization protocol as defined in the RFC-7662 standard.

Express Gateway plays the role of a resource server, which can be configured to query the defined introspection endpoint and based on its response, let the request continue its flow or stop it if required.

When a client’s token has been verified, Express Gateway will append property and authentication headers to the request before proxying it to the downstream service, so that you can identify the consumer and the end-user in your service.

Moreover, the decrypted token response will be placed as the current req.user. In case you need to pass some additional values to your downstream services (such as a custom property in the user object) you can use the rewrite policy.

Usage

To enable the OAuth2 Introspection policy, add oauth2-introspect in gateway.config.yml in the policies section.

policies:
  - oauth2-introspect

Example

pipelines:
  pipeline1:
    apiEndpoints:
      - authorizedEndpoint
    policies:
      - oauth2-introspect:
          - action:
              endpoint: 'https://authorization.cloud.server/introspect'
              authorization_value: 'YXBpMTpzZWNyZXQ=',
              ttl: 400
      - proxy:
          - action:
              serviceEndpoint: backend

Options Reference

• endpoint
  • The endpoint implementing the introspection RFC.
  • required
• authorization_value:
  • the value to append to the Authorization header when requesting the introspection endpoint. This depends on your oAuth2 server implementation. Most of the times, it’s nothing more than your clientId:clientSecret base64 encoded.
  • required
• ttl:
  • the TTL in seconds for the introspection response. Whithin this time, the same token will be take as valid and the cached response will be returned directly without querying the authorization server. Set to 0 to disable the expiration.
  • required, default value: 60
• passThrough:
  • determines whether the gateway should execute the successive policy in case the auth process fails. If set to false, the gateway will return an Unauthorized response.
  • default value: false