proxyfile

auth

auth is not an auth service. It checks each request before the proxy forwards it, in one of two ways or both:

The rest of this page up to Tokens is about ask, which the page calls the check.

services:
  accounts: {http: 7070}   # your service that answers the question
auth:
  ask: accounts /check     # the service and the path the proxy asks about each request
  timeout: 2s              # how long the proxy waits for the answer
  enabled: true            # true runs the check; false turns it off for every request
  when_unavailable: deny   # deny refuses a request the check could not answer; allow lets it through
  accept: [x-user-id]      # the headers of the answer copied onto the request, such as who the user is

The check is a plain HTTP request to your service, so your service needs nothing made for one proxy. With the envoy target it is Envoy's ext_authz in HTTP mode, with the nginx target the script proxyfile.js sends it through its relay (nginx), and with the haproxy target the script proxyfile.lua sends it (HAProxy). How the check works:

What the check is told

With send_request: true the check also learns which request it is asked about, in the headers forward-auth services read:

The request the check receives still goes to the path of ask. The proxy sets each of the four headers itself, so a client's own x-forwarded-uri, x-forwarded-method and x-forwarded-host never reach the check, also when send names them. Whose word the scheme is depends on client_address. With connection it is the connection's own, the scheme the service is sent, but the Envoy output tells the check an HTTP/2 request's :scheme: https for a request sent over plain HTTP with :scheme https, though the service is sent http, and http for one sent over TLS with :scheme http. It also tells http for a request sent over TLS whose absolute target says http, and answers 403 to an absolute https target sent over plain HTTP, which the nginx file serves and tells the check http. With forwarded, the default in a file without tls, it is the scheme of an absolute target when the request line holds one, and through the Envoy output an HTTP/2 request's :scheme, then the X-Forwarded-Proto the request arrived with, and the connection's scheme when it arrived with none; the service is sent that header, or the connection's scheme. A proxy in front sets the header, but the client writes the request line, and a client that reaches the gateway directly writes the header too, so the check then reads https for a request sent over plain HTTP. For an X-Forwarded-Proto of ftp the Envoy output tells the check the connection's scheme, where the nginx and HAProxy files tell it ftp, as it arrived. A gateway that faces its clients writes client_address: connection, and a check behind the Envoy output can trust an https it is told only with tls, as a client can send :scheme https over plain HTTP. The proxy sets x-forwarded-uri, x-forwarded-method and x-forwarded-host on the check's request alone: a client's own copies reach the service as sent, unless remove_from_clients names them.

The proxy normalises every request's path before anything reads it, with or without send_request (A route with auth: off says why): dot segments are resolved, repeated slashes merged and escaped slashes unescaped, and an escaped letter is written out (%61 as a). The check and the service then see the same path. For the service this means that an escaped slash inside one segment arrives as a real slash: /files/a%2Fb as /files/a/b. A backslash, written or as %5C, is read as a slash too. The proxy changes nothing else: a ; parameter on a name (/admin;x=1) and the case of a letter (/ADMIN) reach the check and the service as sent, so a check that decides by path must read them as the service does. send_request is off by default because a path can carry links and tokens. Measured on Envoy 1.40.2.

A check that answers another 2xx

Only 200 lets a request through. A check that answers 201, 202 or 204 refuses the request, and the client receives 403, with the check's body. 2.0 passed that 2xx on to the client, a success for a request that never reached the service. Envoy's HTTP mode has no setting that lets another 2xx through. Measured on Envoy 1.40.2.

A route with auth: off

A route with auth: off sends every request it takes to its service with no check and no token. The proxy normalises the request's path before it picks the route: /open/../private/report.txt is read as /private/report.txt and does not take a route with prefix: /open/ and auth: off. Measured on Envoy 1.40.2 with jwt and Python's static file server as the service: with no token, that path, /open/%2e%2e/private/report.txt and /open/..%2fprivate/report.txt are each answered 401, and no service is reached.

