Skip to content

Authentication

Relay supports local passwords, local two-step sign-in, email-backed registration, and OpenID Connect (OIDC).

Local accounts

Under Administration > Authentication > Local two-step sign-in, enable Require two-step sign-in for local password logins (requireSecondFactor, default false). The setting persists to administrator overrides; refresh and verify it before relying on the policy. Users without a factor must enroll before entering chat. Existing password-only sessions must sign in again on reconnect; already connected sessions are not instantly disconnected.

With the policy off, TOTP enrollment still requires a second step for that account's local password logins. A registered key alone does not require a second factor for optional password login. See the enrollment steps. TOTP enrollment, recovery codes, and optional/required local MFA are post-v0.11.0 behavior in this audited checkout.

Enable allowRegistration for self-registration. registrationMaxUsers caps persisted accounts created through registration (zero means unlimited); administrator creation bypasses the cap. With SMTP enabled, registration verifies an email code before account creation. Without SMTP, registration does not provide email verification. SMTP availability is not a password-reset-by-email feature.

OpenID Connect

Set the issuer URL, client ID, client secret, scopes, and username claim path under Administration > Authentication. Register the public callback URL https://chat.example.com/auth/oidc/callback with the provider, using your Relay hostname and the same HTTPS origin as sign-in.

An OIDC user must already have a matching Relay account; OIDC does not automatically provision one. A dedicated claim such as relay_username is safer than deriving names from mutable display values. Relay does not add its local second-factor challenge to OIDC, so enforce the required MFA policy at the identity provider.

Treat client secrets and SMTP credentials as secrets, restrict configuration-file access, and use HTTPS for both Relay and the identity provider.

Account recovery

For a lost local password, verify the user's identity through your normal administrative process and use Administration > Users to reset it, or run relay users reset <name> with the correct data directory. CLI reset clears saved sessions but retains TOTP and security keys; it does not bypass the next factor challenge.

For a lost authenticator, use an unused recovery code or another enrolled security key. To replace TOTP after signing in, remove the old authenticator using the current password and a valid authenticator/recovery code, then enroll again. There is no dedicated CLI MFA-reset command in this checkout. If every factor and recovery code is lost, an operator with filesystem access can recover the account after verifying its owner:

  1. Stop Relay and back up users/<name>.json securely.
  2. Use relay users edit <name> against that home. Remove the totp field, replace webauthnCredentials with [], and replace sessions with {}. Preserve the other account fields and valid JSON. This deliberately removes local factors and remembered access.
  3. Run relay users reset <name> to issue a fresh local password, then restart Relay.
  4. Have the owner sign in and enroll new factors immediately. Required-MFA policy keeps them in enrollment until verification. Revoke lost devices at the identity provider separately for OIDC.

Do not delete the account merely to regain setup access. Turning off instance-required MFA does not disable an account's enrolled TOTP.

For OIDC-only accounts, recover access at the identity provider and confirm the configured claim still matches the intended local account. Relay binds provider identity server-side; changing a claim is not a supported way to take over another account. Keep an independently recoverable local administrator before changing provider policy.