Administration on back(d)

Command-line administration

Mon, 01 Jan 0001 00:00:00 +0000

The backd binary is also the command-line client for administering a realm. backd user and backd apikey don’t touch MongoDB: they call the realm’s admin API on a running backd, as an administrator. They never need database credentials, and every change they make goes through the same checks as any other admin request, including network restrictions.

Two commands write to MongoDB directly instead: backd bootstrap, which creates a realm’s first administrator, and backd secret rotate-key, which re-encrypts every realm’s secrets under a new master key (see Secrets).

Admin API

Mon, 01 Jan 0001 00:00:00 +0000

The admin API manages the users and API keys of a realm. backd user and backd apikey are command-line clients of it (see Command-line administration), and server-side services can call it directly. It lives under /v1/{realm}/_admin in every realm with auth: enabled.

Every request needs one of the realm’s API keys with the admin role, acting as itself, or the session of a user holding one of the realm’s admin roles:

Credential	Answer
API key with the `admin` role	Allowed
Session of a user holding an admin role (`admin: true` in `realm.yaml`)	Allowed
Session of a user whose admin role opens only some areas	Allowed for those areas; `403 forbidden` naming the missing one for the rest
API key with the `data` role	`403 forbidden`
None, or an invalid key	`401 unauthenticated`
Session of a user without an admin role	`403 forbidden`
`X-Backd-On-Behalf-Of` with any credential	`400 invalid_header`: admin calls never act as another user

Admin UI

Mon, 01 Jan 0001 00:00:00 +0000

The admin UI is a web interface for realm administrators and developers. It is a client of the Admin API and nothing more: it can do nothing the CLI can’t, and every call it makes is authenticated, network-checked and audited by the server like any other. This page is the start of its guide; each area of the interface (users, keys, secrets, audit, functions, data, configuration) is added to it as the area ships.

Audit trail

Mon, 01 Jan 0001 00:00:00 +0000

Each realm with auth: enabled keeps an audit trail: one record per security-sensitive action or event, with who did it, to what, when and from where. It answers questions such as “who gave Bob the admin role?” or “which key created this user?”. Records can be read, but not changed or deleted: they expire after the realm’s retention period.

What is recorded