A dot segment with a ; parameter is refused, the ; written or escaped once. The proxy resolves ..; written with dots, but it writes %2e%2e; out as ..; and leaves it there, and a servlet container drops the parameter and resolves the dots: Tomcat 11 answered /open/..;/private/report.txt with /private/report.txt. The proxy keeps an escaped ;, %3B or %3b, as sent, so a hop that decodes it once on the way to the service would hand the service that same ..;. So the first route of every generated file answers 400 to a path that still holds /.;, /..;, /.%3B or /..%3B, with the hex in either case, and such a request reaches no service. The route does not turn auth off, so the token and the check are read before it answers: a request refused for its token or by the check gets that answer, such as the check's 401, instead of the 400, also under a prefix with auth: off, and a request they let through gets the 400; neither reaches a service (measured on Envoy 1.40.2). A ; escaped twice, %253B, passes as sent: a service that decodes the path twice is not covered. The HAProxy file has no route of its own for this: it asks the check about such a request whatever its route, answers the check's denial, and answers 400 once the check lets it through (HAProxy). The nginx file does the same through the location @pf_r_dotparam (nginx).

Envoy resolves ..; written with dots itself from 1.40.0, and from 1.36.10, 1.37.6, 1.38.4 and 1.39.1 on the older release lines, as their release notes say, while the runtime setting envoy.reloadable_features.strip_dotdot_segments_with_parameters is on, its default. On an older Envoy, or with the setting off, ..; stays in the path and the same first route answers 400: measured on Envoy 1.33.14, and on 1.40.2 with the setting off.

The proxy cannot read a path as every service does. A ; parameter on a name, such as /open/readme.txt;x=1, and the case of letters reach the route, the check and the service as sent. So write prefix with auth: off for a service that holds nothing that needs the check, as the sign-in services of the recipes are. A route that must open one path of a service that holds more is matched with path, not prefix.

Recipes

Each recipe shows the services, the auth block and the routes it needs. The sign-in route comes before the application's route, so it takes the sign-in pages first.

Your own service

ask a route of your service that answers 200 to let a request through and 401 or 403 to refuse it. Set the identity headers on the 200, and name each one in accept. Add send_request: true when the check decides by the request's path or method:

services:
  accounts: {http: 7070}
  app: {http: 8080}
auth:
  ask: accounts /check
  timeout: 2s
  enabled: true
  when_unavailable: deny
  send: [cookie]
  accept: [x-user-id, x-user-roles]
routes:
  - {name: sign-in, prefix: /sign-in/, to: accounts, auth: off}
  - {name: app, prefix: /, to: app}

oauth2-proxy

Measured on Envoy 1.40.2 with oauth2-proxy v7.15.6. The check asks oauth2-proxy at /, and its pages under /oauth2/ take a route with no check:

services:
  oauth2-proxy: {http: 4180}
  app: {http: 8080}
auth:
  ask: oauth2-proxy /
  timeout: 2s
  enabled: true
  when_unavailable: deny
  send_request: true
  send: [cookie, accept]
  accept: [x-auth-request-user, x-auth-request-email, x-auth-request-groups, x-auth-request-preferred-username]
routes:
  - {name: sign-in, prefix: /oauth2/, to: oauth2-proxy, auth: off}
  - {name: app, prefix: /, to: app}

oauth2-proxy needs these settings, next to its own provider and cookie settings:

Do not ask oauth2-proxy's /oauth2/auth. It answers 202 to a signed-in request, which is a refusal here, so every such request would get 403.

Authelia

Measured on Envoy 1.40.2 with Authelia v4.39.28. The check asks Authelia's /api/verify, with the https URL of Authelia's portal, url-encoded, in rd:

services:
  authelia: {http: 9091}
  app: {http: 8080}
auth:
  ask: authelia /authelia/api/verify?rd=https%3A%2F%2Fapp.example.com%2Fauthelia%2F
  timeout: 2s
  enabled: true
  when_unavailable: deny
  send_request: true
  send: [cookie, accept]
  accept: [remote-user, remote-groups, remote-email, remote-name]
routes:
  - {name: sign-in, prefix: /authelia/, to: authelia, auth: off}
  - {name: app, prefix: /, to: app}

Authelia needs these settings, next to the rest of its configuration:

Authelia refuses every request whose x-forwarded-proto is not https, so the request must reach the proxy over https: the proxy serves it with tls, or a proxy in front serves it and sends X-Forwarded-Proto: https, with client_address: forwarded.

Do not ask Authelia's forward-auth endpoint, /api/authz/forward-auth. The check is sent with the client's method, and that endpoint answers 405 to every method but GET and HEAD, and lets an OPTIONS request with no session through with 200.

What both need

Tokens

With jwt the proxy verifies a signed token, a JWT, on each request itself: its signature against your keys, its issuer, its audience and its expiry. examples/jwt verifies tokens with no check, in YAML and HOCON:

