forward-auth

Delegates authentication to an external service.

Category AuthenticationAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin forward-authPriority 2002

What it does

forward-auth asks an authorization service of your own about every request before it goes on to the route's backend. The gateway calls URI with the headers listed under Request headers, the client's Authorization header for example. Whatever the client signs in with is checked by that service, not by a consumer or a credential on the gateway.

When the service answers with a 2xx, the request reaches the backend with the headers listed under Upstream headers copied from that answer. Any other answer goes back to the client with the service's own status, a 401 or a 403 for example, and the headers listed under Client headers. Authentication shows the other ways a request is checked.

When to use it

• Your company already runs a service that checks its session tokens or cookies, and every API behind the gateway should ask it instead of checking them again.
• The backend needs to know who called and with which roles: the service answers with X-User-Id and X-User-Roles, and the gateway copies them onto the request.
• The decision depends on the body, which order a partner may touch for example: with Request method set to POST, the service receives the client's body.
• A sign-in scheme no other plugin speaks, kept in a service your team writes and changes on its own schedule.

Not for a credential the gateway checks itself, an API key for example — see key-auth (Authenticates consumers with an API key sent in a header or query parameter), permissions kept in Keycloak's authorization services — see authz-keycloak (Authorizes requests with Keycloak's authorization services) or tokens from an OpenID Connect identity provider — see openid-connect (Authenticates users against an OpenID Connect provider).

Set it up

Ask an authorization service before the request goes on and pass its verdict along

A 2xx from the service lets the request on with the service's X-User headers; any other answer is sent back to the client with the Www-Authenticate header the service gave.

Under Basics set URI to https://auth.example.com/verify. Under Behavior fill Request headers as in the JSON below, fill Upstream headers as in the JSON below, fill Client headers as in the JSON below and set Timeout to 2000 milliseconds.

forward-auth · as the console saves it

{
  "uri": "https://auth.example.com/verify",
  "request_headers": [
    "Authorization",
    "Cookie"
  ],
  "upstream_headers": [
    "X-User-Id",
    "X-User-Roles"
  ],
  "client_headers": [
    "Www-Authenticate"
  ],
  "timeout": 2000
}

More scenarios

Send the request body to the authorization service as a POST

Under Basics set URI to https://auth.example.com/verify, set Request method to POST and set Request body limit to 65536. Under Behavior fill Request headers as in the JSON below.

forward-auth · as the console saves it

{
  "uri": "https://auth.example.com/verify",
  "request_method": "POST",
  "max_req_body_size": 65536,
  "request_headers": [
    "Authorization"
  ]
}

Things to know

• Upstream headers — With X-User-Id listed, the backend receives the value the service answered for that client, alice in the example.
• Client headers — With Www-Authenticate listed, a client the service refuses receives the service's 401 together with its Www-Authenticate: Bearer realm="orders".
• Request method — With POST, the service reads the client's body and decides by it. An order it allows is answered 200, and any other order the 403 the service gave.
• Request method — Only GET and POST can be set; PUT is refused when you save.
• URI — An address without its scheme, http:// or https://, is refused when you save.
• Extra headers — A header name that carries a colon is refused when you save.
• Status on error — Read only when the service cannot be reached: one that answers a refusal reaches the client with its own status and body.
• Allow degradation — On, a request the service could not be asked about travels to the upstream unauthorized, and the status above is never used.
• AdviceKeep Timeout short and the authorization service near the gateway, since it is asked about every request.
• On a consumer or a consumer group it runs only after the consumer has been identified by a credential; it does not identify the consumer itself.

Settings

The fields as the console shows them, section by section. A field under “When … is …” is there only while that value is set.

Basics

URIuristringRequired

The address of the authorization service, scheme included. Every request is announced to it with the five X-Forwarded headers.

an http or https address

pattern

^https?://

· example http://auth.internal:8080/verify

Request methodrequest_methodstringdefault GET

GET sends the request's headers only. POST also sends the client's body.

one of GET, POST

When Request method is POST

Request body limitmax_req_body_sizeintegerdefault 67108864

The largest client body, in bytes, forwarded to the service. A larger request is answered 413.

at least 1

Behavior

Request headersrequest_headersarray of stringsdefault []

Request headers copied to the service, such as Authorization. X-Forwarded-* names keep the plugin's own values.

Upstream headersupstream_headersarray of stringsdefault []

Headers copied from the service's answer onto the request to the upstream, such as X-User-Id. One the answer lacks is removed.

Client headersclient_headersarray of stringsdefault []

Read from a refusal and sent on to the client with it.

Extra headersextra_headersobject

Extra headers sent to the service, such as X-Route: $uri. A $name is read from the request, and these replace the plugin's X-Forwarded-* values. An object whose keys are a name without a colon, each with a string as its value.

at least 1 key

Status on errorstatus_on_errorintegerdefault 403

200 to 599

Timeouttimeoutintegerdefault 3000

1 to 60000 · in milliseconds

SSL verifyssl_verifybooleandefault true

Advanced

Allow degradationallow_degradationbooleandefault false

Keepalivekeepalivebooleandefault true

Keepalive poolkeepalive_poolintegerdefault 5

at least 1

Keepalive timeoutkeepalive_timeoutintegerdefault 60000

at least 1000 · in milliseconds

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.