oauth2_token_introspection

README

caddy-oauth2-token-introspection

A Caddy module which performs OAuth2 Token Introspection (RFC 7662) to authorize requests containing an OAuth2 access token.

When using Caddy as an API Gateway that sits in front of multiple upstream microservices, this module allows Caddy to authorize requests containing an OAuth2 access token by validating the access token with an OAuth2 Authorization server, rather than each individual upstream microservice from having to do so themselves.

This module is an HTTP handler middleware module, and thus can be used inside HTTP handler based directives (e.g. route, handle, etc).

Installation

Build Caddy using xcaddy and include the caddy-oauth2-token-introspection module:

xcaddy build v2.6.1 --with github.com/bploetz/caddy-oauth2-token-introspection

Usage

Example Caddyfile

# reusable snippet
(oauth2_protected) {
	oauth2_token_introspection {
		token_location bearer_token
		introspection_endpoint {$OAUTH2_SERVER_URI}/oauth2/introspect
		introspection_authentication_strategy client_credentials
		introspection_client_id {$OAUTH2_INTROSPECTION_CLIENT_ID}
		introspection_client_secret {$OAUTH2_INTROSPECTION_CLIENT_SECRET}
		introspection_timeout 1000
		set_header X-API-GATEWAY-SCOPE scope
		set_header X-API-GATEWAY-SUBJECT sub
		set_header X-API-GATEWAY-EMAIL-ADDRESS email
	}
}

# your API site
{$API_HOST} {
	@service_a_public_paths {
		path /v1/foo
		path /v1/bar
	}
	route {
		reverse_proxy @service_a_public_paths {$SERVICE_A_URI}
	}

	@service_a_protected_paths {
		path /v1/private
		path /v1/very-private
	}
	route {
		import oauth2_protected
		reverse_proxy @service_a_protected_paths {$SERVICE_A_URI}
	}
}

Configuration

The oauth2_token_introspection middleware supports the following configuration parameters:

token_location

Where to find the OAuth2 access token in the HTTP request coming into Caddy. Allowable values:

• bearer_token - The access token is in the standard Authorization: Bearer <mytoken> HTTP header

introspection_endpoint

The URL of the OAuth2 Token Introspection endpoint

introspection_authentication_strategy

How to authenticate with the OAuth2 Token Introspection endpoint. Allowable values:

• client_credentials - Use a client_id and client_secret to form a Basic Authentication request
• bearer_token - Use an OAuth2 bearer token (note: this is different than the bearer token on the HTTP request coming into Caddy that we are trying to authorize)

introspection_client_id

Required if the introspection_authentication_strategy is set to client_credentials

introspection_client_secret

Required if the introspection_authentication_strategy is set to client_credentials

introspection_bearer_token

Required if the introspection_authentication_strategy is set to bearer_token

introspection_timeout

The max length, in milliseconds, the token introspection request should finish in before timing out.

set_header

Exposes properties from a successful token introspection response as HTTP headers to upstream microservices. For example, for a token introspection response that looks like this:

{"active": true, "scope": "member", "sub": "abcd1234", "email": "john.doe@someone.com"}

The following headers will be added to the request proxied to the upstream service, so that has some context about the client making the API call:

set_header X-API-GATEWAY-SCOPE scope
set_header X-API-GATEWAY-SUBJECT sub
set_header X-API-GATEWAY-EMAIL-ADDRESS email

You may use dot notation to traverse nested objects in the token introspection response. An error will be raised if a set_header is pointed at a property that is not a scalar (i.e. you point at an object or an array).

For example, for a token introspection response that looks like this:

{"active": true, "scope": "member", "sub": "abcd1234", "user": {"email": "john.doe@someone.com", "first_name": "John", "last_name": "Doe", "preferences": ["foo, "bar"]}}

You can expose properties from the user object like so:

set_header X-API-GATEWAY-EMAIL user.email
set_header X-API-GATEWAY-FIRST-NAME user.first_name
set_header X-API-GATEWAY-LAST-NAME user.last_name

These would result in errors since they point at an object/array:

set_header X-API-GATEWAY-USER: user
set_header X-API-GATEWAY-USER-PREFS: user.preferences

Documentation

Index

• Constants
• type OAuth2TokenIntrospection
  • func (OAuth2TokenIntrospection) CaddyModule() caddy.ModuleInfo
  • func (o *OAuth2TokenIntrospection) Provision(ctx caddy.Context) error
  • func (o OAuth2TokenIntrospection) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error
  • func (o *OAuth2TokenIntrospection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
  • func (o *OAuth2TokenIntrospection) Validate() error

Constants

const BearerTokenAuthenticationStrategy = "bearer_token"

const BearerTokenLocation = "bearer_token"

const ClientCredentialsAuthenticationStrategy = "client_credentials"

Types

type OAuth2TokenIntrospection

type OAuth2TokenIntrospection struct {
	TokenLocation                       string            `json:"token_location"`
	IntrospectionEndpoint               string            `json:"introspection_endpoint"`
	IntrospectionAuthenticationStrategy string            `json:"introspection_authentication_strategy"`
	IntrospectionClientID               string            `json:"introspection_client_id"`
	IntrospectionClientSecret           string            `json:"introspection_client_secret"`
	IntrospectionBearerToken            string            `json:"introspection_bearer_token"`
	IntrospectionTimeout                int               `json:"introspection_timeout"`
	InboundHeaders                      map[string]string `json:"inbound_headers"`
	// contains filtered or unexported fields
}

OAuth2TokenIntrospection is a Caddy http.handlers Module for authorizing requests via OAuth2 Token Introspection

func (OAuth2TokenIntrospection) CaddyModule

func (OAuth2TokenIntrospection) CaddyModule() caddy.ModuleInfo

CaddyModule returns the Caddy module information.

func (*OAuth2TokenIntrospection) Provision

func (o *OAuth2TokenIntrospection) Provision(ctx caddy.Context) error

Provision sets up the module.

func (OAuth2TokenIntrospection) ServeHTTP

func (o OAuth2TokenIntrospection) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error

ServeHTTP implements caddyhttp.MiddlewareHandler.

func (*OAuth2TokenIntrospection) UnmarshalCaddyfile

func (o *OAuth2TokenIntrospection) UnmarshalCaddyfile(d *caddyfile.Dispenser) error

func (*OAuth2TokenIntrospection) Validate

func (o *OAuth2TokenIntrospection) Validate() error

Validate validates that the module has a usable config.