All configuration options
Root configuration object#
| Name | Type | Description | |
|---|---|---|---|
server.hostname | string | The hostname the application is reached at. This is used for setting the “redirect_uri” field for OAuth2 callbacks. | Required |
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.domain | string | Domain name for setting cookies. If empty, this is set to the value of the hostname property.This value must either be the same as the hostname property, or the hostname must be a sub-domain of the cookie domain name. | Recommended |
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 cookies.domain and server.basePath 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. | |
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"