Environment Variables

Every server setting listed here is available three ways: as a VOUCH_-prefixed environment variable, as an equivalent --kebab-case command-line flag, and as a field in the S3 configuration document. An explicit flag beats the environment variable; S3 configuration beats both. See Configuration Sources.

An empty value is the same as no value for every setting whose default is (none): VOUCH_X="", --x=, and "x": "" in the S3 document all leave the setting unset. An empty key therefore makes the server generate one (with the startup warning that says so) rather than load an empty key, an empty secret leaves its feature off, and an empty S3 value does not override the environment.

A few variables the server reads are not VOUCH_-prefixed — RUST_LOG, the OTEL_* and AWS_* families, and DSQL_USER. They are listed in their relevant sections below.

Core Configuration

Network

Upstream Identity Provider

Configure one or more upstream IdPs (OIDC, SAML, or any mix) as a single unified list. VOUCH_IDPS holds a comma-separated list of slugs; each slug picks up its VOUCH_IDP_<SLUG>_* variables. Slugs match [a-z0-9-]{1,32} (no leading or trailing hyphen) and must be unique.

Hyphens in slugs become underscores in variable names: a slug of corp-saml becomes VOUCH_IDP_CORP_SAML_*.

OIDC IdP (per slug)

OIDC IdPs auto-discover authorization, token, and JWKS endpoints from {issuer}/.well-known/openid-configuration at startup.

SAML IdP (per slug)

Session

SSH CA

Warning: because a missing VOUCH_SSH_CA_KEY_PATH file causes the server to generate a new CA key, starting on a fresh or unmounted volume silently rotates your SSH CA. Every host’s TrustedUserCAKeys entry then stops matching and users cannot log in with newly issued certificates. Either provision the key file before first start, or supply the key through VOUCH_SSH_CA_KEY / VOUCH_SSH_CA_KMS_KEY_ID, which never auto-generate.

OIDC Signing

AWS KMS

DPoP

Cleanup & Retention

CORS

GitHub App

These variables configure the Vouch GitHub App integration for issuing GitHub tokens. The App ID, name, and key are required together for GitHub App functionality. OAuth client ID and secret are additionally needed for GitHub user authentication.

An org admin links an installation from /github/connect only after linking their own GitHub account there. Vouch links an installation only when it appears in that account’s GET /user/installations list, so an admin cannot link an installation their GitHub account cannot see. Without the client ID and secret, admins cannot link GitHub accounts, so /github/connect shows “Not Available” and the server logs a warning at startup.

TLS

When both VOUCH_TLS_CERT and VOUCH_TLS_KEY are set, the server listens on port 443 (HTTPS) with an automatic HTTP-to-HTTPS redirect on port 80. The VOUCH_LISTEN_ADDR setting is ignored when TLS is configured.

S3 Configuration

Vouch supports loading configuration from an S3 object for centralized management. S3 configuration values override environment variables.

JWT Assertion

The signing algorithm allowed for a client’s assertion depends on its FAPI 2.0 profile, not just this lifetime bound. Applications with fapi_profile = fapi2_security may only sign assertions with ES256, PS256, or EdDSA (FAPI 2.0 Section 5.4.1); other applications may additionally use RS256. That includes standard-profile applications created in the console with private key authentication (token_endpoint_auth_method = private_key_jwt without the FAPI profile), whose access tokens stay bearer tokens. Discovery’s token_endpoint_auth_signing_alg_values_supported advertises the full four-algorithm union — an application’s own profile determines which of those it may actually use. Setting fapi_profile = fapi2_security on an application whose JWKS keys are all pinned to an algorithm outside that set (e.g. every key declares "alg": "RS256") is refused with a fapi_jwks_algorithm_unsupported error, since the application would otherwise be unable to authenticate at all after the change.

Protected Resource Metadata (RFC 9728)

These optional variables configure descriptive metadata published in the OAuth 2.0 Protected Resource Metadata document at /.well-known/oauth-protected-resource.

Override the last three on a self-hosted deployment. Their defaults point at Vouch’s own site, so a deployment that leaves them alone publishes Vouch’s documentation, privacy policy, and terms as its own in a document clients read to learn who operates the resource. Point them at your organization’s pages.

