Authentication & access
Who may call the server, what they may do once identified, and the surfaces
that are gated rather than always-on: [auth], [authz], [api] admin,
[auth.smart], [management], and [record.signing]. Precedence, the
environment-name grammar, and file discovery are on the
Configuration reference index.
[auth][authz][api] admin[auth.scim]- The access-delay register
[auth.smart][management][deployment][record.signing][record.versioning]
[auth]
Authentication: bearer tokens of one or more trusted issuers, Basic
credentials, or both. [auth] is the section every FerroHEALTH product shares,
checked by the ferrohealth-smart crate (0.9). FerroEHR is a resource server:
it checks tokens and never issues them. Every person a request comes from is
bound to a demographic PERSON (see [authz.party_binding]).
[auth]
enabled = true
[[auth.issuer]]
issuer = "https://keycloak.example.com/realms/staff"
kind = "persons"
profile = "keycloak"
audience = ["ferroehr"]
[[auth.party]]
issuer = "https://keycloak.example.com/realms/staff"
identifier_issuer = "urn:example:staff-login"
identifier_type = "uuid"
[[auth.basic.users]]
user = "clinician"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…$…" # never a plaintext password
[authz.rbac]
first_admin = "clinician"
A Basic user is a credential alone: user and its Argon2id hash
(password_hash or password_hash_file). What it may do is policy in the
CDR: the roles and scopes the hold_roles and hold_scopes grants of its
PERSON name (Operational policy).
[authz.rbac] first_admin names the one Basic user that holds admin_role
and the product scope from the configuration: the administrator who writes
the first policy parties. Which clients a person signs in through, which
clients and RFC 8693 actors act for a person, and which system clients need
no scope are grants on the client’s AGENT (sign_in_persons,
act_for_persons, access_without_scope), so the clients from the example
above sign in only once an administrator grants them.
Beside an [[auth.party]] table, a Basic user is a person’s credential and
must map to the key of its PERSON with [[authz.party_binding.basic_user]],
first_admin included; an unmapped one refuses the start. Until that
PERSON exists, the user’s requests are refused as unbound. Such a deployment
starts with the operator grant, never with first_admin: see
The first grant.
The section keys:
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Master switch. false = all requests pass unauthenticated (development only). With true and no mechanism configured the server refuses to start; see below. |
issuer | [[auth.issuer]] tables | none | The trusted issuers, one table each; see below. A flat issuer = "…" string is a type error at boot. |
tls | table | platform roots | [auth.tls], the family’s outbound TLS table: trust_roots_file, a PEM bundle of certificate authorities trusted in addition to the platform roots for an issuer behind a private PKI (every issuer’s metadata and key set are read trusting it), client_identity_file (one PEM holding a client certificate chain and its key) and min_version ("1.3" by default). An introspection grant’s calls use the grant’s own tls table. A file that cannot be read, holds no certificate, or does not parse refuses the start. |
realm | string | "" ⇒ ferroehr | The realm every WWW-Authenticate challenge names. |
capabilities | list of string | [] | SMART capabilities the discovery document adds: one SMART App Launch or the SMART on openEHR draft lists, or a full URI. |
scopes_supported | list of string | [] | The scopes the discovery document lists. Empty, it lists the scopes the route table honours. |
described_issuer | string | unset | The issuer the discovery document describes: one of kind persons, patients or federation whose metadata FerroEHR has, read from it, introspected, or supplied by [auth.smart] issuer_metadata_file. Read only with [auth.smart] discovery = true, where naming an unknown issuer, a machines issuer or one without metadata is a boot error. Required with discovery when more than one issuer could be described. It renders with any userinfo masked. See the described issuer. |
product_scope | string | "" ⇒ __ferroehr.platform | FerroEHR’s own scope. It admits the ADMIN API and, beside the clients the CDR grants access_demographic, the DEMOGRAPHIC API, the two surfaces no SMART on openEHR resource family covers. A full URI or a string starting with __ (SMART App Launch 2.2.0, Scopes and Launch Context, §Extensibility). |
The keys audience, algorithms, token_profile, clock_skew_seconds,
jwks_max_age_seconds, jwks_refresh_interval_seconds, jwks_file,
timeout_ms, mode, introspection, role_claims, acting_for_claim,
client_tokens and ca_file, which v5.6 read in [auth], are unknown keys
and refuse the start: the first ones live on each [[auth.issuer]] table,
the caller classification replaces acting_for_claim and client_tokens,
and [auth.tls] replaces ca_file.
[[auth.issuer]]: the trusted issuers
Each issuer’s metadata is read at boot, at the RFC 8414 §3 location first and
the OpenID Connect Discovery 1.0 §4 location after a 404, and with it the key
set at its jwks_uri, so an authorization server that cannot be reached
refuses the start. Every setting of an issuer lives on its own table. No two
issuers of one node share an audience, so one audience is one issuer and one
token form; the node’s audience must also differ from every other node’s, an
operator rule boot cannot see.
| Key | Type | Default | Description |
|---|---|---|---|
issuer | string | required | The issuer identifier: an https URL with no query, no fragment and no user name or password; plain http on a loopback host only. |
kind | persons, patients, machines or federation | required | Whose tokens it signs. persons signs the deployment’s own people (and the app-only tokens of its machines), patients tokens naming only the record subject, machines client credentials tokens only, and federation another party’s professionals or organisation. One issuer is one kind, so patients and professionals sign in at separate issuers, a realm or tenant each. |
profile | rfc9068, ferrosmart, entra, keycloak, okta or nl | rfc9068 | The preset of what the issuer’s tokens look like, each value labelled with its source in the crate; ferrosmart reads FerroSMART’s tokens (Behind FerroSMART). Every profile key below may be set on the table over it. Name each issuer in one table only: a second table of the same issuer refuses the start. |
audience | list of string | required | Accepted aud values; a token naming none of them is refused (RFC 9068 §4, RFC 8725 §3.9). |
algorithms | list of string | ["RS256","RS384","PS256","PS384","ES256","ES384"] | Accepted signature algorithms. Asymmetric only: an HS* algorithm is a boot error, and none is no algorithm at all (RFC 8725 §3.1, §3.2). |
clock_skew | duration | "60s" | Leeway on exp, nbf and iat. At most "5min". |
jwks_max_age | duration | "10min" | A key set older than this is read again. |
jwks_refresh_interval | duration | "1min" | A token naming an unknown kid reads the key set again at most once per interval. |
jwks_file | path | "" | A JWK Set of public keys handed over out of band, read instead of the issuer’s metadata. A symmetric key (kty: "oct") or a private-key member (d, p, q, dp, dq, qi, oth, k) is a boot error. An issuer read from a file has no metadata, so it serves the SMART discovery document only with [auth.smart] issuer_metadata_file set. |
timeout | duration | "10s" | One call to the authorization server. |
mode | jwt or introspection | jwt | How the issuer’s tokens are checked: as JWTs against its key set, or posted to its RFC 7662 endpoint (see Opaque tokens). |
role_claims | list of string | ["roles","groups","entitlements"] | Token claim paths the caller’s roles are read from; dotted paths walk nested claims, and a role is matched without regard to case. scope is not a role source. A federation issuer reads no role. Whether a role grants admin_role and the other privileged roles is [authz.rbac] role_issuers. |
sender_constraint | none or required | none | required admits only a token bound to a DPoP key (RFC 9449) or to the client certificate of a mutual-TLS connection (RFC 8705 §3). A token carrying cnf is held to it under either value. |
assurance | table | unset | The assurance level the issuer’s tokens carry, in the shape of [authz.assurance]. |
person_key | string | sub (preset) | The claim a person is bound by. email, phone_number, preferred_username and name are never accepted as a key (OpenID Connect Core 1.0 §5.7). |
act_represents_patient | bool | unset | On a patients issuer, read a token whose sub is the patient and whose top-level act (RFC 8693 §4.1) names someone else as that person acting for the patient. FerroEHR binds the actor by their login to a representative’s PERSON and admits them while that PERSON holds a live representation of the patient (Representatives in the patient portal); otherwise it refuses the token with 403 (refused-representation-unrecorded). Without the key, ferrohealth-smart refuses a patients token that carries act with 401. |
token_types, required_claims, scope_claim, app_only_scope_claim | preset | The token shape that replaces token_profile: the accepted typ values, the claims every token carries, and where its scopes are read. For an issuer that minted under token_profile = "jwt", set token_types = ["JWT"] and the required_claims its tokens carry. | |
client_claims, app_only, guest, impersonation_marker, expect, user_claims, person_equality, unstable_claims, max_actor_chain, representation, tenant_claim, adapter, onward_* | preset | The other profile keys of ferrohealth-smart: which claim names the client, what marks an app-only token or a guest, what refuses an impersonation, the claims a token must carry exactly, how a representative names whom it acts for, the claim naming the tenant, the vendor adapter (idp-entra) and the onward grants. |
[[auth.party]], [[auth.federation]], [[auth.attributes]], [auth.dpop] and [auth.idp.entra]
| Table | Description |
|---|---|
[[auth.party]] | One per persons issuer, keyed by issuer: where its logins are looked up. identifier_issuer and identifier_type (guid and uuid compare in lower case) name the identifiers the issuer profile’s person_key is matched against; group_claim with group_identifier_issuer reads the groups a token asserts; guests looks a guest up. Boot refuses a persons issuer without one, a table that sets claim (the profile’s person_key is the key), two tables sharing an issuer or an identifier_issuer, and a table whose identifier_type is the type of no [[authz.party_binding.person.template]] key: SCIM and just-in-time creation write the key under that type and the lookup compares the type exactly, so no login of the issuer would bind. |
[[auth.federation]] | One per federation issuer: how its tokens’ claims map to the fields of another party’s professional or organisation (mapping = "iua", "ehdsi" or per field), the countries, issuing authorities and provider prefixes that bound them, and contact_point for a MyHealth@EU contact point. fields maps a field to its claim ({ claim = "..." }) or authorization_details member, among them consent.reference, the consent decision reference of a consent-conditioned read, and correlation_id, the requester’s id a chained organisation request carries. |
[[auth.attributes]] | At most one per persons issuer, keyed by issuer: where its tokens state the professional’s attributes (mapping = "iua", the IHE IUA claims under extensions.ihe_iua, or per field in fields), and authorization_details_purposes, whether the purpose_of_use of each RFC 9396 authorization_details entry is a purpose of use too. Its purposes of use and roles go into each access record, and a [audit] purpose_header naming a purpose the token does not state refuses the request with 403. |
[auth.dpop] | The DPoP proof check of a sender-constrained issuer: max_age ("60s"), clock_skew ("10s") and algorithms. Each accepted proof is recorded in the database every replica shares until its window ends, so a proof is accepted once across all of them (RFC 9449 §11.1), and a database that cannot record it refuses the request with 503. A proof’s htu must name server.public_base_url, server.base_path and the request path, so the table needs that key. |
[auth.idp.entra] | The Microsoft Graph access of the idp-entra adapter, which an issuer turns on with adapter = "idp-entra" to read the groups of an Entra ID groups overage: base_url (https://graph.microsoft.com/v1.0), timeout ("2s"), max_response_size (a size), security_enabled_only and the client credentials of [auth.idp.entra.credentials]. An issuer naming the adapter without this table refuses the start. |
Warning
auth.enabled = truewith no mechanism is a boot error. Such a server could only refuse every request while advertising an authentication scheme it does not implement, which RFC 9110 §11.6.1 forbids: a401challenge must name a scheme applicable to the target resource. Configure anissuer, configure[[auth.basic.users]], or setauth.enabled = falsefor a development server.
The key-set fetches verify the identity provider’s certificate against the
platform trust store and follow no redirects. An identity provider whose
certificate comes from a private CA is trusted once that CA is in the image’s
system store or in a directory or file named by SSL_CERT_DIR or
SSL_CERT_FILE. A key set that cannot be read when a token needs it answers
503, never 401: the server cannot decide, and a 401 would tell a caller
with a valid token that its credential was refused.
A validated token must also carry a non-blank sub claim: the authenticated
subject is stamped into the audit trail, so a token without one is refused with
401 rather than recorded under a placeholder identity. A bearer token outside
the RFC 6750 §2.1 b64token alphabet is refused the same way, with 401 and
error="invalid_token".
Opaque tokens by introspection
An authorization server that issues opaque access tokens is served with
mode = "introspection" on its [[auth.issuer]] table, whose
[auth.issuer.introspection] table holds the keys below. Each bearer token is posted to the issuer’s
introspection endpoint (RFC 7662 §2.1), and the active response stands in for
the JWT claims: sub, scope, the roles of role_claims, aud against
audience and iss against the issuer. An inactive token is a 401. An
endpoint that cannot answer is a 503, because the server cannot decide. An
active response is reused until its exp, at most cache_max_age.
| Key | Type | Default | Description |
|---|---|---|---|
endpoint | URL | unset | The introspection endpoint; unset reads the introspection_endpoint of the issuer’s metadata. https, or http on a loopback host. |
cache_max_age | duration | "60s" | The longest an active response is used; "0s" caches nothing. |
cache_capacity | int | 10000 | The most responses held at once. |
client | table | unset | The client authentication of the call (RFC 7662 §2.1), with the keys of an outbound grant: client_id and client_secret, private_key_jwt or mutual TLS (see the grant keys). |
bearer | table | unset | A client credentials grant whose token authorizes the call instead (SMART App Launch 2.2.0, Token Introspection). Exactly one of client and bearer. |
[[auth.issuer]]
issuer = "https://idp.example.org/realms/ferroehr"
kind = "persons"
audience = ["ferroehr"]
mode = "introspection"
[auth.issuer.introspection.client]
client_id = "ferroehr-rs"
client_secret_file = "/run/secrets/introspection-client"
The Basic-auth user store
[[auth.basic.users]] is an array of tables. A Basic user is always a
person: it maps to the PERSON carrying its binding key through
[[authz.party_binding.basic_user]], and a Basic user
with no mapping refuses the start, naming the user. A machine authenticates
with the client credentials grant (RFC 6749 §4.4), and a system/ scope on a
Basic user refuses the start.
| Key | Type | Default | Description |
|---|---|---|---|
user | string | required | The user-id. Empty, or with a colon or a control character, is a boot error (RFC 7617 §2). |
password_hash | secret | required | Argon2id PHC hash ($argon2id$v=19$…), never a plaintext password. Boot-validated against the OWASP floor; see below. |
password_hash_file | path | unset | Read the hash from a file instead, for a mounted secret. A hash is an offline cracking target, so prefer this wherever the configuration file itself is not treated as sensitive. Exactly one of the pair is required. |
scopes | list of string | [] | The SMART on openEHR scopes the user holds, checked on every route exactly like a token’s scope claim. A user bound to a PERSON also holds the scopes of its hold_scopes grants (What the grants decide). A user with none is refused everywhere a requirement applies. |
roles | list of string | [] | The user’s RBAC roles, upper-cased on authentication. A user bound to a PERSON also holds the roles of its hold_roles grants, never a privileged one. A user with none holds no role and is refused wherever [authz.rbac] asks for one. |
[auth.basic] itself takes one key beside the users:
| Key | Type | Default | Description |
|---|---|---|---|
cache_ttl | duration | "5min" | How long a credential that verified is kept, so a repeat request skips the Argon2id derivation; "0s" turns the cache off and checks every request. The entry is named by a keyed hash of user-id:password under a key drawn at boot, never the password, and only a credential that verified is kept, so a wrong password always pays the derivation. The cache holds at most 4096 credentials and empties at a restart. The user list and its hashes are read at boot, so removing a user or changing a password takes effect at the restart that loads the new list, which also empties the cache: the TTL never keeps a removed user working. Argon2id is slow by design, so with the cache off its cost bounds how many Basic requests a core can answer. |
Warning
Every
password_hashmust meet the OWASP Argon2id floor:m>=19456(19 MiB),t>=2,p>=1, algorithmargon2id. Anything weaker (or a non-argon2idPHC string, or an unparsable one) is a boot error naming the user. This is checked at startup because the verifier takes its cost parameters from the stored hash, so a deliberately cheap hash would otherwise verify happily and silently weaken every password in the store. The floor is the OWASP Password Storage Cheat Sheet §Argon2id minimum.
An unknown user-id is checked against a decoy hash of the same cost, so the time a refusal takes does not say whether the user exists.
[authz]
Role-based (RBAC) authorization, the party binding, the grant ceiling and the
patient-data assurance gate. Which caller may read which data is the access
evaluator’s, over each EHR’s access_directives and the controller’s access
policy, and takes no key here. The full evaluation order and design rationale are
in Security.
[authz.assurance]: the assurance level patient data requires
Off by default. What it refuses and the 401 challenge it sends are described
in Security.
| Key | Type | Default | Description |
|---|---|---|---|
claim | string | acr | The token claim carrying the authentication context class; a dotted path reaches into a JSON object. |
levels | table of string → low | substantial | high | empty | Maps each value your identity provider puts in claim to an eIDAS level of assurance. A value the table does not name carries no level. File-only: the keys are usually URIs. |
minimum | low | substantial | high | unset | The level a patient-data request must carry. Unset refuses nothing. |
[authz.assurance]
minimum = "substantial"
[authz.assurance.levels]
"http://eidas.europa.eu/LoA/substantial" = "substantial"
"http://eidas.europa.eu/LoA/high" = "high"
Boot refuses a minimum with an empty levels table or with no value mapped at
or above it (every patient-data request would be refused), a blank claim
beside a declared table, and a levels value that is blank or carries
whitespace, a quote or a backslash, because the refusal names the accepted
values in one quoted, space-separated acr_values parameter (RFC 9470 §3).
A Basic credential carries no level, so with minimum set every Basic user,
mapped to a person or not, is refused on patient data. While minimum is unset
and a Basic user is mapped in [[authz.party_binding.basic_user]], boot logs a
warn naming those users.
The access record carries the acting mode and the professional the caller
classification names; see Audit trail.
[authz.professional] is refused at boot: the issuer’s kind and profile
classify the caller, and a client acting for a person is one the CDR grants
act_for_persons.
[authz.party_binding]
How a person is attributed. There is no switch: binding is how FerroEHR
attributes a person, and enabled is refused at boot.
| Key | Type | Default | Description |
|---|---|---|---|
provider | { issuer, id }, or [[authz.party_binding.provider]] tables | required once [auth] admits a credential | The healthcare provider this deployment acts for, as an identifier issuer and id (in the Netherlands the URA). Every access record of a bound or provisional person and every version a person commits name it (EHDS Art. 13(4), Annex II 3.2(a)). A deployment that serves several providers declares one table per value of its issuers’ tenant_claim (tenant, issuer, id) instead; the two forms cannot be combined, and a bound issuer that names no tenant_claim is refused beside the table form. |
namespace | string | demographic | The PARTY_REF.namespace a bound party is written under, the value of the ITS-REST overview example (committer.external_ref.namespace="demographic"), held to the OBJECT_REF.namespace pattern [a-zA-Z][a-zA-Z0-9_.:/&?=+-]*. |
basic_user | [[authz.party_binding.basic_user]] tables | [] | One per Basic user: user, key_issuer (the identifier_issuer of an [[auth.party]] table) and key, the binding key the user’s PERSON carries. A Basic user with no table, a table naming no Basic user and a key_issuer no table names refuse the start. |
issuer | [[authz.party_binding.issuer]] tables | [] | How the tokens of one persons issuer are read when a first login creates a provisional PERSON; see Just-in-time creation. |
provisional_report_after | duration | "30d" | The age past which ferroehr party-binding check reports a provisional PERSON. |
[authz.party_binding]
provider = { issuer = "urn:oid:2.16.528.1.1007.3.3", id = "12345678" }
[[authz.party_binding.basic_user]]
user = "clinician"
key_issuer = "urn:example:staff-login"
key = "3f2b0c1e-0000-4000-8000-000000000001"
The party mapping
SCIM provisioning, just-in-time creation and the login binding read and
write the same demographic parties under one mapping. It names the
templates each party is valid against, the identifier selectors of the
binding key, userName and externalId, and where each SCIM attribute and
OpenID Connect claim goes. Names go in PARTY.identities and identifiers
in PARTY.details (RM demographic §Names and Addresses, §Party
Identification), and boot refuses a name mapped into details or an
identifier mapped into identities. No openEHR specification governs this
mapping: it is FerroEHR’s own design, and its targets are RM demographic
paths.
| Section | Keys | Description |
|---|---|---|
[[authz.party_binding.person.template]] | template_id, key, user_name, external_id, default | One per template a professional’s PERSON may use, so a migrated template can stay beside a new one. key, user_name and external_id are selectors, each { path, type }: the path of the ELEMENT holding the DV_IDENTIFIER and its type. Every identifier can sit at one path (the repeated element of an identifier cluster), so two selectors at one path are told apart by type, and the key by its issuer, the identifier_issuer of an [[auth.party]] table. Exactly one table sets default = true: SCIM and just-in-time creation create new persons with it. |
[[authz.party_binding.person.attribute]] | scim, oidc, jit, name, path | One per mapped value: a SCIM attribute path (the RFC 7644 valuePath form, emails[type eq "work"].value, and the FerroEHR extension urn:ietf:params:scim:schemas:extension:ferrohealth:2.0:User:loginIdentifier that feeds the binding key), an OpenID Connect claim, whether just-in-time creation writes it (jit, default false), whether it is the name the committer reads (name, at most one), and path, one path per template id. id, schemas, meta, active, userName and externalId are SCIM’s own and are never mapped. |
[authz.party_binding.professional_role] | template_id | The template of the professional ROLE, rooted at ROLE. A PERSON is a professional while it lists a ROLE of this template that names it as performer, is complete or incomplete, and whose time_validity holds today. |
[authz.party_binding.group] | template_id, external_id, display_name | The template of a SCIM Group’s GROUP, its externalId selector and the path of its displayName. |
[authz.party_binding.membership] | archetype_id | The PARTY_RELATIONSHIP archetype of a group membership, as each membership’s archetype_node_id carries it (the interface form of an ADL 2 id, openEHR-DEMOGRAPHIC-PARTY_RELATIONSHIP.membership.v1). SCIM serves /Groups when the group table names a display_name and this table is set. |
[authz.party_binding.patient] | template_id, identifier, name | The template of a patient’s PERSON, the subject of an EHR and the target of a representation: the path of the ELEMENT holding its identifiers (each a DV_IDENTIFIER of any type and issuer) and the path of its name. A PERSON written under this template is validated against it. |
With no mapping key set, every section maps FerroEHR’s default demographic definitions, which the server stores as it boots when the definition store holds no definition of their id. An empty configuration has this mapping:
[[authz.party_binding.person.template]]
template_id = "openEHR-DEMOGRAPHIC-PERSON.healthcare_professional.v1.0.0"
default = true
key = { path = "/details[id2]/items[id3]", type = "login" }
user_name = { path = "/details[id2]/items[id3]", type = "scim_user_name" }
external_id = { path = "/details[id2]/items[id3]", type = "scim_external_id" }
[[authz.party_binding.person.template]]
template_id = "openEHR-DEMOGRAPHIC-PERSON.patient.v1.0.0"
key = { path = "/details[id2]/items[id3]", type = "login" }
user_name = { path = "/details[id2]/items[id3]", type = "scim_user_name" }
external_id = { path = "/details[id2]/items[id3]", type = "scim_external_id" }
[[authz.party_binding.person.attribute]]
scim = "name.formatted"
name = true
path = { "openEHR-DEMOGRAPHIC-PERSON.healthcare_professional.v1.0.0" = "/identities[id4]/details[id5]/items[id6]", "openEHR-DEMOGRAPHIC-PERSON.patient.v1.0.0" = "/identities[id6]/details[id7]/items[id8]" }
[[authz.party_binding.person.attribute]]
scim = "name.givenName"
path = { "openEHR-DEMOGRAPHIC-PERSON.healthcare_professional.v1.0.0" = "/identities[id4]/details[id5]/items[id7]", "openEHR-DEMOGRAPHIC-PERSON.patient.v1.0.0" = "/identities[id6]/details[id7]/items[id9]" }
[[authz.party_binding.person.attribute]]
scim = "name.familyName"
path = { "openEHR-DEMOGRAPHIC-PERSON.healthcare_professional.v1.0.0" = "/identities[id4]/details[id5]/items[id8]", "openEHR-DEMOGRAPHIC-PERSON.patient.v1.0.0" = "/identities[id6]/details[id7]/items[id10]" }
[[authz.party_binding.person.attribute]]
scim = 'emails[type eq "work"].value'
path = { "openEHR-DEMOGRAPHIC-PERSON.healthcare_professional.v1.0.0" = "/contacts[id9]/addresses[id10]/details[id11]/items[id12]" }
[authz.party_binding.professional_role]
template_id = "openEHR-DEMOGRAPHIC-ROLE.healthcare_professional.v1.0.0"
[authz.party_binding.group]
template_id = "openEHR-DEMOGRAPHIC-GROUP.care_team.v1.0.0"
external_id = { path = "/details[id2]/items[id3]", type = "scim_external_id" }
display_name = "/identities[id4]/details[id5]/items[id6]"
[authz.party_binding.membership]
archetype_id = "openEHR-DEMOGRAPHIC-PARTY_RELATIONSHIP.membership.v1"
[authz.party_binding.patient]
template_id = "openEHR-DEMOGRAPHIC-PERSON.patient.v1.0.0"
identifier = "/details[id2]/items[id3]"
name = "/identities[id6]/details[id7]/items[id8]"
The template ids are the ADL 2 ids of the stored archetypes, and the
membership archetype is named in the interface form each membership’s
archetype_node_id carries. The patient template is a person template too,
never the default: a patient portal’s SCIM client provisions its
representatives in it (Users). A representation needs no section: FerroEHR
recognises it by the code it carries, in any archetype (see
Representatives in the patient portal). The default
key is of the type login, so an [[auth.party]] table whose
identifier_type is login needs no mapping key.
A section you set replaces that section’s default whole: a deployment that
sets [[authz.party_binding.person.template]] maps its own attributes too.
A deployment with templates of its own sets the sections that name them and
stores its templates before boot (ferroehr definitions load); the server
stores nothing under its ids, and still stores the default definitions,
which no section of its mapping then names.
A worked example over the default definitions, with the Microsoft Entra object id as the binding key. It sets the person section, and every other section keeps its default:
[[authz.party_binding.person.template]]
template_id = "openEHR-DEMOGRAPHIC-PERSON.healthcare_professional.v1.0.0"
default = true
key = { path = "/details[id2]/items[id3]", type = "guid" }
user_name = { path = "/details[id2]/items[id3]", type = "scim_user_name" }
external_id = { path = "/details[id2]/items[id3]", type = "scim_external_id" }
[[authz.party_binding.person.attribute]]
scim = "name.formatted"
oidc = "name"
jit = true
name = true
path = { "openEHR-DEMOGRAPHIC-PERSON.healthcare_professional.v1.0.0" = "/identities[id4]/details[id5]/items[id6]" }
With Microsoft Entra ID, map the object id to externalId (Entra’s
matching) and to the binding-key attribute (the binding): two attributes,
two selectors. The key’s [[auth.party]] identifier_type is guid, so a
key differing only in case binds one login.
Boot refuses, naming the key: no or two default tables; a selector path
that does not compile; two equal selectors; any selector under the Dutch
BSN namespace (OID 2.16.840.1.113883.2.4.6.3); a key fed by an email
address, a phone number, preferred_username, name, upn or
unique_name; a template that is absent, rooted at another class or lacks
a mapped path; and a path whose type cannot carry its source. Deleting a template
the mapping names is refused with 409.
The parties the binding relies on are protected: a PERSON of a mapped
template carrying a selector identifier, its professional ROLE, a
representation relationship (one carrying openehr_access::represents),
and a GROUP of the group template. Only an
administrator (authz.rbac.admin_role) writes one through the demographic
API, including the creation of a party that carries a selector identifier;
the patient a representation of its own targets writes that one too.
The policy parties (a party holding a capability coded in
openehr_access, an acts-for relationship or a client_id identifier)
are recognised by what they hold and take no key of this mapping; they are an administrator’s to write and to read,
never a SCIM client’s: see Operational policy.
An administrator’s version that leaves a protected identifier out is refused
with 422. A present binding key is immutable (RFC 7643 §2.2): a version
that changes it is refused with 403, and
POST /admin/party/binding-key is the one
change. Each selector value binds one live party: a commit that gives a
binding key, a userName (compared after RFC 8265 width mapping, lower case
and NFC), an externalId or a group displayName a second party is refused
with 409. A deleted PERSON leaves its key as a tombstone that refuses
the login until an administrator binds the key again.
Changing the mapping
The side table is filled from the configured mapping and the party
versions. The first boot fills it and stores the mapping’s digest, which
covers the templates, the selectors, the role, the group and the membership.
It leaves out the key issuers: the identifier_issuer of each
[[auth.party]] table and each patients issuer. Each running replica holds
a lease it renews every 20 seconds, and the lease lists the key issuers the
replica derives keys for.
Adding or removing a key issuer needs no stop and no refill. Each key issuer is a key space with a state:
| State | Its keys bind a login | What happens next |
|---|---|---|
pending | No: the login is answered 503 with a Retry-After | Once every live replica names the issuer, a replica fills its keys from the party versions |
filling | No: 503 with a Retry-After | The fill runs online in pages and the issuer turns active |
active | Yes | A replica that starts without the issuer turns it retiring |
retiring | No: the login is refused with 403 refused-unbound | Once no live replica names it, its keys are deleted; once every live replica names it again, it is filled anew |
So a rolling upgrade that adds a patients issuer serves every other issuer
throughout, and the new issuer’s logins bind on every replica once the last
replica without it is replaced. A replica restarted without an issuer stops
that issuer’s logins binding on every replica at once, so revoking an issuer
needs no downtime. Changing whether an issuer is a patients issuer runs as
a removal followed by an addition. A fill that finds two parties carrying one
key under the new issuer keeps it pending, logs both parties, and looks
again after five minutes; the other issuers keep binding.
A change to the templates, selectors, role, group or membership is a stop-the-world step. A replica whose mapping digest differs from the stored one refuses to start, naming both digests:
- Stop every replica. With Helm, scale the deployment to zero first: a rolling upgrade would start new replicas beside old ones.
- Run
ferroehr party-binding refillwith the new configuration. It refuses while a replica’s lease was renewed within the last minute, and refuses a store in which two parties carry one selector value, naming both. - Start the replicas with the new mapping. A replica still holding the old mapping refuses to start.
How a login is looked up
Every request of a person is looked up in the binding side table of the
party store, on the party database role, with no cache, so a change to a
party takes effect on the next request on every instance. The table holds
the binding key of each PERSON of a mapped template that performs a
professional ROLE (a ROLE of the mapped role template that its roles
list, that names it as performer, whose state is complete or
incomplete and whose time_validity holds today’s date in UTC) or that
is the source of a representation relationship, inline or of its own. A key of type guid or
uuid is compared in lower case. The table is written in each party
commit’s transaction and can be rebuilt from the party versions alone.
The request is refused with 403 and the binding code in the problem body
when the login matches two parties (refused-ambiguous), when its party is
inactive (refused-inactive) or abandoned (refused-abandoned), when
its key belongs to a deleted party (refused-deprovisioned), when the token
carries no key claim (refused-key-claim-missing), when the party lacks the
marker the caller’s kind needs (refused-wrong-marker), when the groups a
token asserts cannot be read (refused-groups-unavailable), when a guest
comes from an issuer whose table does not set guests (refused-guest), and
when a representative’s token names a subject its party has no live
representation relationship to (refused-representation-unrecorded). A party
store or an identity provider that cannot answer is answered 503, with
Retry-After when the identity provider gave one.
A person whose login matches no party is refused with 403 and
refused-unbound on every request, reads and writes alike; only the public
endpoints outside the auth layer answer. The problem names the identifier
issuer to provision the person under, and the refusal of a token without the
key claim names the missing claim instead. No setting serves an unbound person
under a login-only committer, so provision every professional (through
SCIM or the demographic API) before you add a persons issuer, or
let the issuer create a provisional PERSON at the first login
(just-in-time creation). Each
refusal writes one warn line naming the issuer and the outcome, never the
claim value, and counts into the binding_refusals metric by issuer and
outcome.
A representative reaches only the EHR whose EHR_STATUS.subject.external_ref
names the subject it represents: the issuer’s representation claim carries
the subject’s party id, matched without regard to case, and the subject must
be the target of one of the representative’s live relationships, so a
representative of an issuer no [[auth.party]] table binds is refused. The
access evaluator holds every request that names an EHR to that EHR, whatever
the token’s scopes cover, and refuses any other with 403
refused-not-represented; a query must name it with ehr_id, and an
operation that names no EHR is refused the same way. Templates stay
readable. A persons token whose only clinical scopes
are patient/ is a professional confined to its launch EHR, and its commits
record the professional, never PARTY_SELF. A representative signing in
through a patients issuer is bound by FerroEHR itself, with no
[[auth.party]] table: see Representatives in the patient portal.
Just-in-time creation
Just-in-time creation lets a professional with no party work under their own
account at their first login, before SCIM or an administrator completes the
record. When a login of a persons issuer matches no party, and a
create_at_login grant in the CDR admits it, FerroEHR commits one PERSON
of the default template with lifecycle state 553|incomplete|, which RM
common §Incomplete Content allows for “incomplete demographic details”, and
its professional ROLE in the same demographic contribution, then serves the
request bound to it. The next request binds to that PERSON and creates
nothing. When a login creates a party is FerroEHR’s own design: no openEHR
specification governs it.
Which logins are created is operational policy, so it is CDR data and no
configuration key: an administrator writes a ROLE whose capability grants
openehr_access::create_at_login, naming the issuer and the admission
conditions, through the Demographic API. The grant is read on each first
login, so a change applies to the next one without a restart. The
Operational policy page
documents the grant and has a worked example. [authz.grants] allowed
must list create_at_login, which the default does not, or no such grant
can be written or honoured.
The [[authz.party_binding.issuer]] table only says how an issuer’s tokens
are read, and an issuer without one reads the defaults:
| Key | Type | Default | Description |
|---|---|---|---|
issuer | string | required | A persons issuer an [[auth.party]] table binds. |
user_name_claim | string | the profile’s person_key | The claim the userName is read from. It must be one the issuer controls: an email address, a phone number, preferred_username, name, upn and unique_name refuse the start. |
idp_claim | string | idp | The dotted claim path an admit_idp condition reads the identity provider from (the Microsoft Entra idp claim). |
Creation also needs a default person template with a user_name selector,
[authz.party_binding.professional_role], and an attribute that maps an
OpenID Connect name claim (name, given_name, family_name,
middle_name or nickname) to the default template. The default mapping
has them. When a grant admits a login and the mapping lacks one, the login
is not created and the server logs what is missing.
[[authz.party_binding.issuer]]
issuer = "https://login.microsoftonline.com/<tenant-id>/v2.0"
user_name_claim = "oid"
What it writes is the attribution minimum: the binding key, the userName
and the name claims the token carries. Any other mapped attribute is written
only where its [[authz.party_binding.person.attribute]] sets jit = true
(GDPR Art. 25(2), data protection by default), and externalId is never
written, since RFC 7643 §3.1 leaves it to the provisioning client. The
version is committed with change type 249|creation|, a description naming
just-in-time creation and the issuer, and the person’s own committer: the
name, the login identifier and an external_ref naming the new PERSON.
FerroEHR reads every value from the access token only (RFC 9068 §2.2.2), so
the issuer must put the name claims in the access token.
It runs only for a person or a delegated caller of the issuer, never for a
representative, a patient, a system or a federation caller, and never for a
login whose outcome is anything other than unbound: an ambiguous, inactive,
abandoned or deprovisioned party, a token without the key claim and a party
with the wrong marker are refused as before. A PERSON a SCIM client deleted
is never created again by a later login, whatever the identity provider still
issues. A login that no grant in force admits, or whose token carries no
mapped name claim, is refused with 403 and refused-unbound. A guest is
created only under a grant whose admit_guests is true, and only when the
issuer’s [[auth.party]] guests admits it.
Concurrent first requests of one login commit one PERSON: the binding key’s
unique index refuses the second commit, and that request binds to the first
one’s PERSON. A login whose userName another party already holds is
refused with 403 and binds nothing. Just-in-time creation only creates: it
never updates, deactivates or deletes a PERSON, so a later login with
changed claims changes nothing.
A PERSON whose latest version is incomplete is provisional. The access
record of each of its requests carries binding = provisional, a demographic
read and an AQL query over VERSION/lifecycle_state show it, and
ferroehr party-binding check reports the provisional persons older than
provisional_report_after under side_table.provisional. What a provisional person may do is decided by
their SMART scopes and roles, as for anyone. A SCIM client whose
binding_issuer is the issuer’s identifier_issuer completes the PERSON:
it finds it by userName, with a binding key equal to its own, writes the
externalId with a PATCH, and a complete PUT completes it. SCIM
active = false abandons it.
The lawful basis for the attribution minimum (key, userName, name) is GDPR
Art. 6(1)(c): EHDS Art. 13(4) and the logging duties need the professional
identified. An operator who opts a contact attribute in with jit = true
names its own basis, Art. 6(1)(b) or (f). Because the data come from the
identity provider and not from the person, tell the professionals what Art. 14
asks: what is copied, from which source, and why. On a realm or tenant that
creates persons, make the name attributes administrator-controlled, as the key
is; Enterprise identity providers
shows the settings per identity provider.
Imports and system clients
The systems whose wrapped committers an import may carry are no key: a
creating_system element of the importer’s import grant names each one
(What the grants decide).
The system clients are not configuration. An OAuth client-credentials client
is granted what it may commit, import or export in the CDR, as an ACTOR
carrying its client_id that acts for a provider and performs a ROLE whose
capabilities grant the operations; see
What a system client may do.
The former [[authz.system_client]] table is an unknown key and refuses the
start.
Federation agreements
A federation agreement is CDR data, not a configuration key: a grant of
federated_person_access or federated_organisation_access on the partner’s
party, read on every request and judged when it is written. The configuration
keeps what the agreements are judged against: the federation issuers, their
[[auth.federation]] tables, [authz.grants] allowed (which must name both
codes before an agreement can be written). The period a chained agreement
is held to is the access log retention of the controller’s access policy
(ACCESS_POLICY.log_retention). The model, the codes and the rules are on
Operational policy. The
[[authz.federation.agreement]] table is removed, and a configuration that
still holds it is refused at boot as an unknown key.
[authz.grants]
| Key | Type | Default | Description |
|---|---|---|---|
allowed | list of operation codes | ["commit_composition"] | The operations of the openehr_access terminology the policy grants may grant. A ROLE committed with a capability that codes an operation this list does not name is refused with 403, and one already stored is never honoured, so a compromised administrator account grants no more than you allow. An empty list lets the party store grant nothing; an unknown code refuses the start. Environment: FERROEHR__AUTHZ__GRANTS__ALLOWED, comma-separated. The codes and how a request reads its grants are on Operational policy. |
[authz.rbac]
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | The coarse role gate (active when authentication is enabled). Off, every authenticated caller may use every enabled surface, reported as the rbac_off deployment gap. ehr_access_default and admin_role apply either way. |
admin_role | string | ADMIN | Role required for admin-class operations. A blank value is a boot error. |
readonly_role | string | READONLY | Role marking a principal read-only: refused on every write operation (create/update/delete/upload), even alongside granting roles. Reads and AQL queries are still allowed. |
emergency_access_role | string | unset | Role that, when the caller also declares one of [audit] emergency_purpose_codes, reads data an EHDS Art. 8 restriction, a consent deny or a controller deny rule covers where its emergency_override holds, and passes the sensitivity, care relationship and default steps (EHDS Art. 11(5)); the access record then carries the emergency mark. Unset, nobody may override a restriction. See access directives. |
role_issuers | list of string | [] | The persons issuers whose role claims may grant admin_role and emergency_access_role. A token of any other issuer never holds them, a Basic user keeps the roles its own table grants, and a hold_roles policy grant never gives one. An issuer of another kind refuses the start. Empty, no token grants them. |
ehr_access_default | enum{open,restricted} | open | What an EHR carrying no ACCESS_CONTROL_SETTINGS admits. restricted is object-level default-deny: only admin_role reaches a setting-less EHR, so an operator can still author the settings that open it. It is enforced whether enabled is on or off. With [auth] enabled = false nothing could enforce restricted, so that combination is a boot error. See Security. |
Reading one subject’s access log, acting as an EHDS Art. 10 access service,
and importing an EHR or an extract have no key here: each is a grant in the
CDR (read_subject_audit, access_service, import_ehr and
import_ehr_extract),
under [authz.grants] allowed. The keys that named a role for them before
5.7.1 are unknown keys, and the server refuses to start with one
(What the grants decide).
Note
The management surface is not configured under
[authz.rbac].[management.endpoints]owns it, one level per endpoint, with no global default beside it: an endpoint you do not name isoffand is not mounted. Only theadmin_onlylevel consultsauthz.rbac.admin_role.
[api] admin
| Key | Type | Default | Description |
|---|---|---|---|
admin | bool | false | Mount the ADMIN API (physical, irreversible delete). Off ⇒ every admin route answers 405 Method Not Allowed with an empty Allow header, never 403, and never touches the backend. |
Physical deletion is irreversible, so the group stays off by default. With it
on, /admin also joins the group list the OPTIONS System-Options manifest
advertises, so the manifest never names a group that answers 404.
[auth.scim]
FerroEHR is a SCIM 2.0 service provider (RFC 7644) at /scim/v2/, the
endpoint an identity provider provisions each professional through. It is off
by default.
| Key | Type | Default | Description |
|---|---|---|---|
filter_max_results | integer | 100 | The most resources one list response returns, which ServiceProviderConfig declares as filter.maxResults. At least 1. |
max_deactivations | integer | 100 | The most Users one client deactivates or deletes per window. Past it, a deactivation or deletion is 429 with Retry-After and logged at error. The count is kept in the database, so every replica shares one bound. At least 1. |
deactivation_window | duration | "1h" | The length of that window. At least "1min". |
contact_erasure_delay | duration | "0s" | How long after a User’s deletion the contacts of every version of its PERSON are erased (GDPR Art. 17). "0s" erases them in the deletion itself; at most "30d". |
max_group_members | integer | 5000 | The most members one Group holds. An add past it is 400 invalidValue. A membership change versions only the member’s PERSON, so its cost does not grow with the Group. At least 1. |
Who provisions is CDR data, read on every request: a provisioning client is
an OAuth client-credentials client of your own authorization server (an
[[auth.issuer]] of kind machines) whose ACTOR holds a scim_provision
grant in force. The grant’s binding_issuer is the identifier issuer of the
binding keys the client provisions: the identifier_issuer of an
[[auth.party]] table for a client of your professionals, or a patients
issuer for a patient portal’s client, which provisions the portal’s
representatives. Its token_scope is the scope a token of the client
must hold; SMART on openEHR defines none for SCIM, so the value is yours to
choose. Each User belongs to the one client whose binding_issuer issues its
key, so no two clients’ grants name one. [authz.grants] allowed must admit
scim_provision. The first such grant is written with
ferroehr party-binding grant,
since no administrator can log in before the persons it provisions exist;
Operational policy has the
grant’s terms.
Every meta.location and discovery document names the resource by its URI
(RFC 7643 §3.1), under <public_base_url>/scim/v2 with
server.public_base_url
and server.base_path, so the table needs that key.
The table’s presence turns the endpoint on; it has no enabled key, and
setting one refuses the start. The start is refused when the table is present
without server.public_base_url, and when the party mapping
lacks what a User is written with: a default person template with a
user_name selector, and [authz.party_binding.professional_role].
[server]
public_base_url = "https://cdr.example.com"
[auth.scim]
[authz.grants]
allowed = ["commit_composition", "scim_provision"]
/scim/v2/ServiceProviderConfig answers without a token, so a client can read
the authentication scheme before it holds one. Every other path needs a
bearer token of a client that acts for nobody and holds a scim_provision
grant in force:
- no token, or one that does not verify, is 401 with
WWW-Authenticate: Bearer; - a person’s token, a client with no grant in force, a grant whose
binding_issueris neither theidentifier_issuerof an[[auth.party]]table nor apatientsissuer, or another client’s grant names too, and a token without the grant’stoken_scopeare 403, the last withWWW-Authenticate: Bearer error="insufficient_scope"(RFC 6750 §3.1).
Every refusal is an RFC 7644 §3.12 Error message in application/scim+json.
The client’s requests count against
[server.caller_rate] like any caller’s, so each
replica gives the client an allowance of its own, and past it a request is
429 with Retry-After. /scim/v2/Schemas serves the core User schema
reduced to userName, active and the SCIM attributes
[[authz.party_binding.person.attribute]] maps, and FerroEHR’s extension
urn:ietf:params:scim:schemas:extension:ferrohealth:2.0:User with
loginIdentifier, the attribute that feeds the binding key. /ResourceTypes
lists the User type at /Users, and the Group type at /Groups with
FerroEHR’s Group extension
urn:ietf:params:scim:schemas:extension:ferrohealth:2.0:Group and its
immutable boolean careTeam when Groups are served. Both extension URNs take
the form Microsoft Entra ID requires of a custom attribute, in the
urn:ietf:params:scim namespace without a registration (RFC 7643 §10.2.1).
Users
A User is a PERSON of the default person template performing the
professional ROLE. A patient portal’s client, whose binding_issuer is a
patients issuer, provisions the portal’s representatives instead: each
User is a PERSON of the [authz.party_binding.patient] template, which a
[[authz.party_binding.person.template]] must name too, with no ROLE,
and its binding key is the representative’s portal login. SCIM provisions
the identity only. The representation that lets the person act for a
patient is written by the patient or an administrator (Regulation (EU)
2025/327 Art. 4(2)), and a version from the client that adds, changes or
drops one is refused 403. Until a live representation exists, the login
reaches nothing (Representatives in the patient portal).
This is FerroEHR’s own design. The client serves these operations (RFC 7644 §3):
POST /scim/v2/Userscreates thePERSONand itsROLEin one demographic CONTRIBUTION, under the client as committer, and answers 201 with the User, itsLocationand itsETag. The body carriesuserNameand the binding key inloginIdentifier;externalIdand every mapped attribute are optional. A version that fits its template in full iscomplete, and one that fits only with every lower limit at zero isincomplete, which the User’slifecycleStateandmissingPathsname. A User created withactive = falseis 400invalidValue.GET /scim/v2/Users/{id}answers the User with itsETag, the weak tag of its version, and 304 to anIf-None-Matchnaming that version.GET /scim/v2/Usersanswers aListResponse, an empty one with 200 when nothing matches.filtertakeseqandandoveruserName,externalIdandid; names and operators are compared in any case, and anything else is 400invalidFilter.startIndexandcountpage the result, at mostmax_resultsat a time.
The User’s userName, externalId and binding key are DV_IDENTIFIERs at
their selectors, issued by the client’s binding_issuer. A client sees only
its own Users, the ones whose key its binding_issuer issues: every other id
is 404 and absent from every list, as is a PERSON without a live
professional ROLE, apart from a portal client’s Users, which perform none. The userName index spans every client, so a 409
uniqueness tells one client that a userName exists under another;
externalId is unique within one client. Every SCIM request is an access
record of the client, with the PERSON as its object.
A User is changed and removed through these operations:
PUT /scim/v2/Users/{id}replaces the User (RFC 7644 §3.5.1). A mapped attribute the body leaves out is cleared; the binding key andexternalIdare kept, and a left-outactivekeeps the lifecycle state.PATCH /scim/v2/Users/{id}applies the RFC 7644 §3.5.2 operations, value paths and areplacewithoutpathincluded, and commits the result as one version. The operation is read in any case, as the Entra ID client sendsReplace.DELETE /scim/v2/Users/{id}logically deletes thePERSONand its professionalROLEin one demographic CONTRIBUTION and answers 204. Every later request on the id is 404, the User leaves every list, and a new User may take itsuserName. The binding key stays behind as a tombstone: a login on it is refused as deprovisioned until the owning client creates a User with it again.
Each write answers with the User and its new ETag. An If-Match naming
another version is 412, a changed binding key is 400 mutability, and
a write without If-Match is accepted (RFC 7644 §3.14 makes entity tags a
MAY). active drives the lifecycle state of the PERSON (RM common
§Version Lifecycle):
| Current state | active in the request | Result |
|---|---|---|
complete or incomplete | true or left out | complete when the template holds in full, else incomplete |
complete | false | inactive |
incomplete | false | abandoned |
inactive | true | complete, or incomplete when the template does not hold |
abandoned | true | incomplete, then complete in a second version when the template holds |
inactive or abandoned | false or left out, with a change | 400 invalidValue: reactivate the User first |
inactive or abandoned | false or left out, without a change | 200, no new version |
An inactive or abandoned User is still read and found by a filter, so its
client can reactivate it. When the second version of an abandoned User
fails, the User stays incomplete and the same request completes it.
Roles
A User’s roles (RFC 7643 §4.1.2) are the roles the access policy’s
controller rules name. Each
value is one ROLE the User’s PERSON performs, of the professional role
template, whose name is the value coded in the terminology the client’s
scim_provision grant names, and whose time_validity starts on the day it
is added. The grant states which roles the client may hand out:
| Element | Value |
|---|---|
role_terminology | The terminology id the client’s role values are coded in, exactly one |
role | A role code the client may assign, one element per code |
A request whose roles names a code the grant does not list, or any role
when the grant names no role_terminology, is 403 and changes nothing.
A POST, PUT or PATCH makes the User hold exactly the roles its result
lists: a new value commits a new ROLE, and a removed one ends its ROLE
the day before (its time_validity gains the date of the removal as its
exclusive end) and drops it from the PERSON’s roles. The change decides
the next request on the replica that took it, and on every other replica
once the commit’s notification arrives, with no added transaction. A token’s
role claims never drive a controller rule. These ROLEs carry no
capability, so a SCIM client writes them, and an administrator alone grants
a capability. RFC 7643 sets no vocabulary for roles and RFC 7644 §2 leaves
the authorization model out: the mapping is FerroEHR’s own design.
The versions of a deleted User are kept for the record-keeping duties that
need the professional’s identification (GDPR Art. 6(1)(c), laid down in law
as Art. 6(3) requires: in the Netherlands BW 7:454(3), twenty years, and the
logging duty of the Besluit elektronische gegevensverwerking door
zorgaanbieders). Outside the Netherlands, name your national retention
provision. Enable the identity provider’s protection against accidental
deletions beside max_deactivations.
Only the attribution minimum waits for that horizon: the name, the binding key
and the identifiers, userName and externalId among them. The contacts
serve no attribution, so FerroEHR erases them (GDPR Art. 5(1)(e)): with
auth.scim.contact_erasure_delay = 0 the deletion removes the contacts of every
version of the PERSON in the same transaction, and with a period a sweep
that runs every minute removes them once the period has passed. The sweep
reaches every deleted PERSON whose binding key the binding_issuer of a
scim_provision grant issues, one that has ended included,
an administrator’s demographic DELETE included. Each version keeps its uid,
audit and contribution, and its node rows are derived again from the erased
body. A server signature on such a version is removed, because it was taken
over the content the erasure changed. Each erasure is an access record, a
delete of party:<id>#contacts. A login on the key is still refused as
deprovisioned.
Groups
When [authz.party_binding.group] names a display_name and
[authz.party_binding.membership] is set, /scim/v2/Groups is served beside
/Users, and /scim/v2/ResourceTypes lists the Group. A Group is a
demographic GROUP of the group template:
- its
displayNameis theGROUP’sPARTY_IDENTITY, unique across the live Groups after case folding, so a duplicate is 409uniqueness; - its
externalIdis aDV_IDENTIFIERat theexternal_idselector under the client’s group issuer: thegroup_identifier_issuerof the[[auth.party]]table whoseidentifier_issueris the client’sbinding_issuer, so the group claim of that issuer’s tokens matches it. When that table sets none, the group issuer is thebinding_issuerwith/groupsappended (urn:example:logingivesurn:example:login/groups), with any trailing/of thebinding_issuerdropped first. A deployment whose tokens assert groups setsgroup_claimand agroup_identifier_issuerin the table, and that value is the group issuer; - each member holds one inline
PARTY_RELATIONSHIPof the membership archetype, with itsPERSONassourceand theGROUPastarget, stored in the member’s own version (RM demographic §Party Relationships). NoROLEis created for a Group, and aPERSONin no Group hasrelationshipsVoid. - its
careTeam, in FerroEHR’s Group extension, says whether it is a care team: set at creation,falsewhen left out, and never changed (400mutability). A care team is served withcareTeam = trueand the extension in itsschemas; any other Group is served without either. A care team’sGROUPis named by the codedcare_teamand each membership by the codedMBRof HL7HL7_RoleClass(RM demographicPARTY.type()is thename), so its members are in the care of the patients under the team’s care. Creating one and changing its members needs the client’swrite_care_relationshipgrant besidescim_provision, and is 403 without it (Care teams provisioned over SCIM). The group template and the membership archetype must admit aDV_CODED_TEXTname, as the default definitions do.
A Group belongs to the client that created it; every other client gets
404. A member is a User of the same client: a member naming another
client’s User, an unknown id or a Group (nested Groups are not supported) is
400 invalidValue. What a Group allows stays with the token’s scopes and
roles; the access record lists the Groups the token names that the person
belongs to, and a Group in inactive or abandoned lists no member.
POST /scim/v2/Groupscreates theGROUPwith its members, if any, and answers 201 with the Group, itsLocationandETag.GET /scim/v2/Groups/{id}andGET /scim/v2/Groupsfilter witheqandandoverdisplayName,externalIdandid, andexcludedAttributes=membersleaves the members out. Each member is served with itsvalue,$refandtype.PATCH /scim/v2/Groups/{id}answers 204 with the newETag(RFC 7644 §3.5.2).addofmembersadds the listed members;removewith the filtermembers[value eq "<id>"]removes that member, andremoveofmemberswith neither a filter nor a value list removes them all.PUT /scim/v2/Groups/{id}replaces thedisplayNameand the members, keeps a left-outexternalId, and answers 200 with the Group.DELETE /scim/v2/Groups/{id}logically deletes theGROUPwith its memberships, and every later request on the id is 404.
Entra compatibility deviation. A remove of members that carries a
value list removes only the listed members, the request Microsoft Entra ID
sends. RFC 7644 §3.5.2.2 removes “the attribute and all values” when no
filter is specified; FerroEHR follows Entra only when the value list is
present.
A membership change is a new version of each member’s PERSON it touches,
in one CONTRIBUTION, and the GROUP gets no version; a change costs the same
whatever the Group’s size. The Group’s ETag is its GROUP version with a
membership revision that moves with every membership change, so it changes
whenever its members do (RFC 7644 §3.14). The member User’s ETag changes
too, since its PERSON holds the membership (RFC 7643 §4.1.2); its body does
not, because the User serves no groups attribute. Deleting a User deletes
the memberships its PERSON holds with it. Deleting a Group drops the
membership of each active member in the CONTRIBUTION that deletes the
GROUP. A GROUP an administrator set inactive or abandoned keeps its
version, since the version lifecycle draws no update of either state, and a
SCIM write to such a Group is 400 invalidValue.
Deactivated Users leave their Groups. The version lifecycle draws no
update of an inactive or abandoned PERSON (RM common master06 §Version
Lifecycle), so such a PERSON cannot take a membership change, and an
inactive PERSON binds to nothing. Setting a User’s active to false
therefore drops its memberships in the same version, and each Group’s
ETag changes. A membership of a care-team Group stays, as does every other
care relationship, since SCIM never changes one (Deprovisioning a team
member). Microsoft Entra ID often disables a user and then removes it
from its groups; the later remove finds nothing to remove and answers
204. An add naming an inactive or abandoned User is 400
invalidValue (“reactivate the User first”). A reactivated User belongs to
no plain Group until its client adds it again.
Provision from Microsoft Entra ID
Microsoft Entra ID provisions through a non-gallery enterprise application. FerroEHR validates the access token your own authorization server issues to it, so the steps split between the two.
-
Map the person template. The default party mapping maps
userName,externalId, the formatted, given and family name and the work email Entra sends. Set the person section only to map more, or to key the binding on the object id as the worked example there does.A value path such as
emails[type eq "work"].valueserves the value and itstype. FerroEHR holds one value pertypeand no preference among them, so/scim/v2/Schemasdeclaresprimaryread-only and theprimaryEntra sends is ignored (RFC 7644 §3.3). -
Grant the client. Grant its client
scim_provision, withferroehr party-binding grantor as an administrator through the Demographic API: the--issueris your authorization server, an[[auth.issuer]]of kindmachines, thebinding_issuerelement theidentifier_issuerof the[[auth.party]]your professionals log in through, and thetoken_scopeelement the scope its token holds. Setserver.public_base_urlto the URL Entra reaches. In the Helm chart, aconfig.auth.scimvalue also adds the/scim/v2path to the Ingress.ferroehr config checkrefuses a mapping the endpoint cannot serve. -
Federate Entra’s credential at your authorization server. Entra’s Workload Identity Federation presents a signed assertion, which your authorization server exchanges for a client-credentials access token (RFC 7523 §2.2). These checks are your authorization server’s, not FerroEHR’s, so verify each one there, as Microsoft’s “Workload Identity Federation for SCIM Provisioning” guide requires:
-
issis pinned to your full tenant issuer,https://login.microsoftonline.com/<tenant>/v2.0, and the assertion verifies against that tenant’s key set. -
audis pinned toapi://<workload-identity-app-id>, with one workload-identity application per FerroEHR deployment. -
azpis pinned to the application id of Microsoft’s provisioning service. -
utiis cached for the lifetime of the assertion, and an assertion whoseutiwas seen before is refused as a replay. - The access token it issues holds the grant’s
token_scope, names the client inclient_id, and lives between 1 and 6 hours, the range Microsoft’s guide asks for.
The assertion’s
subis the object id of a Microsoft application that every integration in the tenant shares, never yourclient_id, so it does not meet RFC 7523 §3 item 2.B. Accepting it is a deviation of your authorization server; record it there. Leaving Entra’s Secret Token blank, so that Entra uses its own token, is not supported: Microsoft reserves it for testing, and every non-gallery application in the tenant receives a token with the sameissandaud(RFC 9700 §2.3). A long-lived bearer token is not supported either. -
-
Point Entra at FerroEHR. Set the Tenant URL to
<server.public_base_url>/scim/v2and run Test Connection. Entra queries/Userswithfilter=externalId eq "<random guid>", which FerroEHR answers with an emptyListResponse, and fetches a random User and a random Group, each answered 404. -
Map the attributes in Entra. Map
userName,externalId,activeand the attributes of step 1. Map the attribute that carries the professional’s login identifier tourn:ietf:params:scim:schemas:extension:ferrohealth:2.0:User:loginIdentifier; Entra sends it without listing the extension inschemas, which FerroEHR accepts. An attribute the person template does not map is refused as undefined, so remove the rest of Entra’s default mappings. -
Protect against mass deactivation. Turn on Entra’s accidental deletions prevention, with a threshold at or below
max_deactivations. -
Provision groups. Map the group’s
objectIdto itsexternalId, so the object ids Entra puts in thegroupsclaim match, and provision only the groups assigned to the application, which keeps a person’s token under the groups overage limit. Entra creates each Group with no member, reads it withexcludedAttributes=members, finds it bydisplayName, and adds and removes members with PATCH.
Entra writes Replace and Add with a capital letter, disables a User with
active = false, sends DELETE once the user is removed, and never sends a
null. A value cleared in Entra therefore stays in FerroEHR until the User is
replaced or deleted, or an administrator removes it.
The access-delay register
The EHDS Art. 3(3) delay of the person’s own access to newly registered data
is a Member State option, and an
admin register, not a
configuration key: you turn it on through
{ext}/admin/registers/access-delay only where your Member State’s rule
provides for the delay, every version is kept with its committer, and a
change applies on the next request without a restart. [privacy.access_delay]
in ferroehr.toml is an unknown key and refuses boot. What the delay does is
on delayed access by the person.
| Member | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Whether the delay applies. Off, the person’s access is immediate (Art. 3(1)), every hold already placed stops withholding, and the admin route refuses a new hold with 400. |
categories | list of string | [] | The categories held at creation, named as the audit category register names one: a priority category of Art. 14(1) by its code (Laboratory-Reports, Medical-Imaging, …) or as <system>|<code>, or a national category the map declares. A name the map does not hold, and none, refuse the write. Empty holds nothing at creation; a professional still holds a composition by hand. |
max_delay | duration | required while enabled | The limit of a hold, a whole number of hours from "1h" to "8784h" (one year): new compositions of the listed categories are held from patient-context requests until a professional releases them or it passes. It is the length of a hold placed at creation and the latest end a professional may give one. Art. 3(3) allows the delay “for a limited period of time” only; the period is the Member State’s to set. |
{
"enabled": true,
"categories": ["Laboratory-Reports", "Medical-Imaging"],
"max_delay": "7d"
}
[auth.smart]
The SMART on openEHR scopes are enforced on every route whenever
[auth] is on: each operation carries a requirement from FerroEHR’s route
table, which the ferrohealth-smart crate checks against the token’s scopes
or a Basic user’s scopes. There is no switch for it. This section decides
what beside the route table: whether the discovery document is served, and
whose grants count for what. See SMART App Launch.
| Key | Type | Default | Description |
|---|---|---|---|
discovery | bool | false | Serve /.well-known/smart-configuration. It is built from the metadata of one [auth] issuer, the described issuer, so it needs an issuer whose metadata names a token_endpoint (SMART App Launch 2.2.0, Conformance, §Metadata), and server.public_base_url for its absolute services.*.baseUrl values. |
issuer_metadata_file | path | unset | A JSON file holding the RFC 8414 §2 metadata of the [auth] issuer it names, whose key set is a jwks_file, read at boot. It must name an [auth] issuer, wherever it stands in the list, repeat no member name, and every endpoint it names must be https (a loopback host excepted); the discovery document takes its token_endpoint and the other endpoints from it. Set for an issuer whose metadata is read from the issuer, it is a boot error. |
platform_base_url | string | unset ⇒ the REST root | The path the discovery document hangs off, e.g. /gateway/v1. |
episode_launch | bool | false | Advertise episode context and accept the launch/episode scope and episodeId claim; applies no episode-scoped filtering. |
patient_issuers | list of string | [] | The issuers whose patient/ grants count, each confined to the EHR the token’s ehrId claim names (master07 §Context Selection). Empty, a patient/ grant grants nothing. |
The launch-base64-json capability (master09) is advertised by listing it in
[auth] capabilities; the base64 JSON launch object is the application’s to
consume. The table is always read, since patient_issuers applies whether or
not the document is served; discovery alone turns the document on.
Which clients count as backend clients and which reach the DEMOGRAPHIC API is
policy the CDR holds, never a key here: the query_system_wide and
access_demographic grants of the client’s AGENT
(Operational policy).
patient_issuers stays in the file because it is trust: it says which
issuer’s ehrId claim names an EHR of this platform, which the server needs
before it can believe a patient/ token at all.
No smart URL may carry a user name or password, whether or not the document
is served: the discovery document publishes these URLs to every application,
so a credential in one would be served to anyone who asks.
The described issuer
The discovery document describes one authorization server: SMART App Launch
2.2.0, Conformance, §Metadata requires its authorization_endpoint whenever
the document advertises launch-standalone or launch-ehr, so it is where
every user launch starts. FerroEHR describes an issuer that serves a user
launch and whose metadata it has:
personsandpatients: eligible. A practitioner’s launch and a patient standalone launch both start at the issuer’s login.federation: eligible. Another party’s professionals sign in at it, and an agreement admits them.machines: never described. It signs client credentials tokens only:ferrohealth-smartrefuses every token of amachinesissuer that is not app-only, and FerroEHR refuses a system caller that holds auser/orpatient/scope, so no user launch can work there.
An issuer has metadata when it is introspected, when its metadata is read from
it, or when issuer_metadata_file supplies it. An issuer read from a
jwks_file alone has none.
With discovery = true, the start is refused unless exactly one issuer is
described:
[auth] described_issuerset: it must name an eligible issuer, else the start is refused, naming the key and why.[auth] described_issuerunset: the one eligible issuer is described. With more than one, the start is refused, naming them anddescribed_issuer. With none, as when the only issuer with metadata is amachinesissuer, the start is refused, saying no issuer can be described.
With discovery = false, no document is described and described_issuer is
not read.
The order of the [[auth.issuer]] tables never decides. SMART does not say
which of several trusted issuers a resource server describes. The rule is the
FerroHEALTH family’s own design, shared by every product through
ferrohealth-smart, and described_issuer is the same [auth] key in each.
[management]
The ops-introspection surface: build info, Prometheus, metric views, the effective configuration, runtime log control, and the on-demand profiler. Off by default, and every endpoint off individually.
The health probes are not configured here: /health, /health/liveness
and /health/readiness are always served on the main API port without
authentication, whatever this section says (see
Operations → Health probes).
[management]
enabled = false
base_path = "/management"
[management.endpoints]
info = "off"
metrics = "off"
prometheus = "off"
env = "off"
loggers = "off"
flamegraph = "off"
[management.profiling]
max_duration = "30s"
max_frequency = 999
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | false | Mount the management router. |
base_path | string | /management | Base path for the management endpoints. |
port | int | unset ⇒ share the main listener | Serve management on its own listener and port. Must differ from the server.listen port, and it is plain HTTP, an internal surface. |
flame_file | path | unset | Span-timing capture: write the folded stacks of every span to this file, and render offline with inferno-flamegraph. Unset, the layer is not installed. For diagnostic sessions: the file grows with span traffic. |
[management.endpoints]: info, metrics, prometheus, env, loggers
and flamegraph, each enum{off,admin_only,private,public}, default off.
| Level | Meaning |
|---|---|
off | Not mounted at all; the route answers 404. |
admin_only | Requires an authenticated principal carrying authz.rbac.admin_role (401 unauthenticated, 403 authenticated but not admin). |
private | Requires any authenticated principal. |
public | Served outside authentication. |
env renders the effective configuration and flamegraph starts a profiler on
request, so the boot log prints exactly which endpoints a configuration turned
on and at which level.
[management.profiling]: limits for the on-demand CPU flamegraph behind
endpoints.flamegraph (see
Operations → Profiling):
| Key | Type | Default | Description |
|---|---|---|---|
max_duration | duration | "30s" | Longest sample window one request may ask for, in whole seconds. A request asking for more is refused with 400, never clamped. |
max_frequency | int | 999 | Highest sampling frequency (Hz) a request may ask for. Same refusal semantics. |
Warning
probes_enabledandendpoints.healthdo not exist. Configuration is strict, so a file or environment variable still setting either one fails at boot with an unknown-key error: delete the key; the probes are always on.
[deployment]
The commercial licence token. Every build embeds the licensor’s
non-commercial grant; a deployment that holds a commercial licence installs
its token here. The server behaves identically under either grant and reports
the one in force on GET /management/status (licence.use, licence.licensee,
licence.not_after, licence.configured_token). See
Licensing & legal.
| Key | Type | Default | Description |
|---|---|---|---|
licence_file | path | unset | The licence token the licensor issued. A token that cannot be read or does not verify is reported as refused on /management/status; the embedded grant stays in force. |
[record.signing]
VERSION signing. On by default in digest mode, with read-time verification of
the server’s own signatures strict by default.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Server-side signing of committed versions. |
mode | enum{digest,pgp} | digest | A SHA-256 integrity digest, or an OpenPGP (RFC 4880) detached signature. |
key_file | path | unset | Armored secret key; required for pgp (a boot error otherwise). |
key_passphrase / key_passphrase_file | secret / path | unset | Key passphrase. At most one of the pair. |
retired_key_files | list of path | [] | Armored public keys retired from signing and kept for verification, so versions signed before a key rotation keep verifying. |
verify_on_read | enum{off,warn,strict} | unset ⇒ strict when signing is enabled | Read-time recompute-and-compare policy for the server’s own signatures. |
retired_key_files exists because a stored VERSION.signature records no key
identifier and is an immutable committed fact that cannot be re-issued;
keeping the retired public key is the only way history stays verifiable across
a rotation, and a public key can verify but never sign. Its environment form
takes a comma-separated list
(FERROEHR__RECORD__SIGNING__RETIRED_KEY_FILES=/keys/a.pub.asc,/keys/b.pub.asc).
Note
verify_on_readresolves tostrictwhen signing is enabled. On every read the server recomputes the signature of a version it signed and, on a mismatch, returns a500integrity fault rather than silently serving a provably corrupt record. Set it explicitly towarn(log + meterversion_signature_invalid_total, still serve) oroff(never check). Client-supplied signatures (an author’s own, or one carried by an imported version) are always stored verbatim and never re-verified, whatever this setting says, because the author may have signed a different agreed serialization.
Warning
pgpmode fails closed at boot if the key is missing or unusable: the server will not start. Verify the key and passphrase before switching modes.
Choose an Ed25519 signing key
The server refuses an ECDSA (P-256, P-384, P-521, secp256k1, Brainpool)
or Ed448 signing key at boot: their private-key arithmetic runs on
crypto-bigint 0.5, whose constant-time operations can branch on secret
values (RUSTSEC-2026-0387), with no fixed release on that line. The boot error
names the advisory. Move to Ed25519 with the steps below; the old certificate
goes in retired_key_files, where it keeps verifying, because verification
uses only public values.
An RSA signing key is accepted, but it makes every commit perform an RSA
private-key operation, the operation the Marvin timing sidechannel concerns
(RUSTSEC-2023-0071 / CVE-2023-49092), for which the underlying rsa crate has
no fixed release. An Ed25519 key keeps that code off the signing path entirely.
The server does not refuse an RSA key: a repository whose history is already RSA-signed needs that key to keep verifying, and signatures are immutable committed facts that cannot be re-issued. Instead it logs a warning at boot naming the advisory. To clear it:
- Generate a new signing key:
gpg --quick-generate-key "…" ed25519 sign, and export the armored secret key tokey_file. - Export the public half of the old certificate and add it to
retired_key_files, so versions signed with it still verify (see above). - Restart. New versions are signed with Ed25519; old ones keep verifying.
Rotation inside one certificate is cheaper still: add an Ed25519 signing
subkey to the existing certificate, export the armored secret key again to
key_file, and restart. The server signs with the newest subkey whose binding
grants signing and that is neither expired nor revoked
(the rule), with no
retired_key_files entry needed: the certificate keeps the previous subkey, so
past signatures continue to verify. For a refused ECDSA or Ed448 key this works
when the new Ed25519 subkey is the one chosen. The steps above, with a new
certificate, work in every case.
On Kubernetes, digest mode needs nothing; it is the default. pgp mode
needs the key as a file and its passphrase as a secret, both of which the chart
mounts for you:
# values.yaml
config:
signing:
enabled: true
mode: pgp
key_file: /etc/ferroehr/signing-key.asc
files:
signing-key.asc: |
-----BEGIN PGP PRIVATE KEY BLOCK-----
…
secrets:
signingKeyPassphrase: "…"
Every config.files key becomes /etc/ferroehr/<key>, mounted read-only from
a chart Secret at mode 0440, and that volume holds the private key, so it is
never world-readable inside the container. To go back to digest, set
mode: digest and drop the key material; versions already signed keep their
signatures and still verify.
[record.versioning]
What a commit stores is not a setting: a version whose content equals the
current version’s is committed like any other, with its own commit audit,
contribution, version id and ETag, and the content is stored once (the new
version reads its predecessor’s node rows). The one setting here is the
answer to a repeated send of the same content.
| Key | Type | Default | Description |
|---|---|---|---|
record.versioning.idempotent_resend | bool | false | When true, a PUT whose content equals the current version’s commits nothing and answers like a successful update with the existing version: 200 (or 204 under Prefer: return=minimal), and that version’s ETag and Location. |
Turn it on only for the integration that needs it: with the rule on, the
repeated send leaves no commit audit and no contribution, so the version
history does not record that the content was confirmed again, where the
default records every committal as the RM asks (RM common master06
§Committal and Audits). What the repeated send does leave is one record on
the access log ([audit]), operation resend, naming the version the
content matched and its content digest (<version uid>#sha256:<digest>),
the committer and the time: the entry Cadasto writes for a skipped send,
which says the last version was saved one more time. The content is matched
against the current version only, the one If-Match names; content equal to
an earlier version’s is committed as a new version. The openEHR REST API
does not govern skipping an identical commit; the answer is FerroEHR’s own,
chosen to match what a client sees from Cadasto.
[record.versioning]
idempotent_resend = true