All configuration options
Root configuration object#
| Name | Type | Description | |
|---|---|---|---|
server.domains | list of domain configurations | Domains served by Traefik Forward Auth Each entry sets the cookie domain for matching requests, and optionally the public hostname where Traefik Forward Auth is reachable for that domain ( authHost)authHost is only required when running in “dedicated sub-domain” mode; in “sub-path” mode the request host is used and authHost can be omittedauthHost must be the same as, or a sub-domain of, domain.If omitted, it defaults to domain | Recommended |
server.domains.$.domain | string | Domain name used when setting cookies, and matched against the request hostname | Required |
server.domains.$.authHost | string | Public hostname where Traefik Forward Auth is reachable for this domain Used for OAuth2 callback URLs and redirects to the sign-in page when running in “dedicated sub-domain” mode Must be the same as, or a sub-domain of, domainIf omitted, defaults to the value of domain (which is appropriate when running in “sub-path” mode) | |
server.port | number | Port to bind to. | Default: 4181 |
server.bind | string | Address/interface to bind to. | Default: “0.0.0.0” |
server.basePath | string | Base path for all routes. Set this if Traefik is forwarding requests to traefik-forward-auth for specific paths only. Note: this does not apply to /healthz routes | |
server.tlsPath | string | Path where to load TLS certificates from. Within the folder, the files must be named tls-cert.pem and tls-key.pem (and optionally tls-ca.pem).The server watches for changes in this folder and automatically reloads the TLS certificates when they’re updated. If empty, certificates are loaded from the same folder where the loaded config.yaml is located. | Default: Folder where the config.yaml file is located |
server.tlsCertPEM | string | Full, PEM-encoded TLS certificate. Using server.tlsCertPEM and server.tlsKeyPEM is an alternative method of passing TLS certificates than using server.tlsPath. | |
server.tlsKeyPEM | string | Full, PEM-encoded TLS key. Using server.tlsCertPEM and server.tlsKeyPEM is an alternative method of passing TLS certificates than using server.tlsPath. | |
server.tlsCAPEM | string | Full, PEM-encoded TLS CA certificate, used for TLS client authentication (mTLS). This is an alternative method of passing the CA certificate than using tlsPath.Note that this is ignored unless server.tlsClientAuth is set to true. | |
server.tlsClientAuth | boolean | If true, enables mTLS for client authentication. Requests to the root endpoint (normally used by Traefik) must have a valid client certificate signed by the CA. | Default: false |
server.trustedRequestIdHeader | string | String with the name of a header to trust as ID of each request. The ID is included in logs and in responses as X-Request-ID header.Common values include: - X-Request-ID: a de-facto standard
that’s vendor agnostic- CF-Ray: when the application is served by a Cloudflare CDNIf this option is empty, or if it contains the name of a header that is not found in an incoming request, a random UUID is generated as request ID. | |
server.favicon | string | Favicon for the app. If this starts with “http://” or “https://”, it’s treated as a URL and fetched when the server starts up. Otherwise, it’s treated as base64-encoded image data. The favicon must be an ICO, PNG, or SVG image. | |
cookies.namePrefix | string | Prefix for the cookies used to store the sessions. | Default: “tf_sess” |
cookies.insecure | boolean | If true, sets cookies as “insecure”, which are served on HTTP endpoints too. By default, this is false and cookies are sent on HTTPS endpoints only. | Default: false |
tokens.sessionLifetime | duration | Lifetime for sessions after a successful authentication. This can be overridden on each portal. | Default: “2h” |
tokens.signingKey | string | String used as key to sign state tokens. Can be generated for example with openssl rand -base64 32If left empty, it will be randomly generated every time the app starts (recommended, unless you need user sessions to persist after the application is restarted). | |
tokens.signingKeyFile | string | File containing the key used to sign state tokens. This is an alternative to specifying signingKey tokens.directly. | |
tokens.sessionTokenAudience | string | Value for the audience claim to expect in session tokens used by Traefik Forward Auth. Defaults to a value based on the current environment, which is appropriate for the majority of cases. Most users should rely on the default value. | |
logs.level | string | Controls log level and verbosity. Supported values: debug, info (default), warn, error. | Default: “info” |
logs.omitHealthChecks | boolean | If true, calls to the healthcheck endpoint (/healthz) are not included in the logs. | Default: true |
logs.json | boolean | If true, emits logs formatted as JSON, otherwise uses a text-based structured log format. Defaults to false if a TTY is attached (e.g. in development); true otherwise. | |
defaultPortal | string | If set to the name of a portal defined in “portals”, it makes the portal available on the root endpoint, without the portals/<name>/ prefix |
Portal configuration#
| Name | Type | Description | |
|---|---|---|---|
portals.$.name | string | Name of the portal, as used in the URL. | Required |
portals.$.displayName | string | Optional display name. Defaults to the name property if not set. | |
portals.$.alwaysShowProvidersPage | boolean | If true, always shows the providers selection page, even when there’s a single provider configured. Has no effect when there’s more than one provider configured. | Default: false |
portals.$.authenticationTimeout | duration | Timeout for authenticating with the authentication provider. | Default: 5m |
portals.$.sessionLifetime | duration | Lifetime for sessions after a successful authentication for the portal. If set, this overrides the default value configured in the tokens section for this portal. | |
portals.$.backgroundMedium | string | URL to override the background image for the portal, size medium. The recommended size is 720x1080. | |
portals.$.backgroundLarge | string | URL to override the background image for the portal, size large. The recommended size is 940x1410. | |
portals.$.headers | list of headers | List of HTTP headers to add to the response. | |
portals.$.headers.$.name | string | Name of the header. | Required |
portals.$.headers.$.claim | string | ID token claim to use as the header’s value. Only scalar values (strings, numbers, and booleans) are supported for the moment. | |
portals.$.headers.$.property | string | Property to use as the header’s value. Supported properties are portal.name and provider.name. | |
providers | list of provider configurations | List of allowed authentication providers See the provider configuration section for more details. | Required At least one provider is required. |
Provider Configuration#
The configuration depends on the kind of provider used. Currently, the following providers are supported:
Using GitHub#
Example:
portals:
name: "default"
providers:
-
github:
#name: "my-github-auth"
#displayName: "GitHub"
clientID: "your-client-id"
clientSecret: "your-client-secret"
#clientSecretFile: "/var/run/secrets/traefik-forward-auth/github/client-secret"
## Default: "10s"
#requestTimeout: "10s"
#icon: "github"
#color: "emerald"Using Google#
Example:
portals:
name: "default"
providers:
-
google:
#name: "my-google-auth"
#displayName: "Google"
clientID: "your-google-client-id.apps.googleusercontent.com"
clientSecret: "your-client-secret"
#clientSecretFile: "/var/run/secrets/traefik-forward-auth/google/client-secret"
## Default: "10s"
#requestTimeout: "10s"
## Default: "openid profile email"
#scopes: "openid profile email"
#icon: "google"
#color: "yellow"Using Microsoft Entra ID#
Example:
portals:
name: "default"
providers:
-
microsoftEntraID:
#name: "my-microsoft-entra-id-auth"
#displayName: "Microsoft Entra ID"
tenantID: ""
clientID: "your-client-id"
#clientSecret: "your-client-secret"
#clientSecretFile: "/var/run/secrets/traefik-forward-auth/microsoft-entra-id/client-secret"
#clientAssertion: ""
## Default: "10s"
#requestTimeout: "10s"
## Default: "openid profile email"
#scopes: "openid profile email"
#icon: "microsoft"
#color: "cyan"Using OpenID Connect#
Example:
portals:
name: "default"
providers:
-
openIDConnect:
#name: "my-openid-auth"
#displayName: "OpenID Connect"
clientID: "your-client-id"
clientSecret: "your-client-secret"
#clientSecretFile: "/var/run/secrets/traefik-forward-auth/openidconnect/client-secret"
tokenIssuer: "https://id.external-example.com"
#clientAssertion: ""
## Default: "10s"
#requestTimeout: "10s"
## Default: "openid profile email"
#scopes: "openid profile email"
## Default: false
#enablePKCE: false
## Default: false
#tlsInsecureSkipVerify: false
#tlsCACertificatePEM: ""
#tlsCACertificatePath: ""
#icon: "openid"
#color: "pink"Using Pocket ID#
Example:
portals:
name: "default"
providers:
-
pocketID:
#name: "my-pocketid-auth"
#displayName: "Pocket ID"
endpoint: "https://pocketidid.example.com"
clientID: "your-client-id"
clientSecret: "your-client-secret"
#clientSecretFile: "/var/run/secrets/traefik-forward-auth/pocketid/client-secret"
## Default: "10s"
#requestTimeout: "10s"
## Default: "openid profile email groups"
#scopes: "openid profile email groups"
## Default: false
#enablePKCE: false
#clientAssertion: ""
## Default: false
#tlsInsecureSkipVerify: false
#tlsCACertificatePEM: ""
#tlsCACertificatePath: ""
#icon: "pocketid"
#color: "zinc"Using Tailscale Whois#
Example:
portals:
name: "default"
providers:
-
tailscaleWhois:
#name: "my-tailscale-whois-auth"
#displayName: "Tailscale Whois"
#allowedTailnet: "yourtailnet.ts.net"
## Default: "10s"
#requestTimeout: "10s"
## Default: ["italypaleale.me/traefik-forward-auth"]
#capabilityNames: ["italypaleale.me/traefik-forward-auth"]
#icon: "tailscale"
#color: "slate"