The same applies to the /privacy and /terms UI routes, which are fixed redirects to vouch.sh. Override those at your reverse proxy if you need your own.

Vulnerability Disclosure (RFC 9116)

The server publishes a security.txt document at /.well-known/security.txt with Contact, Expires (rolling, 30 days ahead), and Canonical (built from the base URL) fields.

CLI Download URLs

These optional variables configure download links displayed in the server UI.

Database Tuning

Authenticator Policy

Regardless of these settings, software authenticators are always rejected: the none attestation format is refused, so only hardware-backed credentials can enroll. See Security Hardening.

Observability

See Monitoring and Metrics.

AWS Environment

These are read by the AWS SDK or by Vouch’s AWS-specific resolution logic. None are VOUCH_-prefixed.

On EC2, AWS_REGION, AWS_AZ, and AWS_PARTITION fall back to IMDS (placement/region, placement/availability-zone, services/partition) when unset — see EC2 instance bootstrap below. AWS_PARTITION has no IMDS equivalent on older instance generations (services/partition 404s), in which case cross-account KMS ARN construction is skipped.

EC2 Instance Bootstrap

On EC2, vouch-server performs its own bootstrap at startup before building ServerConfig: it reads the region, availability zone, and partition from IMDSv2, then fetches a KEY=VALUE configuration blob from AWS Systems Manager Parameter Store (ssm:GetParameter with decryption) and applies it as a config layer strictly below CLI flags and process environment variables — an explicit --flag or a real env var always wins over the parameter; only variables the operator hasn’t already set are filled in.

• Parameter name. Read from the VouchConfigParameter EC2 instance tag (requires the instance to have been launched with --metadata-options 'InstanceMetadataTags=enabled'). The tag is the opt-in: when it is not visible, the SSM fetch is skipped and the server keeps only the IMDS-derived instance facts, starting from CLI flags and process environment.
• Format. Strict KEY=VALUE lines, one per line, with # comments and blank lines allowed — the same format systemd’s EnvironmentFile= accepts. No export prefix, no CRLF line endings, no quoted values; any of these is a hard startup error rather than a silent misparse.
• Scope. Only variables backed by a vouch-server CLI flag (every VOUCH_* variable in this reference, plus AWS_REGION/AWS_AZ/AWS_PARTITION/ AWS_USE_FIPS_ENDPOINT) are read from the parameter. Anything else in the blob (for example a stray RUST_LOG) is ignored, since it was never real process environment to begin with. In particular, use AWS_REGION — not AWS_DEFAULT_REGION — in the parameter: the alias is honored only as a real environment variable, and inside the blob it is ignored in favor of the IMDS-derived region.
• Never running on EC2 (IMDS unreachable), or AWS_EC2_METADATA_DISABLED=true. Bootstrap is skipped entirely and the server starts from CLI flags and process environment only, same as a non-EC2 deployment.
• On EC2 but the SSM call fails. This is treated as a startup failure (never a silent fallback to an unconfigured server) — the log records a VOUCH_BOOTSTRAP_FAILED line naming the parameter and region. The unit’s Restart=always retries transient failures (e.g. SSM throttling); a persistent failure means the instance never becomes healthy, which an Auto Scaling Group replaces.
• Already configured via env/CLI. If the S3 config bucket is already set (the VOUCH_S3_CONFIG_BUCKET variable or the --s3-config-bucket flag), the IMDS probe is skipped entirely, so non-EC2 and fully env-configured deployments pay nothing.

Test Mode

Startup Validation

The server refuses to start when any of the following holds. Each produces a message naming the offending variable.

A JWT secret with fewer than 8 distinct bytes produces a warning, not an error.

See Troubleshooting for what to do about each.

Localization

The server negotiates the response language per request from the Accept-Language header and the OIDC ui_locales parameter. There is no server-side environment variable for it, and no configuration is required.

The vouch CLI resolves its own language separately, from --lang, VOUCH_LANG, and the standard POSIX locale variables. That is client-side; see vouch.sh/docs.