Configuration reference

PassBeyond uses either a complete environment configuration or one YAML file. It does not merge individual environment values into YAML. See the configuration guide for loading precedence.

File selection

Input	Purpose
--config <path>	Select a YAML configuration file
PASSBEYOND_CONFIG	Select a YAML file when --config is absent
./config.yaml	Default YAML path

Core settings

YAML	Environment	Type	Required / default	Description
domain	PASSBEYOND_DOMAIN	string	Required	Public hostname without a scheme or path, for example host.example.com. Used for HTTPS SAML URLs, redirects, and cookie scope.
idpMetadataURL	PASSBEYOND_IDP_METADATA_URL	string	One metadata source required	Remote IdP metadata. Cached and refreshed every 30 minutes.
idpMetadataFile	PASSBEYOND_IDP_METADATA_FILE	string	One metadata source required	Local IdP metadata XML. Takes precedence over URL mode and is loaded at startup only.
configPath	PASSBEYOND_CONFIG_PATH	string	./dynamic_config.json	Writable dynamic JSON containing generated secrets, keys, instance ID, and remote metadata cache.
sessionTimeout	PASSBEYOND_SESSION_TIMEOUT	integer	1440	Application JWT lifetime in minutes. Must be greater than zero for session creation.
samlRequestSigning	PASSBEYOND_SAML_REQUEST_SIGNING	boolean	false	Sign SAML authentication requests with the generated instance key.
supportURL	PASSBEYOND_SUPPORT_URL	string	Empty	Support link shown on friendly error pages.
footer	PASSBEYOND_FOOTER	string	Empty	Custom footer content on friendly error pages.

When both metadata fields appear in YAML, idpMetadataFile wins. Environment mode selects the URL first when both environment variables are present.

Proxy settings

Proxy settings are nested under proxy in YAML.

YAML	Environment	Type	Required / default	Description
proxy.listenAddress	PASSBEYOND_PROXY_LISTEN_ADDRESS	string	Empty; set explicitly	Address and port for PassBeyond, for example 127.0.0.1:8123 or :8123.
proxy.targetURL	PASSBEYOND_PROXY_TARGET_URL	URL	Required	Backend origin to which accepted requests are proxied.
proxy.targetDisableSSLVerify	PASSBEYOND_PROXY_TARGET_DISABLE_SSL_VERIFY	boolean	false	Disable certificate verification for an HTTPS target. Unsafe for production.
proxy.stripVersionHeaders	PASSBEYOND_PROXY_STRIP_VERSION_HEADERS	boolean	false	Remove common backend version headers from responses.
proxy.useBasicAuth	PASSBEYOND_PROXY_USE_BASIC_AUTH	boolean	false	Send Authorization: Basic <user:> to the backend using the authenticated subject and an empty password.
proxy.ignoreAuthorizationHeader	—	boolean	false	Preserve incoming Basic authorization instead of removing it. YAML only. Bearer authorization is preserved independently.
proxy.trustedProxies	PASSBEYOND_PROXY_TRUSTED_PROXIES	string list	Empty	IP addresses or CIDR ranges allowed to supply X-Forwarded-For. Environment values are comma-separated.

When stripVersionHeaders is enabled, PassBeyond removes X-Powered-By, Server, X-AspNet-Version, X-AspNetMvc-Version, and X-SourceFiles from backend responses.

Authorization compatibility options

useBasicAuth creates a trusted Basic header from the PassBeyond subject. ignoreAuthorizationHeader preserves a client-provided Basic header. These are different behaviors; do not enable the latter unless the backend is explicitly meant to authenticate it.

Passthrough settings

YAML	Environment	Type	Default	Description
passthroughPaths	PASSBEYOND_PASSTHROUGH_PATHS	string list	Empty	Literal path prefixes that bypass SAML. Environment values are comma-separated.
passthroughTokens	PASSBEYOND_PASSTHROUGH_TOKENS	string list	Empty	Bearer tokens accepted through X-Passbeyond-Authorization. Environment values are comma-separated.

Path values must start with / and contain at least one additional character. Root and empty values are rejected. A configured token applies to the whole instance, not to one path.

Environment example

PASSBEYOND_DOMAIN="myapp.example.com"
PASSBEYOND_IDP_METADATA_URL="https://sso.example.com/metadata.xml"
PASSBEYOND_CONFIG_PATH="/var/lib/passbeyond/myapp.json"

PASSBEYOND_PROXY_LISTEN_ADDRESS="127.0.0.1:8123"
PASSBEYOND_PROXY_TARGET_URL="http://127.0.0.1:8888"
PASSBEYOND_PROXY_TARGET_DISABLE_SSL_VERIFY="false"
PASSBEYOND_PROXY_STRIP_VERSION_HEADERS="true"
PASSBEYOND_PROXY_USE_BASIC_AUTH="false"
PASSBEYOND_PROXY_TRUSTED_PROXIES="127.0.0.1,::1"

PASSBEYOND_SESSION_TIMEOUT="1440"
PASSBEYOND_SAML_REQUEST_SIGNING="false"
PASSBEYOND_SUPPORT_URL="https://support.example.com/"
PASSBEYOND_FOOTER="Example Company — Identity Support"

PASSBEYOND_PASSTHROUGH_PATHS="/public/,/static/"
PASSBEYOND_PASSTHROUGH_TOKENS="first-secret,second-secret"

Boolean environment values are enabled only by the literal lowercase value true; all other non-empty values are treated as false.