Certificate and key rotation

On first start, each instance generates a JWT secret and a self-signed 2,048-bit RSA certificate/key pair. They are stored in the dynamic JSON file. The certificate is valid for approximately five years and is not automatically renewed.

Rotation affects two separate trust relationships:

• the JWT secret validates PassBeyond browser sessions;
• the SAML key pair signs requests and can decrypt assertions configured for its public certificate.

Inspect the current certificate

Use the public endpoint so the check also validates the deployed route:

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

Record the SHA-256 fingerprint in the change plan and monitor notAfter. Begin coordination with the IdP well before expiry.

Understand the impact

Replacing the complete dynamic state:

• invalidates every existing PassBeyond JWT
• changes the SP certificate exposed in metadata
• changes the key used for signed authentication requests
• breaks assertion encryption until the IdP uses the new certificate
• creates a new instance ID
• discards cached remote IdP metadata until it is fetched again

There is no online rotation API or dual-certificate overlap. Plan a maintenance window and an IdP rollback path.

Planned full rotation

The following procedure rotates the whole generated state. Replace myapp consistently.

1. Prepare

1. Confirm remote IdP metadata is reachable, or that the configured local metadata file is valid.
2. Export or document the IdP application configuration.
3. Back up static and dynamic configuration securely.
4. Record the current certificate fingerprint.
5. Decide how the new certificate will be added at the IdP.
6. Warn users that active PassBeyond sessions will end.

If the IdP requires signed authentication requests or encrypted assertions, expect authentication to fail between PassBeyond restart and the IdP certificate update.

2. Stop and preserve old state

sudo systemctl stop passbeyond@myapp.service
sudo install -d -m 0700 /root/passbeyond-rotation
sudo cp --preserve=mode,ownership,timestamps \
  /var/lib/passbeyond/myapp.json \
  /root/passbeyond-rotation/myapp.json.before-rotation
sudo mv /var/lib/passbeyond/myapp.json \
  /var/lib/passbeyond/myapp.json.retired

Keep both copies protected. Do not edit key strings manually.

3. Generate new state

sudo systemctl start passbeyond@myapp.service
sudo journalctl -u passbeyond@myapp.service -n 100 --no-pager

PassBeyond creates the new file with fresh generated values. Verify ownership and mode:

sudo chown passbeyond:passbeyond /var/lib/passbeyond/myapp.json
sudo chmod 0600 /var/lib/passbeyond/myapp.json

Retrieve and record the new fingerprint.

4. Update the IdP

Refresh the PassBeyond SP metadata in the IdP or replace the certificate according to the provider's procedure. Confirm:

• request-signature verification trusts the new certificate when enabled;
• assertion encryption targets the new certificate;
• Entity ID, ACS URL, SLO URL, and NameID format did not change.

5. Validate

Use a private browser window and test:

1. SP-initiated authentication;
2. IdP-initiated authentication if used;
3. expected backend headers and authorization;
4. logout;
5. an encrypted assertion if configured.

Confirm the old session cookie no longer authenticates.

Rollback

If the IdP cannot be updated or validation fails:

sudo systemctl stop passbeyond@myapp.service
sudo mv /var/lib/passbeyond/myapp.json \
  /var/lib/passbeyond/myapp.json.failed-rotation
sudo cp --preserve=mode,ownership,timestamps \
  /root/passbeyond-rotation/myapp.json.before-rotation \
  /var/lib/passbeyond/myapp.json
sudo systemctl start passbeyond@myapp.service

Restore the previous certificate configuration at the IdP when it was changed. Verify the original fingerprint and login flow.

After the rollback window closes, securely remove retired copies according to the organization's secret-destruction policy.

Emergency rotation after compromise

Treat disclosure of the dynamic JSON file as disclosure of both JWT and SAML private material:

1. restrict access to the affected host and logs
2. stop the instance if active abuse is possible
3. preserve evidence according to the incident-response process
4. perform full rotation and IdP update
5. assume all existing JWTs are compromised until the secret changes
6. investigate backups, tickets, diagnostics, and log platforms for additional copies

Changing only sessionTimeout does not revoke existing tokens.

IdP signing-certificate changes

This is separate from rotating PassBeyond's own key. With idpMetadataURL, PassBeyond refreshes the IdP metadata every 30 minutes and keeps the last valid data if refresh fails. Coordinate IdP rollover so old and new IdP certificates overlap in published metadata.

With idpMetadataFile, replace the local metadata and restart PassBeyond. Keep the previous file available for rollback and validate the source before installation.