Application integrations

PassBeyond can protect almost any browser-based HTTP application, but “works behind PassBeyond” does not always mean “automatically logs the user into the application.” Choose the integration model the backend actually supports.

Integration models

Model	Result	Best fit
Outer authentication gate	SAML is required before the application's own login page	Applications without a trusted-header login mode
Trusted-header login	Backend creates or selects a user from X-Passbeyond-* or REMOTE_USER	Auth-proxy and remote-user capable applications
Basic-auth compatibility	PassBeyond sends the subject with an empty password	Applications explicitly designed for proxy-generated Basic auth
Passthrough	Selected traffic skips SAML	Public assets or tightly controlled non-browser automation

The outer gate is the safest default because it does not require the application to trust a new identity mechanism. It adds authentication but does not replace the application's own login.

Before configuring the backend

1. Prevent every direct client path to the backend.
2. Decide which PassBeyond subject is stable: preferably email or sAMAccountName.
3. Map only attributes the application needs.
4. Determine whether the application auto-creates users or requires pre-provisioning.
5. Define authorization and group behavior for missing or stale claims.
6. Test logout from both PassBeyond and the application.

Header authentication requires network isolation

An application that accepts X-Passbeyond-User from any source allows identity spoofing. Restrict the backend listener or trusted-proxy list to PassBeyond itself.

Outer authentication gate

No backend authentication changes are required. Set proxy.targetURL to the application's private origin and keep its existing login enabled.

This model:

• blocks unauthenticated public access before the application
• can add an additional IdP policy or MFA gate
• still presents the application's own login afterward
• does not synchronize PassBeyond logout with the application's session;
• does not automatically use PassBeyond groups for application authorization.

It is appropriate when the application has no supported auth-proxy mode or when changing its identity model is too risky.

Trusted-header login

Use an application-supported auth-proxy, remote-user, or trusted-header feature. Common inputs are:

Purpose	Header
Stable login	X-Passbeyond-User
Compatibility login	REMOTE_USER or X-Forwarded-User
Email	X-Passbeyond-Data-Email
Display or common name	X-Passbeyond-Data-Commonname
Groups	X-Passbeyond-Data-Groups

Header names are case-insensitive, but application configuration may display a canonicalized spelling. Groups arrive as one comma-separated value.

Configure the application to trust only the PassBeyond source address. Decide whether new users may be auto-created and whether group synchronization removes old memberships.

See Generic trusted-header integration for a complete checklist.

Basic-auth compatibility

With:

proxy:
  useBasicAuth: true

PassBeyond sends:

Authorization: Basic <base64(subject + ":")>

The password is empty. This is useful only when the backend deliberately trusts proxy-generated Basic credentials. It will not bypass a form login or an application that verifies a real password.

Do not combine this with preserving arbitrary client Basic authorization unless the security model explicitly requires both behaviors.

Mobile, native, and sync clients

Native clients often cannot follow a browser SAML redirect or share the browser cookie. This affects some tested products even when their web interface works.

Options are:

• keep the native/API hostname separate and secure it with the application's own authentication;
• use a precise passthroughPaths prefix for an API that remains independently authenticated;
• use a high-entropy passthrough token for controlled automation;
• disable unsupported clients rather than broadly bypassing authentication.

Never expose an application API through passthrough when it assumes PassBeyond already authenticated the caller.

Tested applications

The project has been tested as an authentication overlay with:

• Grafana
• Confluence and Jira, excluding their mobile apps
• Syncthing
• Firefly III
• Proxmox
• AdGuard Home
• Guacamole
• Bitwarden/Vaultwarden, excluding mobile apps
• wger
• Graylog
• UniFi Controller
• Nextcloud, excluding its mobile app and sync client
• SonarQube
• Checkmk
• Frigate
• NodeRed

This list confirms browser routing through PassBeyond, not a guaranteed transparent-login configuration for every product version. Application authentication options can change verify them against the vendor documentation for the deployed version.

Available recipes

• Generic trusted-header integration
• Grafana auth proxy

Additional application recipes should document the exact tested application version, PassBeyond version, headers, user-provisioning behavior, logout behavior, and unsupported native clients.

Validation checklist

• [ ] A direct request to the backend is blocked by network policy.
• [ ] A request without a PassBeyond session starts SAML authentication.
• [ ] The application receives the expected stable subject.
• [ ] A forged identity header from the public client is ignored.
• [ ] Missing email or groups fail safely.
• [ ] User creation and group synchronization behave as intended.
• [ ] PassBeyond and application logout behavior is understood.
• [ ] Mobile/API access either works independently or is explicitly unsupported.
• [ ] Large group sets do not exceed cookie or header limits.