Security model

PassBeyond establishes an authentication boundary in front of one HTTP application. It verifies SAML assertions and its own signed session tokens, then supplies identity information to a backend that is reachable only through PassBeyond.

It does not replace backend authorization, edge TLS, network isolation, or IdP security.

Trust boundaries

PassBeyond assumes that:

• the configured IdP metadata belongs to the intended, trusted IdP;
• the IdP authenticates users and signs assertions securely;
• the public reverse proxy terminates TLS correctly;
• only configured proxies can connect in a way that influences client IP data;
• the backend accepts identity headers only from PassBeyond;
• static and dynamic configuration files are protected from unauthorized access;
• system clocks are synchronized.

Breaking any of these assumptions can invalidate the authentication boundary.

SAML validation

The Service Provider publishes fixed HTTPS endpoints derived from domain and uses the configured IdP metadata to validate the SAML exchange. Authentication requests can optionally be signed with samlRequestSigning.

The SAML key pair is generated on first start and stored in dynamic configuration. The public certificate is published at /saml/certificate.crt for signing and optional assertion-encryption scenarios.

Session integrity

Application sessions are HS256-signed JWTs. PassBeyond validates their algorithm, signature, issuer, not-before time, and expiry on each protected request. The signing secret is generated randomly per instance and stored only in dynamic state.

JWT confidentiality is not provided: the payload is encoded, not encrypted. Do not map unnecessary sensitive attributes into SAML assertions.

Header spoofing protection

Before proxying a request, PassBeyond removes incoming values that could impersonate an authenticated user:

• REMOTE_USER, Remote-User, X-REMOTE-USER, and X-Forwarded-User;
• every X-Passbeyond-* header;
• incoming Basic Authorization by default.

It then adds identity headers derived from a validated session. It also replaces X-Forwarded-For and X-Real-IP with the resolved client address and removes its session cookie before contacting the backend.

Bearer Authorization is preserved for application APIs. If ignoreAuthorizationHeader is enabled, incoming Basic authorization is preserved as well; enable that compatibility option only when the backend is intended to authenticate those credentials independently.

Network requirements

The safe topology has only one public entry point:

Public HTTPS proxy → private PassBeyond listener → private backend

If clients can connect directly to the backend, they can set the same identity headers PassBeyond would set. If clients can reach PassBeyond without the expected edge proxy, TLS and client-address assumptions can fail.

List only real proxy addresses or narrow CIDR ranges in trustedProxies. An empty list means client-supplied X-Forwarded-For is ignored.

Secret storage

The dynamic configuration contains the JWT signing secret and SAML private key. Protect it as a credential:

• make it readable and writable only by the service account;
• give every instance a different file;
• keep encrypted, access-controlled backups;
• never commit it or copy it into diagnostics;
• rotate it after suspected disclosure and update the IdP certificate where required.

Static YAML can also contain passthrough tokens and should receive the same treatment when those are configured.

Authentication bypasses

passthroughPaths and passthroughTokens intentionally skip SAML authentication. They reduce the guarantees described on this page.

Use path bypasses only for content that is genuinely public. Prefix matching is literal, so review neighboring paths. Use token bypasses only for controlled automation, with high-entropy secrets, TLS, network restrictions, monitoring, and rotation.

Backend authorization

PassBeyond answers “who authenticated?” and passes an attribute snapshot. The backend must answer “what may this user do?” Do not grant access merely because any identity header is non-empty; define authorization rules for users and groups and decide how missing attributes are handled.

Continue with the threat model and known limitations.