Users, roles and permissions

People who sign in to Meridian are in one of two separate realms. Staff sign in to the admin and act through roles granted to their groups. Members (on engine-dmo) sign in to the member portal on behalf of organisations and never hold staff permissions. The engine’s own background work runs as the system.

Staff access is configuration: roles and grants are YAML in config/access/, reviewed and versioned like the rest of the project. Which groups a user is in is data, managed from the command line, the admin or your identity provider.

A staff user’s permission comes through a chain: the user is in groups, a grant gives a group a role under a scope, and the role lists the permissions:

flowchart LR
  user["Staff user"] -->|is in| group["Group<br/>such as editors"]
  group -->|grants.yaml| grant["Grant"]
  grant --> role["Role<br/>built in or roles.yaml"]
  grant --> scope["Scope<br/>site, type, locale, state, owner, tag"]
  role --> perm["Permissions<br/>such as content.publish"]
  perm --> decision{"Allowed on<br/>this resource?"}
  scope --> decision

The user may act when any one grant’s role holds the permission and that grant’s scope covers the resource.

A minimal exampleCopy Anchor Link

# config/access/grants.yaml
grants:
  - { group: administrators, role: owner }
  - { group: editors, role: editor }
  - group: welsh-team
    role: translator
    scope: { locale: [cy] }
  - group: town-editors
    role: editor
    scope: { site: [town] }
  - group: newsroom
    role: news-writer
    scope: { type: [article], state: [draft, in_review], owner: self }

# config/access/roles.yaml
roles:
  - key: news-writer
    name: { en: News writer }
    permissions: [content.view, content.create, content.edit, media.view, media.upload]

Run engine-dmo check --fix to give the new role its id. A member of newsroom can create articles and edit their own drafts and articles in review, but cannot publish, see other people’s drafts or touch other types. A member of welsh-team can edit and publish Welsh on any document. A member of town-editors has the editor role on the town site only.

Staff users and groupsCopy Anchor Link

A staff user has an email address, a display name, a status (active or suspended) and a list of groups. Groups are plain keys such as editors or welsh-team; they need no declaration, and exist because a user is in them and a grant names them.

Opening an enrolment link, the user sets a password and enrols an authenticator app in one step, then sees their recovery codes once.

engine-dmo user list                       # every user, --group <key> for one group
engine-dmo user suspend --email <address>  # suspend and revoke every session
engine-dmo user reset-mfa --email <address> --confirm # clear the second factor, revoke sessions, print a new enrolment link

Local accountsCopy Anchor Link

# config/engine.yaml
auth:
  staff:
    local:
      enabled: true
      require_mfa: true
      password_min_length: 12
      breach_check: local
      allowlist: ${LOCAL_ACCOUNT_ALLOWLIST:-}

Single sign-onCopy Anchor Link

With auth.staff.oidc.enabled: true, staff sign in through an OpenID Connect provider. The provider says who the user is; your grants say what their groups may do. group_claim names the claim that lists a user’s groups, and group_map maps each value in it to one or more Meridian group keys:

auth:
  staff:
    oidc:
      enabled: true
      issuer: ${OIDC_ISSUER}
      client_id: ${OIDC_CLIENT_ID}
      client_secret: ${OIDC_CLIENT_SECRET}
      group_claim: groups
      group_map:
        "Web-Editors": editors
        "Web-Admins": administrators
        "Comms": [newsroom, welsh-team]

Each value is compared exactly. Every Meridian group a mapping names must be one grants.yaml grants a role to (or one provision.groups gives every user); check refuses a mapping that would grant nothing.

Custom fields on the staff user record are declared in config/access/users.yaml.

RolesCopy Anchor Link

A role is a named list of permissions. Eight roles are built in, and a grant can name any of them without roles.yaml declaring it:

Every list except owner’s is written out, so a permission added in a later release is denied to these roles until your roles.yaml grants it.

# config/access/roles.yaml
roles:
  - key: media-steward
    name: { en: Media steward }
    permissions: [media.view, media.rights, media.delete, ai.use]

# config/access/grants.yaml
grants:
  - { group: administrators, role: owner }
  - { group: editors, role: editor }
  - { group: editors, role: media-steward }

Modules add their verbs to some built-in roles; see Modules and bundles.

Your own rolesCopy Anchor Link

config/access/roles.yaml declares roles of your own, and replaces built-in ones:

roles:
  # A new role, with an id written by check --fix.
  - key: news-writer
    name: { en: News writer }
    permissions: [content.view, content.create, content.edit, media.view, media.upload]

  # Replaces the built-in editor role: this list is the whole of it.
  - key: editor
    name: { en: Editor }
    permissions: [content.view, content.create, content.edit, content.publish, media.view, media.upload, media.edit, nav.manage]

The owner role can be renamed (its name) but given no permissions list.

The permissionsCopy Anchor Link

Core’s verbs, in both bundles:

Each module the binary compiles adds its own verbs (Modules and bundles). engine-dmo access matrix lists every active user’s effective permissions, by group (--site for one site’s view).

GrantsCopy Anchor Link

A grant gives a group a role under a scope. Every grant is in config/access/grants.yaml:

The scope’s dimensions:

A dimension left out, empty or containing "*" means any value. The dimensions of one grant combine with AND; a user with several grants (through several groups, or several grants to one group) may do whatever any one of them allows.

Scope is applied inside the database queries, so a list in the admin or the content MCP shows only what the user’s grants reach, and counts and pages are right.

Applying role and grant changesCopy Anchor Link

Roles and grants are part of the schema plan. A change appears in engine-dmo schema plan and takes effect when it is applied (dev up applies it as you save, unless it is destructive):

• Removing or narrowing a grant that takes a permission from active users is destructive, marked with the number of users who lose it, and needs approval like any destructive change.
• A plan that would leave no active user able to manage users or holding the owner role is refused, even with --allow-destructive.

The admin’s Access screen can draft a grant for you: it renders the YAML and a diff against grants.yaml for you to commit. It never writes the file itself.

Explaining a decisionCopy Anchor Link

engine-dmo user grant-explain --email sam@example.org --action content.publish --resource article:<document id>

grant-explain says whether the user may do it and why: each grant they hold, each dimension of its scope, and which one passed or failed. With --resource type:<id> it reads the site, type, locale, state, owner and tags from the document; without it, describe a hypothetical resource with --site, --type, --locale, --state, --owner and --tag. The admin’s Access screen answers the same question.

MembersCopy Anchor Link

On engine-dmo, the people behind organisations (a business owner, its marketing contact) sign in to the member portal, not the admin. Members are a separate realm:

• They never hold staff grants; nothing in grants.yaml applies to them.
• They sign in with a magic link or a passkey (auth.member in engine.yaml). Member passwords are not available.
• They join by a staff invitation or by claiming an organisation (auth.member.registration: claim, the default), or by invitation only (invite_only).
• What a member may do for an organisation is set by their partner role on it. owner, manager, contact and billing are built in; config/portal/roles.yaml adds your own or restates a built-in one.

A staff user with member.impersonate can see the portal as a member sees it. Partners and the portal covers members, partner roles and the portal in full.