Deployment

A production request passes through three layers:

Internet → TLS reverse proxy → PassBeyond → Backend application

Only the TLS reverse proxy should be public. Bind PassBeyond to loopback or a private network, and ensure that users cannot reach the backend by another route.

For complete nginx, Apache, Caddy, container-network, WebSocket, and edge rate-limit examples, see Reverse proxy integrations.

nginx example

The following example protects myapp.example.com. Certificate provisioning is intentionally outside the example.

upstream passbeyond_myapp {
    server 127.0.0.1:8123;
    keepalive 32;
}

server {
    listen 80;
    listen [::]:80;
    server_name myapp.example.com;

    return 307 https://$host$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name myapp.example.com;

    ssl_certificate     /etc/letsencrypt/live/myapp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/myapp.example.com/privkey.pem;

    location / {
        proxy_pass http://passbeyond_myapp;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Proxy "";

        proxy_buffering off;
        proxy_redirect off;
    }
}

Match it with:

domain: "myapp.example.com"
proxy:
  listenAddress: "127.0.0.1:8123"
  targetURL: "http://127.0.0.1:8888"
  trustedProxies:
    - "127.0.0.1"
    - "::1"

trustedProxies controls whether PassBeyond accepts X-Forwarded-For from the connecting peer. PassBeyond then overwrites the forwarding headers sent to the backend with the resolved client address.

If the application uses WebSockets, add its normal Upgrade and Connection proxy settings. If uploads are large, configure nginx's body-size limit for the application's requirements. PassBeyond also has fixed server and transport timeouts; review Runtime limits for long-running requests and large identity sessions.

TLS to the backend

When targetURL uses HTTPS, certificate validation is enabled by default. Keep targetDisableSSLVerify: false and establish a trusted internal CA where necessary.

Avoid disabling verification

targetDisableSSLVerify: true makes the PassBeyond-to-backend connection vulnerable to interception. Use it only as a short-lived diagnostic measure on a controlled network.

systemd instances

The package template starts /usr/bin/passbeyond --config /etc/passbeyond/<instance>.yaml as the unprivileged passbeyond user. It also applies filesystem, device, kernel, clock, log, and privilege restrictions.

Run one instance for each domain or service:

/etc/passbeyond/wiki.yaml       → passbeyond@wiki.service       → 127.0.0.1:8123
/etc/passbeyond/grafana.yaml    → passbeyond@grafana.service    → 127.0.0.1:8124

Each instance needs a unique:

• domain;
• proxy.listenAddress;
• proxy.targetURL;
• configPath dynamic state file.

For an OCI image instead of the system package, follow Container deployment. Keep the same one-instance-per-domain model and persist the dynamic state directory.

Start and inspect an instance with:

sudo systemctl enable --now passbeyond@wiki.service
sudo journalctl -u passbeyond@wiki.service -f

Persistence and backup

Back up both the static YAML configuration and the dynamic JSON state. Preserve file ownership and permissions during restore. A restored instance must use the same domain and private state if existing sessions and the published SAML certificate are expected to remain valid. The Backup and restore runbook covers consistent backups, migration, validation, and recovery.

For URL-based IdP metadata, cached metadata is part of the dynamic file and allows startup during a temporary IdP metadata outage. A new instance without a cache still needs a successful initial metadata download.

Operational checks

PassBeyond does not expose a dedicated health endpoint. Use multiple signals:

• systemd reports the process as active;
• logs contain no startup or metadata refresh failure;
• /saml/metadata.xml returns valid XML through the public origin;
• a test user can sign in and reach the backend;
• /saml/slo clears the PassBeyond cookie;
• the backend receives the expected identity headers.

Do not use only the metadata endpoint as a complete readiness check: it does not prove that the IdP login or backend target works.

Applications known to work

The project has been tested with Grafana, Confluence, Jira, Syncthing, Firefly III, Proxmox, AdGuard Home, Guacamole, Vaultwarden, wger, Graylog, UniFi Controller, Nextcloud, SonarQube, Checkmk, and Frigate.

Browser-based access is the intended use case. Mobile apps and sync clients may not support the SAML redirect flow; see Known limitations.

For the backend side of the deployment, use the application integration guide and its header-authentication recipes.