Organizations on backd

Build a B2B app

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

This recipe builds the backend of a small project tracker where each customer is an organization. It uses a realm called acme with a main database, and the JavaScript client. The finished version, with a UI, is the Shelf tutorial’s chapter 20.

Read the concepts first if “effective role” or _meta.org are new.

1. Declare the roles

In realm.yaml:

auth: enabled

organizations:
 roles:
 owner: { description: Runs the company, manage: [org, members, roles, teams] }
 admin: { description: Invites and removes people, manage: [members, teams] }
 editor: { description: Creates and edits projects }
 member: { description: Reads }
 default_roles: [member]
 creator_roles: [owner]
 invitation_link: "https://app.acme.example/join?token={token}"

The manage capabilities decide who administers the organization; owner needs org, since an organization always keeps someone who can manage it.
default_roles are held by every member, so member is never granted one by one.
The invitation_link must be inside the realm’s sign_in.allowed_redirects.
Creating organizations is allowed to anyone with a verified email by default (create: user.email_verified).

2. Mark the collections

In main/projects/collection.yaml:

Rules cookbook

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

Rules for collections with an organization:. The helpers are inOrg(org), hasOrgRole(org, role) and orgClaims(org).claim, described in access rules; document._meta.org is the organization of the document and data._meta.org the one a create names (?org=).

Members read

rules:
 read: inOrg(document._meta.org)

Everyone who belongs to the organization reads its documents, and nobody else sees them, counts or lists. In a read rule this is a database filter.

Editors write, admins delete

rules:
 read: inOrg(document._meta.org)
 create: hasOrgRole(data._meta.org, 'editor') || hasOrgRole(data._meta.org, 'admin')
 update: hasOrgRole(document._meta.org, 'editor') || hasOrgRole(document._meta.org, 'admin')
 delete: hasOrgRole(document._meta.org, 'admin')

Roles are checked in the document’s organization only: an admin of one customer holds nothing in another. Effective roles include the ones from teams and default_roles.

Team roles

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

Teams carry organization roles to everyone in them. That is enough for “the editors”, but not for “Marta manages Sales”: a manager of Sales must not manage Support. Team roles are roles held within one team, by a member of the organization, and they mean nothing outside it.

Organization roles, teams and team roles

	Organization role	Team	Team role
Declared in	`organizations.roles`	created through the API	`organizations.team_roles`
Holds	what the role allows in the organization	a group of members	a role in one team
Given by	`manage: members` or `manage: roles`	`manage: teams`	`manage: teams`
Gives access to	everything the role is checked for	the roles it carries	only what checks that team

A team role never gives an organization or a realm role, and an organization role never gives a team role.

What happens when…

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

What happens when…

Event	Access	Documents and data
A member leaves or is removed	Ends at the next request. They leave their teams	Documents they created stay with the organization. The last manager can’t leave: `409 last_org_manager`
A member is erased	Memberships, team memberships and bound invitations are removed	Documents stay, owner cleared (or erased, with `in_org: apply`). An organization left without a manager becomes `orphaned`
The last manager is erased	The organization has nobody to manage it	`orphaned`: a realm administrator assigns an owner (`backd orgs assign-owner`). The startup log and the erase report name it
An organization is deleted	Ends at once for everybody; the slug is free	Each collection’s `on_org_delete` applies in a resumable job: `delete` removes the documents and queues their files, `keep` leaves them readable only by administrators
A document is transferred	The new organization’s members see it, the old one’s don’t, at once	Only realm administrators transfer (`_transfer`); its `_meta.org` is the only change
`require_mfa` is turned on	Sessions without a second factor stop counting as members there; its routes answer `403 org_requires_mfa`	Nothing changes. The manager’s own session needs a second factor, or they would lock themselves out
A role is removed from a team	Members lose it at the next request, unless they hold it directly or through another team	The members list shows what remains. A team can’t lose its last managing role if that leaves nobody who can manage
A role is no longer declared in `realm.yaml`	The stored grants stay, and grant nothing; startup logs them	Declare the role again to restore it, or give another one
A member’s roles change	At the next request: there is no cache	Nothing
An invitation is revoked or its link reissued	The old token is invalid at once	People who already accepted keep their membership