services:
  app: {http: 3000}
  identity: {http: 4000}                # the sign-in service, which issues the tokens
auth:
  jwt:
    issuer: https://login.example.com   # the iss a token must carry
    audiences: [api.example.com]        # its aud must hold one of them; any accepts every audience
    keys: /etc/gateway/jwt/jwks.json    # the signing keys: a JWKS file on the proxy's host, or an https URL
    claims:
      x-user-id: sub                    # the token's sub reaches the service in x-user-id
      x-user-roles: realm.roles         # a nested claim, written with dots
routes:
  - {name: sign-in, prefix: /login/, to: identity, auth: off}
  - {name: app, prefix: /, to: app}

What a request gets:

The keys:

The claims:

With ask and jwt together:

Before either: a request over a rate limit is refused before its token is verified, and a browser's CORS preflight is answered before either runs, as it carries no token.

Each behaviour in this section was measured on Envoy 1.40.2, except the 10 minutes, which are Envoy's default, and the 2 seconds, which the generated file sets.

The example's /etc/gateway/jwt/jwks.json is a path on the proxy's host, or in its container. scripts/validate-envoy.sh validates each example with a throwaway key set and CA bundle mounted at /etc/gateway/jwt, made for each run and removed after it.

Keys

Key Meaning Rule Class
auth The checks every request goes through before it reaches a service: a service of yours asked about each request, a signed token the proxy verifies, or both. A mapping. At least one of ask and jwt. Without auth there is no check. core
auth.ask The service and the path the gateway asks. A service and a path, such as accounts /check. The service needs an http port. core
auth.timeout How long the gateway waits for the answer. A time such as 2s. Required with ask, and refused without it. At most 4294967295s. none is not accepted. core
auth.enabled true runs the check on every request it applies to, false on none. true or false. Required with ask, and refused without it. It does not turn jwt off. core
auth.when_unavailable What happens to a request when the check cannot be asked: allow lets it through, deny refuses it. allow or deny. Required with ask, and refused without it. core
auth.only_with_header The check runs only on requests that carry this header. A lower-case header name. A request without it, or with it empty, goes through with no check. Needs ask. core
auth.send The request headers the check is sent; a name ending in * is a prefix. A list; each item is a lower-case header name, or a prefix ending in *. Needs ask. core
auth.accept The headers of the check's answer that reach the service; a name ending in * is a prefix. A list; each item is a lower-case header name, or a prefix ending in *. Needs ask. core
auth.send_request true also tells the check which request it is asked about: its path and query in x-forwarded-uri, its method in x-forwarded-method, its scheme in x-forwarded-proto and its host in x-forwarded-host; false when not written. true or false. Needs ask. core
auth.jwt The proxy verifies a signed token (a JWT) on each request itself: its signature against your keys, its issuer, its audience and its expiry. A mapping. A request without a valid token is answered 401, or 403 when its audience is not accepted, and reaches neither the check nor a service, unless its route writes auth: off. A token with no expiry is refused. core
auth.jwt.issuer The iss claim a token must carry. Required. One character or more. core
auth.jwt.audiences The audiences accepted: a token's aud must hold one of them, or any accepts every audience. Required. A list of audiences, or any. any lets a token minted for another application of the same issuer through, so it is written on purpose. core
auth.jwt.keys Where the signing keys come from, as a JWKS: a file on the proxy's host, or an https URL the proxy fetches and keeps for 10 minutes. Required. An absolute path, or a URL starting with https://. core
auth.jwt.ca The CA bundle, PEM, the keys URL's certificate must chain to; /etc/ssl/certs/ca-certificates.crt when not written. An absolute path. Only with a URL in keys. A path that does not exist stops the proxy at start. core
auth.jwt.header The header that carries the token; authorization, with the Bearer scheme, when not written. A lower-case header name. Any other header carries the bare token. A token anywhere else, such as in the query, is never read. Not cookie. core
auth.jwt.optional true lets a request with no token through unverified; a request with a token that fails is still refused. false when not written. true or false. A token the proxy does not read, such as one after bearer in lower case, counts as no token, so with true the request passes and the service receives that token unverified. core
auth.jwt.claims Claims copied into request headers for the service, by header name. A mapping keyed by header name. Not a header send or accept names, nor the header that carries the token. A claim that is not text arrives as the base64 of its JSON. core
auth.jwt.claims.<header name> The claim it holds, with dots for a nested claim. A claim name, with dots for a nested claim, such as realm.roles. The header name is a lower-case header name. core