Sessions

PassBeyond uses a short-lived SAML flow session while authentication is in progress and a signed JWT cookie for subsequent application requests.

Session creation

After the IdP posts a valid SAML response to /saml/acs, PassBeyond maps supported attributes and chooses the authenticated subject in this order:

1. mapped email address;
2. mapped sAMAccountName;
3. the SAML session subject (NameID).

An empty subject is rejected. PassBeyond then creates an HS256-signed JWT with:

Claim	Meaning
sub	Authenticated user identifier
iss	Fixed issuer passbeyond
iat	Issue time
nbf	Not-before time, backdated by five seconds
exp	Expiration based on sessionTimeout
data	Mapped SAML attributes and groups

The JWT is stored in __passbeyond_session with Secure, HttpOnly, SameSite=Lax, domain-wide, and root-path cookie attributes. Its cookie expiry is five minutes later than the JWT expiry; the signed exp claim remains authoritative.

All mapped attributes and group values are embedded in the JWT. Large group memberships therefore create a large cookie on every browser request and large identity headers on the backend request. Browsers and reverse proxies commonly impose lower header limits than PassBeyond's own 1 MiB server limit, so map only data the application needs and test representative high-membership users. See Runtime limits.

Request validation

On every protected request, PassBeyond verifies:

• the JWT signature with the instance's generated secret;
• the expected HS256 algorithm;
• the nbf and exp times;
• the fixed passbeyond issuer.

Invalid or absent sessions restart the SAML login flow. Valid claims are converted to backend headers. The session cookie itself is removed before the request is proxied, so it is not disclosed to the backend.

Attribute snapshot

The JWT contains an attribute snapshot taken at sign-in. PassBeyond does not query the IdP again during the session. Group, profile, or account-status changes therefore become effective only after the current JWT expires and the user authenticates again.

Choose sessionTimeout with this delay in mind. The default is 1,440 minutes (24 hours).

Logout

/saml/slo expires the PassBeyond JWT cookie and clears the SAML flow session. When the IdP advertises Single Logout, PassBeyond sends a logout request using Redirect binding or falls back to POST binding. If the IdP has no SLO endpoint, logout remains local.

Because application sessions are self-contained JWTs, PassBeyond has no server-side session record to revoke. Clearing one browser's cookie does not invalidate a copied JWT elsewhere; only expiry or rotation of the instance JWT secret does that.

Key rotation

The JWT secret is stored in the dynamic JSON file. Replacing or deleting that state causes a new secret to be generated and invalidates every existing PassBeyond session for the instance.

The same file also contains the SAML key pair. A full state rotation therefore changes the certificate exposed to the IdP. Plan the IdP update before using deletion as an incident-response action and follow the Certificate rotation runbook.

Passthrough requests

Configured paths and tokens can bypass session validation. They are intended for explicitly public resources or non-browser clients, not as an alternative user session mechanism. Review Configuration and the security model before enabling them.