Generic trusted-header integration

Use this pattern only when the backend explicitly supports identity supplied by a trusted reverse proxy. PassBeyond authenticates the request; the backend consumes the resulting subject and attributes.

1. Select the subject

PassBeyond selects the first non-empty value from:

1. email;
2. sAMAccountName;
3. SAML NameID.

Configure the IdP so the selected value is unique, stable, and suitable as an application login. Do not rely on transient NameID when the backend needs a durable account key.

The primary header is:

X-Passbeyond-User: alice@example.com

Use REMOTE_USER, X-REMOTE-USER, or X-Forwarded-User only when the application requires that compatibility name.

2. Choose attributes

Example mapped values:

X-Passbeyond-Data-Email: alice@example.com
X-Passbeyond-Data-Givenname: Alice
X-Passbeyond-Data-Surname: Example
X-Passbeyond-Data-Department: Engineering
X-Passbeyond-Data-Groups: app-users,report-readers

Send only required attributes from the IdP. Every value is copied into the browser JWT and later into a backend header.

3. Isolate the backend

Bind the backend to loopback, a Unix socket where supported, or a private network reachable only by PassBeyond. If the application has a trusted-proxy allowlist, add only the PassBeyond source IP or narrow subnet.

Do not use the end user's IP as the header-auth trust decision. The trusted party is PassBeyond, while the resolved user IP is supplied separately in X-Forwarded-For and X-Real-IP.

4. Configure user provisioning

Choose deliberately:

• pre-provisioned users only;
• automatic creation on first trusted request;
• attribute refresh at every request or login;
• group synchronization behavior;
• deactivation and removal behavior.

PassBeyond attributes are a session snapshot. Removing a user or group at the IdP does not update an existing JWT until it expires.

Avoid treating every received group as an application role. Map or allowlist groups with an application-specific prefix.

5. Define failure behavior

The backend must fail closed when:

• the user header is missing or empty;
• a required email or group value is absent;
• the request does not come from PassBeyond;
• an unknown user is received and automatic creation is disabled.

Do not fall back from missing trusted headers to a public anonymous administrator or another privileged account.

6. Test spoofing resistance

From the public side, send forged values:

curl --include \
  -H 'X-Passbeyond-User: administrator' \
  -H 'REMOTE_USER: administrator' \
  https://myapp.example.com/

The request should still require SAML. After authentication, the backend must receive only the real PassBeyond-generated identity.

Also confirm that a direct backend request is blocked at the network layer rather than merely missing a header.

7. Test lifecycle behavior

Test:

1. first login and optional user creation;
2. existing user login;
3. user without required group;
4. group removal after the PassBeyond JWT expires;
5. PassBeyond logout while the application has its own session;
6. application logout while the PassBeyond cookie remains valid;
7. expired PassBeyond session;
8. backend restart or unavailable target.

Document whether the application creates a second session. If so, /saml/slo clears PassBeyond but may not revoke the backend session cookie.

Header reference

See Forwarded headers for removal rules, Basic authorization, client IP handling, and all standard values. See Supported claims for IdP attribute aliases.