web-proxy gates access with any combination of basic auth, bearer keys, a branded session login page, and OpenID Connect. This page documents every authentication variable and the behavior of each type. See Usage for the rest of the configuration.

Variables

Variable	Default	Description
AUTH_TYPE	none	Comma-separated list of none, basic, bearer, forms, oidc. Multiple types are enabled simultaneously and a request is allowed if it passes any of them, e.g. basic,bearer. none alone disables auth; combining it with other types disables them too
AUTH_USER	admin	The username for basic and forms auth
AUTH_PASS	random	The hex sha256 of the password for basic and forms auth
AUTH_KEYS	unset	Comma separated hex sha256 hashes accepted by bearer auth
AUTH_SESSION_TTL	24h	How long a forms session cookie lasts
AUTH_COOKIE_SECURE	true	Sets the Secure flag on the forms session cookie. Set to false only when serving plain HTTP without TLS termination
AUTH_FORM_TITLE	Sign in	The heading on the forms login page
AUTH_FORM_SUBTITLE	Enter your credentials to continue	The tagline on the forms login page
AUTH_FORM_COLOR	#6366f1	The accent color used on the forms login page
AUTH_FORM_TEMPLATE	unset	A path to a custom .gohtml that overrides the embedded login template
AUTH_OIDC_ISSUER	unset	Issuer URL of the OIDC provider, used by the oidc type
AUTH_OIDC_CLIENT_ID	unset	Client id registered with the provider
AUTH_OIDC_CLIENT_SECRET	unset	Client secret for a confidential client; leave unset for a public client using PKCE
AUTH_OIDC_REDIRECT_URL	unset	Public URL the provider redirects back to, e.g. https://app.example.com/oauth2/callback. Its path is the callback route
AUTH_OIDC_SCOPES	openid,email,profile	Scopes requested from the provider; must include openid
AUTH_EXCLUDE_PATHS	unset	Comma-separated request paths that skip auth entirely, e.g. /.well-known/*,/oauth2/token

Passwords and bearer keys are stored as lowercase hex sha256 hashes. Generate one for a password with a standard tool on the shell.

printf 'secret' | sha256sum

Set AUTH_PASS to that output. When AUTH_PASS is left unset a random password is generated instead, so authentication always denies access until you configure one. The authentication example shows a container wired up with each auth type.

Multiple types

List several types in AUTH_TYPE to accept any of them, for example AUTH_TYPE=basic,bearer lets browsers sign in with basic auth while machine clients use an API key, and AUTH_TYPE=forms,bearer keeps the branded login page for people and a key header for services. A request is checked against each configured type and passes if any single one accepts it: an Authorization header is matched to its scheme, a valid forms session cookie always passes, and only when no header credentials were rejected does an unauthenticated browser request get served the login page.

Excluding paths

AUTH_EXCLUDE_PATHS is a comma-separated list of request paths that skip authentication entirely, for example AUTH_EXCLUDE_PATHS=/.well-known/*,/oauth2/token. This is useful when the proxied app serves machine endpoints that authenticate themselves, such as an OIDC provider whose token endpoint must be reachable without a browser session.

• Entries must begin with /; anything else is ignored with a warning.
• A pattern ending in /* matches every descendant of that path: /oauth2/* matches /oauth2/token and /oauth2/a/b, but not /oauth2 itself.
• Any other pattern is a path.Match glob, where * does not cross /.
• Matching is case-sensitive and runs on the cleaned, URL-decoded request path, so .., duplicate slashes and encoded separators cannot smuggle a request past the check. The query string is not considered.
• An exclusion list only widens access; keep entries as narrow as possible and review changes carefully.

Excluded requests still pass through the blocking rules, and any X-Auth-Request-* headers a client sends are stripped as usual.

basic

The client supplies the AUTH_USER and AUTH_PASS pair through standard HTTP basic auth. The password is hashed on every request and compared against AUTH_PASS.

bearer

The client sends an API key in the Authorization header. The key is hashed and matched against AUTH_KEYS. When AUTH_KEYS is unset the single AUTH_PASS value is accepted. This type is suited to machine clients such as services and monitoring probes.

A key may also be sent in the X-Api-Key header, which is accepted as an alternative to Authorization: Bearer while the bearer type is enabled. This lets a service authenticate with its own key on a request whose Authorization header carries someone else's credential, for example when web-proxy gates a service that itself authenticates with a bearer token.

forms

The proxy serves a login page for anything that is not authenticated. A successful login sets a signed session cookie that lasts for AUTH_SESSION_TTL. Sessions are verified on every request, and the login page can be restyled through the AUTH_FORM_* variables. Point AUTH_FORM_TEMPLATE at a custom .gohtml that redefines the form or bootstrap templates for full design control. The value form is accepted as an alias of forms.

oidc

The oidc type offloads authentication to an external OpenID Connect provider, which owns the login UI. An unauthenticated browser is redirected to the provider's authorization endpoint with state, nonce, and PKCE (S256); the callback verifies the ID token against the provider's JWKS and then sets the same signed session cookie used by forms. Configuration must be secure: the issuer and redirect URL must use https unless they point at localhost.

Machine clients do not run the browser flow; instead they present an access token from the provider as Authorization: Bearer <token>. The token is verified against the provider's JWKS and the token_use=access claim, and is accepted for the same client the proxy is registered as. A rejected token still falls through to the browser flow, so unknown bearer values are not silently trusted.

The verified identity is passed to the upstream application on every request through headers, which lets the application make its own authorization decisions:

Header	Contents
X-Auth-Request-User	The token sub (subject)
X-Auth-Request-Email	The email claim, when present
X-Auth-Request-Role	The role claim, when present
X-Auth-Request-Access-Token	The provider's access token, for calling the provider's API

Any X-Auth-Request-* headers sent by the client are stripped before the request is handled, so the upstream can trust them.