Logging and monitoring

PassBeyond writes structured-looking plain text to standard output and error. Under the packaged systemd unit, journald adds timestamps and PassBeyond uses the identifier passbeyond-<instance>.

There is currently no configurable log level, JSON output, metrics endpoint, or audit-log destination.

Read logs

For a systemd instance:

sudo journalctl -u passbeyond@myapp.service -n 100 --no-pager
sudo journalctl -u passbeyond@myapp.service --since "15 minutes ago" --no-pager
sudo journalctl -u passbeyond@myapp.service -f

For a container:

docker logs --since 15m passbeyond-myapp
docker logs -f passbeyond-myapp

Log categories

Prefix or message	Meaning
WEB:PROXY:AUTH	Request proxied with a PassBeyond user session
WEB:PROXY:PASSTHROUGH	Request proxied without a user session
WEB:UNAUTH	No valid application or SAML flow session; authentication starts
WEB:METADATA	Public SP metadata was requested
WEB:ERROR	Request handling, subject, loop, or configuration-related error
SAML-ERROR	SAML request or response validation failed
PROXY-ERROR	Backend connection or reverse-proxy failure
WARNING	A fallback was used, commonly cached metadata
Failed to ...	Fatal startup or initialization error when followed by process exit

Authenticated proxy records include the resolved client IP, subject, UTC timestamp, method, request URI, referrer, and user agent. Passthrough records contain no authenticated subject.

Request IDs

Friendly SAML and proxy error pages show a random request ID. The same ID appears in the corresponding SAML-ERROR or PROXY-ERROR record.

sudo journalctl -u passbeyond@myapp.service \
  | grep 'REQUEST-ID-FROM-ERROR-PAGE'

Use the ID and a narrow time window when assisting a user. It avoids searching or sharing unrelated identities and request paths.

Privacy and retention

Treat PassBeyond logs as personal and security-relevant data. Depending on traffic, they can contain:

• authenticated user identifiers;
• client IP addresses;
• complete paths and query strings;
• referrer URLs;
• user-agent strings;
• network and SAML error details.

Do not place secrets in URLs. Restrict journal and log-platform access, set an explicit retention period, encrypt transport to central logging, and document the lawful purpose for identity logging in your environment.

Before sharing diagnostic lines:

• replace domains and user identifiers where they are not essential;
• remove query values and internal addresses;
• exclude cookies and all authorization headers;
• never attach the dynamic JSON file or a SAML response.

PassBeyond sanitizes line breaks in request-derived log fields to reduce log injection, but that does not make the logged values non-sensitive.

Metadata monitoring

URL-based metadata should produce SAML IdP metadata updated and cached at startup and every successful refresh. Alert when refresh failures repeat beyond the expected IdP maintenance window.

The last successful update is stored in dynamic state. Query only that field rather than printing the whole secret-bearing file:

sudo jq -r '.settings["saml-idp-metadata-last-updated"] // "not available"' \
  /var/lib/passbeyond/myapp.json

Local metadata mode does not update this timestamp.

Certificate monitoring

Monitor the certificate through the public endpoint:

curl --fail --silent --show-error \
  https://myapp.example.com/saml/certificate.crt \
  | openssl x509 -noout -dates -fingerprint -sha256

Alert well before notAfter. The generated certificate is not automatically rotated; follow Certificate and key rotation.

Recommended signals

Monitor at least:

• systemd or container process state;
• TCP reachability of the private listener;
• public /saml/metadata.xml availability;
• repeated SAML-ERROR, PROXY-ERROR, or metadata refresh failures;
• authentication-loop reports;
• certificate expiry;
• disk and inode availability for dynamic state and logs;
• an external end-to-end login and backend request.

The metadata endpoint is a shallow availability signal. It does not verify IdP login, JWT creation, backend reachability, or application authorization.

Edge-proxy monitoring

The public proxy must provide the controls PassBeyond does not implement. Monitor its rate limits, rejected body/header sizes, TLS expiry, upstream latency, and 4xx/5xx distribution. Correlate edge timestamps with PassBeyond logs rather than forwarding untrusted request IDs into a privileged log context.