Configuration

PassBeyond accepts a YAML file or a complete set of environment variables. YAML is recommended for systemd installations because it keeps every instance explicit and easy to audit.

Configuration loading

At startup, PassBeyond first tries environment configuration. Environment configuration is accepted only when PASSBEYOND_DOMAIN, a metadata source, and PASSBEYOND_PROXY_TARGET_URL are present. If that set is incomplete, PassBeyond loads YAML instead.

The YAML path is selected in this order:

1. the argument --config /path/to/instance.yaml;
2. PASSBEYOND_CONFIG;
3. ./config.yaml in the working directory.

No per-setting merge

Environment values are not overlaid onto YAML. PassBeyond either uses the environment configuration as a whole or falls back to the YAML file as a whole. PASSBEYOND_CONFIG is the exception: it selects the YAML path.

Static configuration is evaluated at process startup. Restart the instance after changing YAML or environment values; PassBeyond does not hot-reload them.

Complete YAML example

domain: "myapp.example.com"

# Configure exactly one IdP metadata source.
idpMetadataURL: "https://sso.example.com/path/to/metadata.xml"
# idpMetadataFile: "/etc/passbeyond/idp-metadata.xml"

# Generated keys, secrets, instance ID, and cached IdP metadata.
configPath: "/var/lib/passbeyond/myapp.json"

proxy:
  listenAddress: "127.0.0.1:8123"
  targetURL: "http://127.0.0.1:8888"
  targetDisableSSLVerify: false
  stripVersionHeaders: true
  useBasicAuth: false
  ignoreAuthorizationHeader: false
  trustedProxies:
    - "127.0.0.1"
    - "::1"

sessionTimeout: 1440
samlRequestSigning: false

supportURL: "https://support.example.com/"
footer: "Example Company — Identity Support"

passthroughPaths:
  - "/public/"
  - "/static/"

passthroughTokens:
  - "replace-with-a-long-random-token"

See the configuration reference for types, defaults, and environment variable names.

IdP metadata

Choose exactly one of these modes.

Remote metadata

Set idpMetadataURL. PassBeyond fetches the metadata during startup with a 30-second request timeout, limits the response to 10 MiB, caches a successful response in the dynamic configuration, and refreshes it every 30 minutes.

If a later refresh fails, the currently loaded metadata remains active. During startup, valid cached metadata is used when the remote endpoint cannot be refreshed.

Local metadata

Set idpMetadataFile to a readable XML file. The local file takes precedence when both options are present. It is loaded only at startup and is not refreshed automatically; restart the instance after replacing it.

Dynamic configuration

configPath is a JSON file managed by PassBeyond. On first start it receives:

• a unique instance ID;
• a randomly generated JWT signing secret;
• a self-signed RSA key and certificate for SAML signing and encryption scenarios;
• cached IdP metadata when URL mode is used.

Do not edit this file while PassBeyond is running. Give each instance its own file, make it writable only by the service account, and include it in encrypted backups. Deleting it rotates the session and SAML material, invalidates existing sessions, and requires updating IdPs that use the previous certificate.

Use the Backup and restore and Certificate rotation runbooks instead of manipulating live state ad hoc.

Session lifetime

sessionTimeout is measured in minutes and defaults to 1440 (24 hours). A shorter timeout reduces the period during which stale group membership or a disabled IdP account can remain effective. It also makes users authenticate more frequently.

The browser cookie expires five minutes after the JWT itself. The JWT expiry is authoritative.

Passthrough access

Passthrough rules deliberately skip SAML authentication.

Paths

Every entry in passthroughPaths is a path prefix. /public therefore also matches /publications. Include a trailing slash when you intend to expose a subtree only, and test adjacent paths.

Root (/), an empty value, and values without a leading slash are rejected. The public and internal PassBeyond endpoints remain separately reserved.

Tokens

Clients can supply a configured token as:

X-Passbeyond-Authorization: Bearer <token>

Treat passthrough tokens like passwords: generate high-entropy values, send them only over TLS, store them in a secret manager, rotate them, and scope network access to the callers that need them. A valid token bypasses user authentication for any request handled by that instance.

Error page customization

supportURL adds a support link to friendly error pages. footer adds organization-specific footer content. Do not put secrets or operational internals in either value because error pages are shown to end users.