Legacy Authentication

By default, registration is disabled. You must explicitly enable it and choose what conditions, if any, a prospective user must meet before an account is created.

Enabling registration

Set allow_registration = true to enable registration. On its own this is not enough; you must also configure at least one of the following:

• A registration token (recommended)
• Required email at registration, with an SMTP connection_uri set
• The open-registration confirmation flag (not recommended)

Password registration also needs login_with_password left at its default of true. With it disabled, only identity providers can register new accounts.

Token-based registration

A registration token acts as a shared secret that prospective users must supply when creating an account. This is the recommended approach for private or invite-only servers.

Static token — set a single token directly in the config:

allow_registration = true
registration_token = "o&^uCtes4HPf0Vu@F20jQeeWE7"

File-based tokens — read tokens from a file, one per line or separated by whitespace. Useful for rotating tokens without restarting the server:

allow_registration = true
registration_token_file = "/etc/tuwunel/.reg_tokens"

Both options can be set at the same time; tokens from both are accepted.

Admin-issued tokens — generate short-lived or single-use tokens from the admin room without touching the config file:

Open registration

To allow anyone to register without a token, you must set an additional confirmation flag that acknowledges the abuse risk:

allow_registration = true
yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse = true

This is not recommended for public-facing servers. Consider token-based registration or SSO providers instead.

Email verification

Tuwunel can verify that a user controls an email address by emailing a single-use confirmation link through your own SMTP relay. No external identity server is involved; each verified address binds locally to one account. Email is the only supported medium (phone-number verification is not supported). Verified email is used for adding an address to an account, resetting a forgotten password, and optionally requiring email at registration.

Point Tuwunel at an SMTP relay and set the sender mailbox. The confirmation link is built from well_known.client, so that must also be set and reachable by your users in a browser:

[global.smtp]
connection_uri = "smtps://noreply%40example.com:password@mail.example.com:465"
sender = "Example <noreply@example.com>"

[global.well_known]
client = "https://matrix.example.com"

The subsystem is disabled by default and stays inert until connection_uri is set. If a client asks to verify an email while it is disabled, the request is rejected with M_THREEPID_DENIED.

Requiring email at registration

These options gate registration on a verified email address. Both default to off, and both require the email verification subsystem above to be configured.

Guest registration

Guest accounts are anonymous sessions that some clients (e.g. Element) create automatically before a user logs in. Guest registration is separate from normal registration and is disabled by default.

Login options

These options control which login methods are accepted regardless of how accounts were created.

Login rate limits

Password sign-in uses three token buckets. A refused attempt gets M_LIMIT_EXCEEDED, with a retry_after_ms unless a limit’s table is full.

• Wrong passwords: each account and client address pair has its own budget. An attempt reserves a token before checking the password and returns it on success; wrong passwords and unknown accounts keep it. Once exhausted, that pair is refused until a token refills, including attempts with the correct password. Attempts from another address still have their own allowance. Concurrent attempts each reserve a token, so they cannot bypass the limit.
• Client addresses: all password attempts from one address share a broader budget across accounts, charged before verification and kept on success too. This bounds password spraying and password-verification work.
• Successful sign-ins: only a verified password consumes the account’s sign-in budget. Wrong guesses never consume it, but an account that has signed in too often is refused even with the correct password.

Public /login and the built-in OIDC login page share the first two budgets. Password re-entry for sensitive actions (UIAA) has separate failed-attempt and address budgets with the same settings, so public login attempts cannot exhaust its allowance. The successful-sign-in budget does not apply to UIAA. LDAP binds made by /login remain outside these limits; an account not found in LDAP that falls back to local password checking is limited.

IPv4 addresses have individual budgets. IPv4-mapped IPv6 addresses use their IPv4 identity, and other IPv6 addresses share budgets within each /64. Clients sharing a NAT address also share its address budget. By default the address comes from the socket peer. A loopback peer, such as a reverse proxy connecting over loopback or any client of the Unix socket, stands for every client behind it, so its attempts are not limited per address and keep only the failed-attempt and successful-sign-in limits. Behind a reverse proxy, configure http.ip_source, restrict backend access to trusted proxies, and have the proxy replace the selected forwarding header with a verified address; this also applies the address budget behind a local proxy or the Unix socket. Do not accept client-supplied forwarding headers unchanged. A proxy that connects from a non-loopback address, including a container on a bridge network, gives all its users one address and allowance unless it forwards the client address. Password login and password UIAA require the selected source even for loopback peers and peers listed in http.ip_source_trusted_subnets; they do not use those peers’ usual extraction bypass. A missing or invalid selected source refuses authentication. At startup and on reload, a warning says when a Unix socket or loopback listener has no per-address limit.

Each limit has its own config section, shown here with its defaults:

[global.rate_limiting.login.failed]
per_second = 0.17
burst_count = 3

[global.rate_limiting.login.account]
per_second = 0.003
burst_count = 5

[global.rate_limiting.login.address]
per_second = 1.0
burst_count = 20

The failed-attempt budget allows three wrong passwords per account/address pair, then about one attempt every six seconds. The address budget allows 20 attempts across accounts, then one per second. The account budget allows five successful sign-ins, then about one every five and a half minutes. Setting either burst_count or per_second to 0 disables that limit.

Separating addresses prevents guesses from one address from exhausting an account’s allowance at another address. It also means distributed guesses from different addresses have separate failed-attempt budgets. Users sharing an address or IPv6 /64 can still affect one another. Existing sessions and non-password login methods (m.login.token, SSO and JWT) are unaffected.

Each table holds at most 65536 entries in memory and resets on restart. Fully refilled buckets can be removed to make room; buckets still limiting are retained. Full failed-attempt and address tables admit untracked pairs and addresses until room frees up, while retaining limits for existing entries. A full successful-sign-in table refuses untracked accounts. Table exhaustion logs a warning.

Token and session lifetimes

Emergency password

The emergency password lets you log in to the server bot account (@conduit:<server_name>) when normal access is unavailable — for example, if you have lost access to your admin room.

emergency_password = "F670$2CP@Hw8mG7RY1$%!#Ic7YA"

Remove this option and restart the server once you have regained access — all sessions for the bot account are logged out when it is unset. See the troubleshooting guide for other recovery methods.