See also teams or direct roles for why the same role should be given one way.

Membership hooks

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

Apps often need to react when someone joins a company: create a profile, add them to a channel, send a welcome. Polling for new members is slow and misses changes; membership hooks call an internal function for you, in the background, when it happens.

# realm.yaml
organizations:
 hooks:
 on_member_joined: core/members-joined  # <database>/<function>
 on_member_left: core/members-left
 on_roles_changed: core/roles-changed

Every hook is optional, and each names a function that is internal: true and mode: async; startup refuses anything else. They are run through the job queue like account.on_signup: there is no user in ctx, the function’s retry: applies, and a failure never undoes the change that caused it.

Company context

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

backd’s own emails (verification, password reset, magic links, MFA and consent notices, organization invitations) and its hosted pages are realm-wide. An app that serves many companies wants them to look like each company’s. Two things give them company context: the request says which organization the person comes from, and an internal function supplies the data, so backd never reads your collections by configuration.

Say where the person comes from

Sign-up, sign-in, POST /_auth/magic-link and POST /_auth/reset-password/request take an optional org:

Company email templates

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

With company context an email can look like the company’s. Company templates go one step further: the owners of an organization write the text themselves, for the kinds of email you allow, and backd keeps your own files as the fallback.

# realm.yaml
email:
 customizable: [org-invitation, magic-link, reset-password, verify-email, absence-requested]
 overrides:
 permission: manage_org # who edits: holders of manage: org (the default)

Every listed kind must have a template in the realm’s email/ folder, which is what a company’s version replaces; startup checks it, and that the realm has organizations. permission is manage_org, manage_members, manage_roles or manage_teams: the capability that edits them.

Team access recipes

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

Recipes for team roles and team-scoped documents. Each one is small and says what it relies on; the HR absences page puts them together in a tested example.

Concepts

	What it is	Rules ask
Organization role	what a person is in the company (`owner`, `hr`, `member`)	`hasOrgRole(document._meta.org, "hr")`
Team	a group of members. As a role group it carries organization roles to everyone in it; as a document owner it is where documents live (`_meta.team`)	`inTeam(document._meta.team)`
Team role	what a person is within one team (`manager` of Sales)	`hasTeamRole(document._meta.team, "manager")`

A team can be both. The roles a team carries (teams) are organization roles, given to everyone in it. Team roles are separate: held by a person in one team, giving nothing outside it. A team that carries roles and a person who holds a team role in it don’t interact.
inTeam vs hasTeamRole. inTeam is “they belong to the team”: everyone in Sales. hasTeamRole(…, "manager") is “they hold that role there, now”: the manager, whether or not they belong. Combine them with && and ||: inTeam(document._meta.team) || hasTeamRole(document._meta.team, "manager").
A role without membership. A team role is held by a member of the organization, not necessarily of the team: a delegate from Support approves Sales’ requests without seeing Sales’ calendar or having its roles.

Departments with managers

Documents carry the department (team: required), employees create in their own, managers read and decide for theirs:

Example: HR absences

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

An HR module for a B2B app: each company is an organization, each department a team, and people ask for absences that their manager (or someone covering) approves. The whole realm is examples/config/hr, and its rules are tested with backd rules test.

Who is who

Who	Is	Can
Ana	member of Sales	ask for an absence; edit or delete it while it is requested
Marta	member of Sales, `manager` there	see and decide Sales’ absences
Dario	member of Support, `delegate` in Sales for two weeks	see and decide Sales’ absences in that period
Hugo	`hr` in the company	see every absence of the company

The realm

examples/config/hr/realm.yaml

Organizations on backd

Build a B2B app

1. Declare the roles#

2. Mark the collections#

Rules cookbook

Members read#

Editors write, admins delete#

Team roles

Organization roles, teams and team roles#

What happens when…

What happens when…#

Membership hooks

Company context

Say where the person comes from#

Company email templates

Team access recipes

Concepts#

Departments with managers#

Example: HR absences

Who is who#

The realm#

1. Declare the roles

2. Mark the collections

Members read

Editors write, admins delete

Organization roles, teams and team roles

What happens when…

Say where the person comes from

Concepts

Departments with managers

Who is who

The realm