Authentication
Users, sign-in methods and passwords in each realm.
Each realm with auth: enabled has its own pool of users and API keys, stored in the realm’s system database. One sign-in is meant to work across all databases of that realm (single sign-on), and never in another realm.
Sign-in methods: providers
A user holds only identity data: a unique email, whether that email is verified, roles, and whether the account is disabled. Credentials are not part of the user. Each way of signing in is a provider — a sign-in method (an identity) linked to the user:
password— built in, nothing to declare; the realm’s own accounts.magic_link— an emailed link or code, from the realm’smagic_link:section (Magic links). It proves control of the mailbox, the same thing a password reset proves.google,microsoft,apple— remote providers, declared in the realm’sproviders:section with their credentials as realm secrets (Sign in with…).passwordandemailare reserved names: no provider may take them.
A user can have several methods at once, at most one of each kind — a password and Google, say. They all lead to the same user, so roles, rules and owned documents don’t depend on how the user signed in. A user can exist without a password (an operator may create the account first), and can remove any method but the last (DELETE /_auth/identities/{provider}); GET /_auth/me lists them. Application data about a user, such as a display name or avatar, belongs in your own collections, not in the user.
Whatever the first factor, a user with a second factor is still asked for it — a provider sign-in answers the same challenge a password does: Multi-factor authentication.
The pages, in order
| Page | What it covers |
|---|---|
| Users and passwords | Creating and managing a realm’s users with backd user or the admin API |
| Sign-up, login and sessions | The /_auth endpoints: sign up, log in, sessions, password reset, brute-force protection, sign-in methods, deleting the account |
| Magic links | Signing in from an email alone: the link, the code, account claiming |
| Re-authentication | A fresh proof of identity before sensitive actions |
| Multi-factor authentication | The TOTP second factor, recovery codes, required_roles — applies to every first factor, remote providers included |
| Sign in with Google, Microsoft or Apple | The redirect flow, native ID tokens, linking rules, account.on_signup |
| Access rules | Per-collection rules: in collection.yaml: which callers may read, create, update and delete |
| Consents | Versioned texts, records, re-acceptance, withdrawal, gating |
| API keys | Server-side services, with full access to the realm’s data |
Operating it
- Command-line administration:
backd bootstrap,backd login,backd user. - Admin API: server-side user management.
- Audit trail of security-sensitive actions.
- Deactivating and erasing users, with per-collection policies for their data; compliance covers personal-data scope, retention and recipes.
- Provider sign-in in the clients: JavaScript and Dart —
signInWith,completeSignIn,signInWithIdToken.
See the security model for what backd protects, and the hardening checklist before exposing a realm. Planned: personal-data export as a downloadable package; other OpenID Connect providers (type: oidc).
Create and manage a realm’s users with backd user or the admin API.
Sign-up, login and sessionsThe /_auth endpoints: sign up, log in, manage sessions, change or delete the account.
Magic linksSign in from an email: a link on the same device, or a code typed on any device. How it works, who can use it and what it protects against.
Re-authenticationA fresh proof of identity before sensitive actions: which proof applies to which user, the endpoints that ask for it and how a client sends it.
Multi-factor authenticationA second step after the first factor: how a sign-in answers with a challenge, how the second factor is checked, and how rules and functions see how a session was made.
Sign in with Google, Microsoft or AppleLet users sign in with an external identity provider: configuration, the redirect flow, linking rules, errors and security.
Access rules (rules:)Decide per collection which callers may read, create, update and delete documents.
ConsentsVersioned consent texts kept with the config, accepted and recorded as proof, and served to apps.
API keysGive server-side services access to a realm’s data with API keys.