identity-manager¶
The Identity domain manager. It owns the Organization → Group → User hierarchy and the cross-cutting Role labels that back TAPPaaS identity, and it reconciles that desired config onto the identity service (Authentik) via the identity controller.
What it owns¶
Config state lives under config/identities/ (default ${TAPPAAS_CONFIG:-/home/tappaas/config}/people/), one JSON file per entity:
config/identities/
roles/*.json # cross-cutting role labels
organizations/*.json # tenant / company / family
groups/*.json # teams, departments, access-sets (carry roles)
users/*.json # people, with memberOf groups + roles + lifecycle state
Each file is validated against a JSON Schema (role-fields.json, organization-fields.json, group-fields.json, user-fields.json) plus cross-reference integrity (e.g. a user's memberOf groups must exist, an org's owner must be a known user). User lifecycle state is one of planned (no identity presence), active (full access), suspended (disabled + roles stripped), terminated (deleted).
The repo also ships minimal-org/ — the canonical bootstrap content (3 roles, 1 org, the users, authentik Admins and installer groups, and 2 users: root + the installer) with __ORG__ / __USER__ / __EMAIL__ / __ROOT_EMAIL__ placeholders, seeded by identity-manager bootstrap.
authentik Admins is Authentik's own built-in superuser group, adopted by name rather than invented. Membership in an is_superuser group is the only thing that grants the Authentik admin UI — the admin/root roles are labels TAPPaaS passes to apps and confer nothing there. The installer (= the site / default-environment owner) is a member, so day-2 user administration does not need the akadmin break-glass login; root is deliberately not.
installer is the console's Installer group (ADR-034 D3); the installer is its member. The console's Admin is the admin role, which Authentik carries as a group named admin (see identity/USERS.md).
Groups of three origins¶
| Origin | Which | Declared by | Edited with |
|---|---|---|---|
| the model | a file under config/identities/groups/ | that file | group add/modify/delete |
| a module | <module>-admins, for a module installed with identity.providesAdminRole (the module's name without its -<environment> suffix) | config/<module>.json, its identity block | the module (module-manager modify) |
| Authentik built-in | authentik Admins, authentik Read-only, authentik Agent-Users | the identity module (config/identity.json), its bootstrap | Authentik |
group list lists all three, a module's or a built-in group marked by its origin (forgejo-admins (module forgejo), authentik Read-only (Authentik built-in)); group list --declared lists only those two kinds (--json: name, origin, declaredBy). group show of one prints its origin and declaredBy, and group modify / group delete refuse it, naming its origin. A group with a file is the model's, whatever its name: authentik Admins is adopted that way.
Authentik's own users¶
Authentik's bootstrap creates two kinds of user TAPPaaS has no file for: akadmin, the break-glass login, and one service account per outpost, ak-outpost-<hex>. They come with the identity module, so its bootstrap declares them ({ "file": "identity.json", "key": "bootstrap" }, origin Authentik built-in). user list lists them beside the model's users, marked (Authentik built-in); the outpost accounts only when Authentik answers, since their names are Authentik's. user list --declared lists only them, user show prints their origin, and user modify / user delete refuse them. A user with a file is the model's, whatever its name.
Commands¶
This manager exposes one compiled CLI (identity-manager) plus one bash helper (validate-people.sh).
identity-manager — bootstrap, read, CRUD + reconcile¶
identity-manager bootstrap --org O --user U --email E [--minimal-org DIR] [--force] [--skip-validate] [--config-dir DIR]
identity-manager reconcile [--apply] [--config-dir DIR] (alias: sync, deprecated)
identity-manager validate [--config-dir DIR]
identity-manager <kind> list [--json] [--deep] [--declared] [--config-dir DIR]
identity-manager <kind> show <name> [--json] [--config-dir DIR] (alias: get, deprecated)
identity-manager <kind> add <name> [field flags] [--force] [--config-dir DIR]
identity-manager <kind> modify <name> [--set <field>=<value>]... [--unset <field>] [field flags] [--config-dir DIR]
identity-manager <kind> delete <name> [--force] [--config-dir DIR]
identity-manager user reset-password <name> [--link | --password-stdin] [--config-dir DIR]
identity-manager -h | --help
<kind> is one of role, org (alias organization), group, user.
The standardized ADR-007 verb vocabulary applies: add (was create), modify (was set/update-entity), delete (was remove), show (was get), list, reconcile (was sync). get is kept as a deprecated alias for show.
modify --set <field>=<value> names a field as its schema does (user-fields.json: displayName, primaryEmail, state, roles, memberOf; a list as a,b or JSON), and --unset <field> empties one. The field flags (--email, --groups, …) are shortcuts for one field each (ADR-020 D11); --add-* / --remove-* change a list by one entry.
Options:
--apply— onreconcile, push the plan to the identity service. Without it,reconcileonly PREVIEWS the plan (the default) — matchingsite-manager,network-manager, etc. (--dry-runis a deprecated no-op: preview is already the default.)--json— onlist/show, emit structured JSON (default is human-readable).--deep— onorg/grouplist, recurse into groups + user membership.--declared— ongroup list, only the groups a module or Authentik declares; onuser list, only Authentik's own users.--force— onadd, overwrite an existing entity; ondelete, ignore the reference guard.--config-dir DIR— the People directory to read/write (default$TAPPAAS_CONFIG/people).
Write-and-push workflow¶
add / modify / delete write the validated JSON under config/identities/<dir>/<name>.json and then push it to the identity service — a change is live when the command returns, with no second command to remember. Admins thus drive everything through verbs and never hand-edit JSON — see docs/design/ADR-007-verb-alignment.md ("admins drive verbs, not JSON").
identity-manager <kind> add|modify|delete ... # write + push
identity-manager <kind> add|modify|delete ... --no-reconcile # write only (stage)
identity-manager reconcile [--apply] # preview / push
Order of operations, and why it is that order:
- Validate, then write. Each write is gated by the same
validateRefsintegrity checkreconcileruns (an unknown role/org reference, a danglingmemberOf, etc. is rejected and no file is written), and is atomic (mktemp+rename). A rejected edit therefore never reaches the identity service. deletepushes the removal explicitly before reconciling.reconcileis driven by what config contains, so an entity whose file was just removed is invisible to the plan — without this step it would live on in Authentik forever. Users, groups and roles are removed; an Organization has no Authentik object, so there is nothing to push. Groups Authentik ships itself (authentik Admins,authentik Read-only) are dropped from config only, never deleted from Authentik.- Then a full reconcile, not just this entity's actions:
config/identitiesis the desired state, so the moment we are already talking to the identity service is the right moment to converge all of it.
If the push fails (identity service down, a rejected action), the command exits non-zero and says so — the config write stays on disk. The fix is to re-run identity-manager reconcile --apply, not to redo the edit.
--no-reconcile keeps the old config-only behaviour, for staging several edits into one push or for editing while the identity service is down.
Field flags¶
| Kind | Scalar flags | List flags (support --add-<f> / --remove-<f>) |
|---|---|---|
role | --displayName, --description | — |
org | --displayName, --type, --owner (a user), --parentOrg (an org) | — |
group | --displayName, --type, --ownerOrg (an org) | --roles |
user | --displayName, --email (→ primaryEmail), --state (planned/active/suspended/terminated) | --roles, --groups (→ memberOf) |
List flags accept a comma-separated value to replace the whole list (--roles "admin,user"), or --add-<field> / --remove-<field> (repeatable) to incrementally add/remove a member (set semantics — adds dedupe). Only the comma separates: a Group.name may contain internal spaces so that an Authentik-created group can be named, so --add-groups "authentik Admins" is one member, not two.
Examples:
identity-manager user list
identity-manager org show foo-company
identity-manager role add editor --displayName "Editor"
identity-manager user add jan --email jan@foo.nl --roles user --groups foo__users
identity-manager user modify jan --add-roles admin --remove-groups foo__users
identity-manager group delete foo__users # refused if any user is a member
identity-manager role delete editor --force # delete despite references
identity-manager user add jan --email jan@foo.nl --no-reconcile # stage, do not push
identity-manager reconcile # preview the plan (default)
identity-manager reconcile --apply # apply to the identity service
identity-manager user reset-password — a new way in for a user¶
A user who cannot sign in gets one of two things. --link (the default) prints a one-time link from Authentik's recovery flow: whoever opens it sets this user's password, so it is handed over like a key; it expires unused. It needs the recovery flow identity/update.sh makes (authentik-controller recovery-flow-ensure); without it the verb says so. --password-stdin sets the password that is the first line of stdin — 8 characters or more, never on a command line, never printed — which is how the web console's "Reset a user's password" sets a temporary password; the console's other way is the link. The user must exist in config/identities.
identity-manager user reset-password lars # the link, on stdout
printf '%s\n' "$pw" | identity-manager user reset-password lars --password-stdin
identity-manager bootstrap — bootstrap a minimal org¶
Copies minimal-org/ into config/identities/, substituting the placeholders (__ORG__ / __USER__ / __EMAIL__ / __ROOT_EMAIL__) in both filenames and contents. Pure file bootstrap — makes no identity calls (run identity-manager reconcile --apply afterwards). Native since the ADR-007 refactor Phase 8.2 (the former user-setup.sh is retired; the flags are preserved, with --people-dir folded into the manager's --config-dir).
identity-manager bootstrap --org <slug> --user <slug> --email <email>
[--config-dir <path>] # dest (default $TAPPAAS_CONFIG/identities)
[--minimal-org <path>] # source templates (default: the
# component's minimal-org/; env
# override PM_MINIMAL_ORG_DIR)
[--force] # overwrite a non-empty dest
[--skip-validate] # skip post-copy validation
Refuses a non-empty destination without --force, so install-time callers (rest-of-foundation.sh) stay idempotent — they skip the bootstrap once config/identities/ is populated. The result is validated for reference integrity (the identity-manager validate gate); exit 0 = success, 1 = error.
identity-manager validate — validate the People config¶
The manager's validate operation is now a native verb (ADR-007 — the convention end-state). It loads config/identities/ and checks reference integrity (the same validateRefs gate reconcile runs), report-only — no identity-service calls. Exit 0 = valid, 1 = reference errors.
The bash validate-people.sh (a deeper JSON-Schema gate against role-fields.json etc.) remains linked under its project-wide name for back-compat and schema-level checks:
Reports to the CMDB¶
identity-manager is a source of the CMDB (ADR-040 D4; cmdbSource in components.json). identity-manager report [--json] sends:
| Class | Key | What |
|---|---|---|
organization | name | displayName, desired |
role | name | displayName, description, desired |
group | Authentik uuid | displayName, roles, desired |
user | Authentik uuid | username, email, enabled, displayName, desired; member-of its groups |
Users and groups are reported only when Authentik answers (their key is its uuid, from authentik-controller's list-*); without it, organizations and roles only. A group's owning organization is not reported: the metamodel has no relation for it yet. A group's desired is its file; for a module's group { "file": "<module>.json", "key": "identity" }, for an Authentik built-in { "file": "identity.json", "key": "bootstrap" } (see Groups of three origins), so the sweep calls neither unmanaged. A group nothing declares has none. A user's desired is its file; for akadmin and an outpost's account the identity module's bootstrap (see Authentik's own users).
reconcile reports what it read; reconcile --apply and the write verbs report what they touched (a deleted user or group ends by its uuid, an organization or role by name); bootstrap reports the seeded organizations and roles.
report --discover (ADR-040 D15) adds what Authentik holds beyond people, from authentik-controller discover: authentik: {providers[], applications[], outposts[], flows[]} on the identity module's vm, a provider naming its flows by slug. Named fields only: no secret leaves Authentik.
A verb's change report carries the verb, the console's job (TAPPAAS_JOB_ID) and the actor (TAPPAAS_ACTOR, else the OS user; lib/ts job.ts). A report the CMDB cannot take is spooled in config/.cmdb-spool/ (lib/ts cmdb.ts) and never fails the verb; TAPPAAS_CMDB=off turns reporting off (the tests do). The tests check every payload against cmdb-controller's metamodel (lib/ts/test/cmdb-check.ts).