Action	When	Details
`user.create`	An administrator (or `backd bootstrap`) creates a user	`password` (whether one was set), `roles` (seeded from `realm.yaml`)
`user.signup`	A user signs up	`invited`, `roles`
`user.password`	An administrator sets a user’s password
`user.password_change`	A user changes their own password
`user.verify_email`	An administrator marks an email as verified, or not; or a user verifies it with the link in their email	`verified`
`user.password_reset`	A user sets a new password with a reset link	`verified_address`
`user.email_changed`	A user’s address changes: confirmed by the new address, or set by an administrator	`by` (`self` or `admin`)
`user.email_change_reverted`	The old address undid a change
`user.purged_unverified`	A worker deletes accounts that never verified their address	`count`, `older_than`
`push.test`	An administrator sent a test push to a user	`send`, `kind`
`device.removed`	An administrator removes a user’s push device	`platform`, `device`
`user.claimed`	A link or code verified an address that was never verified, and took the account away from whoever made it: password, providers, second factor and sessions are removed	`methods`, `mfa`
`function.invoke_manual`	An administrator runs a function by hand (admin API)	`as` (the user’s id, never their email, or null)
`files.versions.regenerate`	An administrator runs `backd files regenerate` (admin API)	`version`, `missing_only`, `job_id`
`storage.reconcile`	An administrator runs `backd storage reconcile` (admin API)	`delete`, `orphans` (how many were found), `deleted`
`storage.check`	An administrator runs a storage check (admin API); never the keys or anything stored	`ok`, `provider`, `bucket`
`data.check`	An administrator starts a schema check (admin API); the target is `data:<database>/<collection>`, `data:<database>` or `data:*`; never the report	`collections`, `limit`, `job_id`
`schedule.pause`, `schedule.resume`	An administrator pauses or resumes a function’s schedule (admin API); only a change is recorded; the target is `schedule:<database>/<function>`	none
`triggers.gap_resolve`	An administrator closes a gap of the trigger dispatcher (admin API, `backd triggers resolve`); the target is `trigger-gap:<id>`	none
`triggers.rescan`	An operator runs `backd triggers rescan` for a collection; the actor is `cli`; the target is `<database>/<collection>`	`trigger`, `since`, `scanned`, `queued`, `run`
`job.cancel`, `job.rerun`	An administrator cancels a job, or queues a finished one again (admin API); the target is `job:<id>`	`function`; for a re-run also `new_job`
`user.disable`, `user.enable`	An administrator disables or re-enables a user
`user.delete`	An administrator erases a user (the tombstone is made; the data work is in the job)	`job_id`
`user.erased`	The erase job finished, or failed for good	`job_id` and `counts` per `database/collection/operation`; `needs_attention` and `error` when it failed. Never content
`user.delete_account`	A user deletes their own account (it is deactivated, not erased)
`user.networks`	A user’s network restrictions change, through the API or from `realm.yaml`	`admin_networks`, `login_networks`
`identity.apple_revoked`	Apple revoked a user’s tokens after their account was erased or deleted, or Apple was unlinked
`identity.linked`	A provider account is linked to a user, automatically or by the user; also when a provider sign-up creates the user	`provider`
`identity.unlinked`	A user (or an administrator) removes a sign-in method	`provider`, `by` (`self` or `admin`)
`identity.signin_refused`	A provider sign-in for an account that can’t sign in (the app is only told `signin_refused`)	`provider`, `reason` (`disabled`, `network`, `erased`, …)
`role.add`, `role.remove`	A role is assigned or taken away, through the API or from `realm.yaml` seeds	`role`
`data.transfer`, `data.assign_org`	A document is moved to another organization, or a job gives a collection’s documents without one an organization (admin data route)	`database`, `collection`, `id`, `from`, `to` / `org`, `job_id`; never content
`org.create`, `org.update`	An organization is created (by a user or an administrator) or renamed	`by`, `creator` / `fields`
`org.member_add`, `org.member_remove`, `org.member_leave`, `org.roles`	A member is added without an invitation, removed, leaves, or has roles changed	`user`, `roles`, `by` / `added`, `removed`
`org.team_create`, `org.team_update`, `org.team_delete`, `org.team_member_add`, `org.team_member_remove`	A team is made, changed or deleted, or someone joins or leaves it	`team`, `name`, `roles` / `user`
`org.invitation_create`, `org.invitation_link`, `org.invitation_accept`, `org.invitation_revoke`	An organization invitation is made, given a new link, accepted or revoked	`invitation`, `binding`, `roles`, `teams`, `sent` / `user`
`org.require_mfa`	An organization turns its second-factor requirement on or off	`value`
`org.delete`, `org.deleted`, `org.reactivate`	An organization is deleted (access ends), its cleanup ends, or it is brought back	`by`, `job_id` / `counts` (documents removed per collection; never content) / `slug`
`org.claims`, `org.owner_assign`	Claims are replaced; a manager is assigned	`keys` / `user`
`apikey.create`, `apikey.revoke`	An API key is created or revoked	`role`, `networks`, `expires_at`
`invitation.create`, `invitation.revoke`	An invitation is created or revoked	`bound_to_email` (whether it is), `expires_at`
`invitation.sent`	An invitation is emailed to its address	`expires_at`
`admin.login`	A user holding an admin role logs in	`session_id`
`data.create`, `data.update`, `data.delete`, `data.restore`, `data.purge`	A document is written through the admin data route (a batch audits each operation)	`database`, `collection`, `id`; the target is `doc:<database>/<collection>/<id>`; never content
`session.revoke`	An administrator ends a user’s session (admin API)	`session`
`admin.refused`	An admin API request is refused: by a network restriction, or because the administrator’s roles don’t open the area or hold the rights of the user or role involved	`reason`, `method`, `path`
`realm.bootstrap`	`backd bootstrap` creates the realm’s first administrator	`role`

