Authentication using External Auth Service

EnRoute Technical Reference

External Auth Plugin

The External Auth plugin provides a mechanism to authenticate incoming requests against an external auth service

External Auth System Diagram

Enroute external authentication
  • User makes a request [1]
  • EnRoute sends request to external auth service
  • External Auth service authenticates the request and responds back to EnRoute (either 200 OK or 4xx defined code)
  • Depending on the return code, EnRoute forwards the request to upstream or sends an error response back to the client

External Authentication Filter Configuration

External Auth filter configuration needs the following config

  • An external Auth Service that follows the specification defined for Envoy Proxy to sending requests to an external service for authentication using ext_authz filter

  • External Auth Filter config

urlA URI specifying how to reach the external authentication service. It specifies the protocol to use, along with the namespace, name and port of the service
auth_service_protoSpecifies the protocol used to talk to the external auth service. It can be either http or gRPC
body_max_bytesMaximum of body bytes to be sent to the external authentication service
body_allow_partialUsed in conjuntion with body_max_bytes. If body is larger than body_max_bytes, the partial body is sent to external auth service
status_on_errorThe status code to use on an error, eg: 403 (forbidden)
failure_mode_allowIf set, it allows the client request to pass through even when external auth service is unreachable
timeoutThe timeout used in connecting with external auth service. Depending on failure mode, the request may or may not be allowed
path_prefixPath prepended to request path before sending it to an external auth service.
allowed_request_headersHeaders sent to the external auth service (always including Authorization, Cookie, From, Proxy-Authorization, User-Agent, X-Forwarded-For, X-Forwarded-Host, and X-Forwarded-Proto)
allowed_authorization_headersHeaders allowed in from external auth service. This list of headers are received from external auth service and then sent to upstream (always including Authorization, Location, Proxy-Authenticate, Set-cookie, WWW-Authenticate)
External Authentication Filter Config Example
kind: HttpFilter
  name: extauthz-filter
  namespace: httpbin
    config: |
            "url" : "https://ext-authz-ns.ext-auth:8443",
            "auth_service" : "ext-auth",
            "auth_service_proto" : "http",
            "body_max_bytes" : 4096,
            "body_allow_partial" : true,
            "status_on_error" : 403,
            "failure_mode_allow" : true,
            "timeout" : 10,
            "path_prefix" : "",
            "allowed_request_headers": ["x-stamp", "requested-status", "x_forwarded_for", "requested-cookie"],
            "allowed_authorization_headers" : ["ext-authz-example-header", "x-auth-accountId", "x-auth-userId", "x-auth-token"]
  name: extauthz-filter
  type: http_filter_extauthz


ext_authz is a community plugin

ext_authz plugin is a global HttpFilter. It sets configuration on the Listener and is applicable to all GatewayHost when defined.