---
title: "Authentication settings"
summary: "Settings for how people sign in and how long their sessions last."
description: "Sign-in mode, session lifetimes, and the OIDC provider configuration."
status: preview
generated: true
read_when:
  - "You are moving an instance from local sign-in to an identity provider."
  - "You need to map provider groups onto Pitot roles."
---

Every setting below is read once at startup and requires a restart to change.
Built-in defaults are overridden by nonempty environment values.
For the first Pitot alpha, unset `PITOT_` variables accept `FANOUT_` equivalents with a names-only deprecation warning. Explicitly empty primary variables block fallback.
Unknown `PITOT_` names fail startup; platform-injected service names are tolerated.
Vendor credentials and endpoints keep the vendor's documented names.

| Environment variable | Type | Default |
|---|---|---|
| `PITOT_AUTH_CODE_SECRET` or `PITOT_AUTH_CODE_SECRET_FILE` | string · secret | — |
| `PITOT_AUTH_MODE` | string | `local` |
| `PITOT_OIDC_ADMIN_GROUPS` | string | — |
| `PITOT_OIDC_ALLOWED_DOMAINS` | string | — |
| `PITOT_OIDC_ALLOWED_GROUPS` | string | — |
| `PITOT_OIDC_AUTO_PROVISION` | boolean | `false` |
| `PITOT_OIDC_CLIENT_ID` | string | — |
| `PITOT_OIDC_CLIENT_SECRET` or `PITOT_OIDC_CLIENT_SECRET_FILE` | string · secret | — |
| `PITOT_OIDC_DEFAULT_ROLE` | string | `viewer` |
| `PITOT_OIDC_EMAIL_CLAIM` | string | `email` |
| `PITOT_OIDC_EMAIL_VERIFICATION` | string | `required` |
| `PITOT_OIDC_ISSUER_URL` | string | — |
| `PITOT_OIDC_OPERATOR_GROUPS` | string | — |
| `PITOT_SCIM_TOKEN` or `PITOT_SCIM_TOKEN_FILE` | string · secret | — |
| `PITOT_SELF_SIGNUP` | boolean | `false` |
| `PITOT_SESSION_ABSOLUTE_TTL` | duration | `168h` |
| `PITOT_SESSION_IDLE_TTL` | duration | `12h` |

## Notes

### `PITOT_AUTH_CODE_SECRET`

Signs sign-in codes and login links; needs at least 32 characters in local mode and to issue or redeem OIDC break-glass links.

### `PITOT_AUTH_MODE`

Selects local sign-in or oidc; each mode validates its prerequisites.

### `PITOT_OIDC_ADMIN_GROUPS`

Lists identity-provider groups mapped to admin, separated by commas.

### `PITOT_OIDC_ALLOWED_DOMAINS`

Lists allowed email domains, separated by commas; wildcard * requires verified email.

### `PITOT_OIDC_ALLOWED_GROUPS`

Lists allowed identity-provider groups, separated by commas.

### `PITOT_OIDC_AUTO_PROVISION`

Creates accounts on OIDC sign-in; requires an allowed group or domain.

### `PITOT_OIDC_CLIENT_ID`

Identifies Pitot's client registration; required in OIDC mode.

### `PITOT_OIDC_CLIENT_SECRET`

Authenticates Pitot's client registration; required in OIDC mode.

### `PITOT_OIDC_DEFAULT_ROLE`

Assigns viewer, operator, or admin to users without a group role mapping.

### `PITOT_OIDC_EMAIL_CLAIM`

Names the claim containing the user's email address.

### `PITOT_OIDC_EMAIL_VERIFICATION`

Selects required verified-email claims or issuer trust; issuer trust requires an allowlist.

### `PITOT_OIDC_ISSUER_URL`

Selects the identity provider issuer; required in OIDC mode. Pitot starts while it is unreachable and retries discovery; a mismatched issuer fails startup.

### `PITOT_OIDC_OPERATOR_GROUPS`

Lists identity-provider groups mapped to operator, separated by commas.

### `PITOT_SCIM_TOKEN`

Enables SCIM 2.0 user provisioning under /scim/v2 and turns off browser setup; requires OIDC mode and at least 32 characters.

### `PITOT_SELF_SIGNUP`

Allows verified email addresses to create viewer accounts; requires local auth and SMTP.

### `PITOT_SESSION_ABSOLUTE_TTL`

Limits total session lifetime; it must be at least PITOT_SESSION_IDLE_TTL.

### `PITOT_SESSION_IDLE_TTL`

Expires inactive sessions; use a Go duration of at least 5m.

> **Secrets**
>
> Settings marked `secret` are redacted from Pitot's startup configuration
> log. Supply either the value or its `_FILE` path, never both. File contents
> lose exactly one trailing newline (LF or CRLF); empty secrets fail startup.