Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Environment Variables

All Vouch server configuration is done via environment variables (prefixed with VOUCH_). These can also be passed as command-line arguments.

Core Configuration

VariableRequiredDefaultDescription
VOUCH_RP_IDYeslocalhostRelying Party ID (domain, e.g., vouch.sh). Used as the WebAuthn RP ID.
VOUCH_RP_NAMENoVouchRelying Party display name shown in browser prompts and UI.
VOUCH_DATABASE_URLYessqlite:vouch.db?mode=rwcDatabase connection URL. Supports sqlite:, postgres:, and Aurora DSQL endpoints.
VOUCH_JWT_SECRETConditional(empty)JWT signing secret. Must be at least 32 characters. Must not consist of a single repeated character. Used to sign internal state tokens. Required unless VOUCH_JWT_HMAC_KMS_KEY_ID is set.
VOUCH_BASE_URLNohttps://{rp_id}Base URL for this server. Auto-derived from VOUCH_RP_ID if not set (http://localhost:{port} for local dev, https://{rp_id} for production).
VOUCH_ORG_NAMENo(none)Organization name for branding in the UI. Falls back to VOUCH_RP_NAME if not set.
VOUCH_ALLOWED_DOMAINSNo(none)Comma-separated list of allowed email domains for enrollment (e.g., example.com,corp.example.com). If not set, all domains are allowed. Normalized to lowercase.

Network

VariableRequiredDefaultDescription
VOUCH_LISTEN_ADDRNo[::]:3000Address and port to listen on. Ignored when TLS is configured (server listens on 443 instead).

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.

VariableRequiredDefaultDescription
VOUCH_IDPSNo(none)Comma-separated list of IdP slugs in display order (e.g., google,entra,corp-saml).
VOUCH_IDP_<SLUG>_TYPEYes (per IdP)(none)oidc or saml.

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.

