Skip to main content
r5d.chat supports local password accounts and an optional OIDC provider that administrators configure at runtime, without a redeploy.

​
First-administrator setup

A fresh installation has no users. The first successful setup request creates the administrator and permanently closes public setup.
Between exposing the installation and claiming it, anyone who reaches the URL can become the administrator. Always set SETUP_CLAIM_TOKEN before making an unclaimed installation reachable.
Setup requires a name, an email, a password of at least 12 characters containing a letter and a number, and the claim token when one is configured. Check the current state at any time:
required: false means the installation is claimed. The whole operation is a single transaction, so concurrent attempts cannot produce two administrators.

​
Invitations and local accounts

Administrators manage users from the admin area.
1

Create an invitation

Generates a single-use link for a new account.
2

Or create the account directly

Administrators can create an account with a temporary password and hand it over through a secure channel.
3

Manage roles and access

Promote users to administrator or disable accounts that should lose access.
Keep at least one local administrator account even after enabling SSO. If the identity provider becomes unreachable or misconfigured, local login is the recovery path.

​
OIDC single sign-on

Configure any standards-compliant OIDC provider at runtime from the admin settings.
​
string
required
Lowercase identifier used in callback URLs, matching ^[a-z0-9][a-z0-9-]{1,38}$.
​
string
required
Button text on the login page, for example “Sign in with Okta”.
​
string
required
The issuer URL, such as https://login.example.com.
​
string
Optional explicit .well-known/openid-configuration URL when it is not at the standard location.
​
string
required
OAuth client identifier from your provider.
​
string
required
OAuth client secret. Encrypted with SETTINGS_ENCRYPTION_KEY.
​
string
default:"openid profile email"
Space-separated scopes to request.
​
boolean
default:"false"
Create an account automatically on first successful sign-in. Leave this off to require an invitation first.
​
boolean
default:"false"
Link an SSO identity to an existing local account with the same email address.
Only enable this when the identity provider verifies email ownership. Otherwise a user who controls an unverified address at the IdP could take over an existing account.
​
array
default:"[]"
Restrict sign-in to specific email domains. Up to 50 entries. Recommended for any provider with a broad user base.

​
Set it up

1

Register the application at your provider

Set the redirect URI to:
<provider-key> is the provider key you configure below, and the host must match publicUrl exactly.
2

Enter the configuration

Fill in issuer, client ID, client secret, and scopes in the admin settings.
3

Test before enabling

Use the built-in test action, which validates discovery and the client credentials against the real provider.
4

Enable and verify

Enable the provider, then sign in from a private browser window to confirm the full round trip.

​
Sessions

Sessions are cookie-based and signed with BETTER_AUTH_SECRET. Cookies are scoped to the publicUrl host, which is why a mismatch between publicUrl and the browser’s address produces a login loop where sign-in appears to succeed but the session is never recognized. Rotating BETTER_AUTH_SECRET signs every user out.

​
Troubleshooting

The transaction did not complete. Check control-plane logs for a database error and confirm /api/setup still reports required: true.
publicUrl does not match the browser URL, so the session cookie is rejected. Align publicUrl, ingress.host, and your DNS record.
The redirect URI registered at the provider differs from https://<publicUrl-host>/api/auth/oauth2/callback/<provider-key>. They must match exactly, including scheme and trailing path.
With auto-provision disabled, an account must exist first. Either invite the user or enable auto-provision with an allowed-domain restriction.
The client secret is encrypted with SETTINGS_ENCRYPTION_KEY. Restore the original key or re-enter the OIDC configuration.