Failed logins aren’t recorded here: they are throttled and counted, and every request is in the access log.

Deleting and erasing users

Mon, 01 Jan 0001 00:00:00 +0000

backd separates two things people call “deleting an account”:

What	Who	Effect	Reversible
Deactivate	the user (`DELETE /_auth/me`, with their password), or an administrator (`PATCH /_admin/users/{id}` with `disabled`, `backd user disable`)	the user is disabled and every session ends; all data is kept	yes: an administrator reactivates (`backd user enable`)
Erase	an administrator (`DELETE /_admin/users/{id}`, `backd user delete --yes`)	the user becomes a tombstone, and the policies of your collections are applied (below)	no

Compliance with backd

Mon, 01 Jan 0001 00:00:00 +0000

Apps that handle personal data usually have to answer four questions: what do you hold about me, did I agree to this, stop using my data for that and delete me. backd builds the mechanisms once; the decisions stay yours.

Not legal advice

backd gives you tools, not conclusions. Which law applies to you, the legal basis of each use of data, the texts people accept, how long you keep each thing and how fast you must answer a request are decisions for you and your lawyers. Nothing here, and nothing backd does by default, is a statement that you comply.

What backd provides, and what stays yours

Need	What backd gives you	What is still yours
Knowing what is held about a person	A personal data scope per collection (`personal_data:`), a report of it (`backd compliance scope`), and the system data it adds; the same model as erasure	Declaring what exempts a collection, and checking that collections mixing several people’s data are narrowed with `fields`
A copy of the data	The scope and the per-user reads you build on (`GET /_admin/users/{id}/owned`, consent history); the export package itself is planned	Answering the request within your legal deadline, and verifying who asks
Consent	Versioned texts, records that name the exact words (a hash), withdrawal, re-acceptance, rules and email/push gating	The texts, which consents you need and why, and what each is used for
Erasure	A tombstone, per-collection policies, reduced consent records, retention	The policies you declare, backups, and data held outside `backd` (your function’s calls to other services)
Retention	`audit.retention`, `functions.log_retention`, `compliance.consent_retention`, soft-delete retention	The periods themselves: they are legal decisions
Minors	Nothing: age checks and parental consent belong to the app	Whether you need them; they can be recorded as consents or by functions

What counts as a person’s data

A user’s data is, by default, the documents whose _meta.owner is that user (whatever their on_owner_delete action), the documents where their id or email is listed in a pull field of an erase policy, and the files those documents hold, plus the account itself: identities, sessions, devices, second-factor status, consents, audit records about them and the function invocations they made. Credentials, tokens, secrets and other people’s details are never part of it.

Security model

Mon, 01 Jan 0001 00:00:00 +0000

This page summarizes how backd protects data in realms with auth: enabled, and what the operator is responsible for. To report a vulnerability, see SECURITY.md.

Who can do what

Caller	Proves identity with	Can
Anonymous	nothing	What access rules allow `user == nil`
User	session token (`bds_…`)	What access rules allow that user; manage their own account and sessions
Server-side service	API key (`bdk_…`) with the `data` role	Everything in the realm’s data; act as a user with `X-Backd-On-Behalf-Of`
Management tooling	API key with the `admin` role	The same, plus the admin API: users, roles, invitations, API keys
Administrator	session of a user holding an admin role, for example through `backd login`	What access rules allow that user, plus the admin API
Operator	access to `CONFIG_DIR` and MongoDB	Everything, including creating a realm’s first administrator with `backd bootstrap`

Credentials belong to one realm and are unknown in every other realm. Invalid, expired or revoked credentials are always refused (401), never downgraded to anonymous access.

Administration on back(d)

Command-line administration

Admin API

Admin UI

Audit trail

What is recorded#

Deleting and erasing users

Compliance with backd

What backd provides, and what stays yours#

What counts as a person’s data#

Security model

Who can do what#

What is recorded

What backd provides, and what stays yours

What counts as a person’s data

Who can do what