Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Party binding: bootstrap and migration

FerroEHR binds every person who logs in to a demographic PERSON, and a login with no PERSON is refused (403, refused-unbound). This page takes a new deployment from an empty database to its first bound login, and takes an existing deployment, whose people were attributed by login alone, to binding. The configuration it names is in Authentication & access, and the two commands are in CLI & production checklist. Every incompatible change of the release, with its upgrade step, is on Breaking changes of party binding.

No openEHR specification governs a deployment’s migration or its credential store: this is FerroEHR’s own design.

Who is a person

Every [[auth.basic.users]] entry is a person. It maps to the PERSON that carries its binding key, with [[authz.party_binding.basic_user]]:

[[authz.party_binding.basic_user]]
user = "clinician"
key_issuer = "urn:example:staff-login"   # the identifier_issuer of an [[auth.party]] table
key = "clinician"                        # the binding key the PERSON carries

A Basic user with no mapping refuses the start, naming the user. A machine, read-only included, authenticates with OAuth 2.0 client credentials and is granted in the CDR (Operational policy). A Basic credential carries no assurance level, so with [authz.assurance] minimum set it is refused on patient data, and the server logs a warn naming every mapped Basic user while no minimum is set.

Bootstrapping a new deployment

With Basic users persons only, a new deployment has no machine login to start from, so it starts in this order:

  1. Store the definitions the party mapping names. The server stores FerroEHR’s default demographic definitions as it boots, which the default mapping names. A mapping that names templates of your own needs them stored first: run ferroehr definitions load on them before the server starts, since boot refuses a mapping whose templates the store lacks.
  2. Grant the identity provider’s SCIM client. It is an OAuth 2.0 client-credentials client (RFC 6749 §4.4) of the deployment’s authorization server with the provisioning scope: an [[auth.issuer]] of kind machines issues its tokens, and ferroehr party-binding grant grants it scim_provision in the CDR with the scope as token_scope and the binding_issuer its Users’ keys are written under (The first grant).
  3. Provision the first person through /scim/v2/. The identity provider, or you through that client, sends POST /scim/v2/Users (RFC 7644 §3.3). FerroEHR creates the PERSON and its professional ROLE, and issues the PERSON’s id itself (RFC 7643 §3.1: the id “is always issued by the service provider”).
  4. Only then map a Basic user, by that person’s binding key. A Basic user mapped before its PERSON exists is refused at its first request.

The first administrator is a provisioned person whose token carries the administrator role from an issuer [authz.rbac] role_issuers lists.

The Docker Compose quickstart follows this path from an empty database: its ferroehr-provision one-shot takes a token for the quickstart-scim client and provisions the user ferroehr through /scim/v2/ once the server is healthy, and ferroehr is mapped by its key. The hosted sandbox does the same with its ferroehr-provision service after every nightly reset, and its reseed waits for the login to bind before it commits the demo data.

Migrating an existing deployment

An existing deployment attributes its people by login alone. It moves to binding in four steps, each with its check. Add the persons issuers last: from then on, every login with no PERSON is refused.

1. Prepare the existing persons

Bring every existing PERSON, for example those migrated from an earlier system, to a template of the party mapping, with the login identifier at the binding-key selector and the identity provider’s userName at its selector. Leave externalId to the identity provider, which issues it (RFC 7643 §3.1). A prepared PERSON performs no professional ROLE yet, so it does not bind.

Adopt them. ferroehr party-binding adopt gives each listed PERSON a professional ROLE of the mapping’s role template, with the PERSON as performer, and a new PERSON version listing it in roles, in one demographic CONTRIBUTION committed by the administrator you name, and writes one access record per adopted PERSON:

ferroehr party-binding adopt --admin <ADMIN_PARTY_ID> \
  --migration "<committer name of the migration>" <PARTY_ID>...

Under Docker Compose or the Helm chart, run it in the server’s container (Where the binary runs).

It refuses, naming them, every PERSON whose binding key was introduced by a committer the provenance rule does not accept (step 3), so a key a demographic writer planted before the upgrade is never adopted silently. Adopt before the first SCIM run: without the ROLE, the provider’s userName eq query finds no User and creates a duplicate.

At its next start, the server fills the binding side table from the party versions and refuses to start on any duplicate key, naming the parties.

2. Upgrade, then provision through SCIM

Check the upgraded configuration before the server starts on it with ferroehr config check, which runs the boot validation and touches no database (Where the binary runs shows it on the new image under Docker and for the configuration a Helm release refuses).

Start the upgraded deployment with only the SCIM client’s issuer configured; the persons issuers come in step 4, so no clinician meets a refusal while provisioning runs (for Microsoft Entra ID, the initial provisioning cycle). The provider’s filter=userName eq "..." queries find the existing persons whose keys are equal, so it updates them, writing their externalId, and creates only the professionals who have no PERSON yet. A bulk load through SCIM is the one sanctioned route.

3. Run the pre-flight

ferroehr party-binding check --admin <ADMIN_PARTY_ID> \
  --migration "<committer name of the migration>" \
  --expected assigned-users.txt

Under Docker Compose or the Helm chart, run it in the server’s container, with the --expected file at a path inside it (Where the binary runs).

ferroehr party-binding check reads the party versions and writes nothing, so it runs before any boot fill. Per key issuer it reports the persons that carry a key, duplicates, inactive and abandoned persons, the provisional persons older than provisional_report_after, the key-bearing persons that perform no professional ROLE (which adopt has not reached), and every mapped Basic user with the PERSON it binds.

For each key it reports the committer of the version that introduced the key, and fails unless that committer was a SCIM client (one whose ACTOR holds or held a scim_provision grant), an administrator you name, a migration you declare, or just-in-time creation on a persons issuer an [[auth.party]] table binds. A stored version records no role its committer held, so you name the administrators (--admin, --admin-key), and the report repeats them.

With --expected, it reads the identity provider’s list of assigned users (their login identifiers, exported from the provider, one per line) and lists every one with no PERSON. The command exits non-zero on a duplicate, a missing person or a key that fails the provenance rule.

4. Add the persons issuers

Add each persons issuer with its [[auth.party]] table. Every login with no PERSON is refused from then on; the warn lines and the binding_refusals metric show any the pre-flight missed.

Versions committed before binding

Versions are immutable, and nothing rewrites an AUDIT_DETAILS (RM Common master06-change_control_package.adoc §Committal and Audits), so every version committed before the upgrade keeps the committer it was committed with. Only versions committed after it name the bound PERSON.

Go-live prerequisites in other products

A deployment whose FerroBRIDGE facade or FerroFED gateway writes to FerroEHR adds its persons issuers only after the bridge and the gateway reach it under the caller; until then their writes are refused by the committer rule.

ProductWhat it needsRelease
FerroBRIDGEWrites to the CDR under the facade caller’s exchanged token (FerroHEALTH/FerroBRIDGE#1582)FerroBRIDGE v0.0.23
FerroFEDThe gateway reaches the CDR under the caller (FerroHEALTH/FerroFED#1615)none as of FerroFED v0.0.19; the issue’s FerroFED milestone is v0.0.20

No FerroFED release up to v0.0.19 reaches the CDR under the caller, so a deployment with a FerroFED gateway adds its persons issuers only once a FerroFED release carries that change (FerroHEALTH/FerroFED#1615).