VariableRequiredDefaultDescription
VOUCH_IDP_<SLUG>_ISSUERYes(none)OIDC issuer URL (e.g., https://accounts.google.com). Must serve a valid OIDC discovery document.
VOUCH_IDP_<SLUG>_CLIENT_IDYes(none)OIDC client ID from the IdP.
VOUCH_IDP_<SLUG>_CLIENT_SECRETYes(none)OIDC client secret from the IdP.

SAML IdP (per slug)

VariableRequiredDefaultDescription
VOUCH_IDP_<SLUG>_METADATA_URLYes(none)URL to the SAML IdP metadata XML document. Fetched at server startup.
VOUCH_IDP_<SLUG>_SP_ENTITY_IDNo{VOUCH_BASE_URL}SP entity ID sent in authentication requests. Defaults to the server’s base URL.
VOUCH_IDP_<SLUG>_EMAIL_ATTRIBUTENo(auto-detect)SAML attribute name containing the user’s email address.
VOUCH_IDP_<SLUG>_DOMAIN_ATTRIBUTENo(none)SAML attribute name containing the user’s domain (for domain restriction).

Legacy variables (no longer read)

The previous flat single-IdP variables — VOUCH_OIDC_ISSUER, VOUCH_OIDC_CLIENT_ID, VOUCH_OIDC_CLIENT_SECRET, VOUCH_OIDC_PROVIDERS, VOUCH_SAML_IDP_METADATA_URL, VOUCH_SAML_SP_ENTITY_ID, VOUCH_SAML_EMAIL_ATTRIBUTE, VOUCH_SAML_DOMAIN_ATTRIBUTE — are silently ignored. Setting them configures nothing; only the unified VOUCH_IDPS / VOUCH_IDP_<SLUG>_* variables above are read. See IdP Overview for the field-by-field mapping.

Session

VariableRequiredDefaultDescription
VOUCH_SESSION_HOURSNo8Session duration in hours. After this time, the user must re-authenticate.
VOUCH_DEVICE_CODE_EXPIRESNo600Device code expiration in seconds. How long a device code remains valid during enrollment.
VOUCH_DEVICE_POLL_INTERVALNo5Device code polling interval in seconds. How frequently the CLI polls for device code completion.

SSH CA

VariableRequiredDefaultDescription
VOUCH_SSH_CA_KEYNo(none)SSH CA private key content (base64-encoded PEM format, Ed25519). If set, takes precedence over VOUCH_SSH_CA_KEY_PATH.
VOUCH_SSH_CA_KEY_PATHNo./ssh_ca_keyPath to SSH CA private key file (raw PEM, not base64). Set to empty string to disable SSH CA entirely.

OIDC Signing

VariableRequiredDefaultDescription
VOUCH_OIDC_SIGNING_KEYNo(auto-generate)OIDC signing key content (base64-encoded PEM format, P-256 ECDSA). Used for signing access tokens and ID tokens with ES256 algorithm. If not set, an ephemeral key is generated on each server restart (not recommended for production).
VOUCH_OIDC_RSA_SIGNING_KEYNo(auto-generate)OIDC RSA signing key content (base64-encoded PEM format, RSA-3072). Used for signing ID tokens with RS256 algorithm per OIDC Core Section 3.1.3.7. Minimum 3072-bit key enforced. If not set, an ephemeral key is generated on each server restart.

AWS KMS

VariableRequiredDefaultDescription
VOUCH_SSH_CA_KMS_KEY_IDNo(none)AWS KMS key ID for SSH CA signing (Ed25519). When set, overrides VOUCH_SSH_CA_KEY and VOUCH_SSH_CA_KEY_PATH.
VOUCH_OIDC_SIGNING_KMS_KEY_IDNo(none)AWS KMS key ID for OIDC token signing (P-256 ECDSA). When set, overrides VOUCH_OIDC_SIGNING_KEY.
VOUCH_OIDC_RSA_SIGNING_KMS_KEY_IDNo(none)AWS KMS key ID for OIDC RSA token signing (RSA-3072, RSASSA_PKCS1_V1_5_SHA_256). When set, overrides VOUCH_OIDC_RSA_SIGNING_KEY.
VOUCH_JWT_HMAC_KMS_KEY_IDNo(none)AWS KMS key ID for HMAC state token signing. When set, VOUCH_JWT_SECRET is not required.

DPoP

VariableRequiredDefaultDescription
VOUCH_DPOP_MAX_AGENo300Maximum age of DPoP proofs in seconds. Proofs older than this are rejected.

Cleanup & Retention

VariableRequiredDefaultDescription
VOUCH_CLEANUP_INTERVALNo15Background cleanup task interval in minutes. Set to 0 to disable automatic cleanup.
VOUCH_AUTH_EVENTS_RETENTION_DAYSNo90Retention period for authentication events in days. Events older than this are purged during cleanup.
VOUCH_OAUTH_EVENTS_RETENTION_DAYSNo90Retention period for OAuth usage events in days. Events older than this are purged during cleanup.

CORS

VariableRequiredDefaultDescription
VOUCH_CORS_ORIGINSNo(none)Comma-separated list of CORS allowed origins. Empty means same-origin only. Use * to allow all origins (not recommended for production).

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.

VariableRequiredDefaultDescription
VOUCH_GITHUB_APP_IDNo(none)GitHub App ID (numeric, assigned when creating the app on github.com).
VOUCH_GITHUB_APP_NAMENo(none)GitHub App name (the slug from github.com/apps/{name}).
VOUCH_GITHUB_APP_KEYNo(none)GitHub App private key (PEM format, RSA). Can use literal \n for newlines.
VOUCH_GITHUB_WEBHOOK_SECRETNo(none)GitHub webhook secret for verifying webhook signatures (HMAC-SHA256).
VOUCH_GITHUB_APP_CLIENT_IDNo(none)GitHub App Client ID for OAuth user authentication. Found in GitHub App settings (different from the numeric App ID).
VOUCH_GITHUB_APP_CLIENT_SECRETNo(none)GitHub App Client Secret for OAuth user authentication.

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.

VariableRequiredDefaultDescription
VOUCH_TLS_CERTNo(none)TLS certificate (base64-encoded PEM).
VOUCH_TLS_KEYNo(none)TLS private key (base64-encoded PEM). Required if VOUCH_TLS_CERT is set.

S3 Configuration

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

VariableRequiredDefaultDescription
VOUCH_S3_CONFIG_BUCKETNo(none)S3 bucket name for configuration file. If set, config is loaded from S3.
VOUCH_S3_CONFIG_KEYNoconfig/vouch-server.jsonS3 object key for configuration file.
VOUCH_S3_CONFIG_REGIONNo(auto)AWS region for S3 access. Uses the default credential chain region if not set.
VOUCH_S3_CONFIG_POLL_INTERVALNo60S3 config polling interval in seconds. How frequently the server checks for configuration changes.

JWT Assertion

VariableRequiredDefaultDescription
VOUCH_JWT_ASSERTION_MAX_LIFETIMENo300Maximum lifetime (seconds) for private_key_jwt client-authentication JWT assertions (RFC 7523 §2.2 / §3). Assertions older than this are rejected.

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.

VariableRequiredDefaultDescription
VOUCH_RESOURCE_NAMENoVouchHuman-readable name of this protected resource.
VOUCH_RESOURCE_DOCUMENTATIONNohttps://vouch.sh/docs/URL of developer documentation for this protected resource.
VOUCH_RESOURCE_POLICY_URINohttps://vouch.sh/privacy/URL of the resource’s data-use policy.
VOUCH_RESOURCE_TOS_URINohttps://vouch.sh/terms/URL of the resource’s terms of service.

CLI Download URLs

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

VariableRequiredDefaultDescription
VOUCH_CLI_DOWNLOAD_MACOSNo(none)CLI download URL for macOS, displayed in the server UI.
VOUCH_CLI_DOWNLOAD_LINUXNo(none)CLI download URL for Linux, displayed in the server UI.
VOUCH_CLI_DOWNLOAD_WINDOWSNo(none)CLI download URL for Windows, displayed in the server UI.