Basic Auth (proto)

This extension has the qualified name envoy.filters.http.basic_auth

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

This extension must be configured with one of the following type URLs:

Basic Auth configuration overview.

extensions.filters.http.basic_auth.v3.BasicAuth

[extensions.filters.http.basic_auth.v3.BasicAuth proto]

Basic HTTP authentication.

Example:

users:
  inline_string: |-
    user1:{SHA}hashed_user1_password
    user2:{SHA}hashed_user2_password

{
  "users": {...},
  "forward_username_header": ...,
  "authentication_header": ...,
  "allow_missing": ...,
  "emit_dynamic_metadata": ...
}
users

(config.core.v3.DataSource) Username-password pairs used to verify user credentials in the “Authorization” header. The value needs to be the htpasswd format. Reference to https://httpd.apache.org/docs/2.4/programs/htpasswd.html

forward_username_header

(string) This field specifies the header name to forward a successfully authenticated user to the backend. The header will be added to the request with the username as the value.

If it is not specified, the username will not be forwarded.

authentication_header

(string) This field specifies the request header to load the basic credential from.

If it is not specified, the filter loads the credential from the “Authorization” header.

allow_missing

(bool) If set to true, requests without Basic credentials (missing Authorization header, or Authorization header with a non-Basic scheme such as Bearer) are allowed to pass through without authentication. Requests that present Basic credentials are still fully validated.

This is useful when combining BasicAuth with other authentication methods (e.g. JWT) to achieve OR semantics: a request is accepted if any one configured auth method succeeds. When allow_missing is true on all auth filters, pair it with an RBAC filter that checks the dynamic metadata emitted by this filter (see emit_dynamic_metadata) to ensure at least one method authenticated the request. Requires emit_dynamic_metadata to be set to true.

emit_dynamic_metadata

(bool) If set to true, the filter emits dynamic metadata on successful authentication with key username set to the authenticated username. The metadata is emitted under the namespace corresponding to the name of this basic_auth filter as configured in the http_filters chain (e.g. if the filter is configured with name envoy.filters.http.basic_auth, that is the namespace that will be used).

This is typically enabled together with allow_missing when combining BasicAuth with other authentication methods (e.g. JWT) and using a downstream RBAC filter to enforce OR semantics.

extensions.filters.http.basic_auth.v3.BasicAuthPerRoute

[extensions.filters.http.basic_auth.v3.BasicAuthPerRoute proto]

Extra settings that may be added to per-route configuration for a virtual host or a cluster.

{
  "users": {...}
}
users

(config.core.v3.DataSource, REQUIRED) Username-password pairs for this route.