Breaking changes of party binding
The release that binds every person to a demographic PERSON changes the
configuration and the wire in ways an existing deployment must act on.
Each change below has the upgrade step it needs and its own entry under
Changed or Removed in the changelog. The order to apply them in is on
Party binding: bootstrap and migration.
Configuration
- The family pins move together.
ferrohealth-smart0.9, withferrohealth-authz,ferrohealth-session,ihe-atna,ehds-logging,ihe-iti,ferrohealth-config,ferrohealth-serverandferrohealth-ui. Upgrade: nothing to set; the configuration changes below follow from theferrohealth-smart0.9 shape. - Every issuer is an
[[auth.issuer]]table with a requiredkind(persons,patients,machinesorfederation) and a profile, and holds every setting of its tokens itself. Upgrade: write each issuer as its own table, move the section-level settings (audience,algorithms,clock_skew_seconds, thejwks_*keys,timeout_ms,mode,role_claims,[auth.introspection]) onto it, give it itskind, and put patients and professionals at separate issuers. token_profile, the section-level issuer settings and theclaimkey of[[auth.party]]are deleted. A configuration that still names them refuses the start, naming what replaces it. Upgrade: replacetoken_profile = "jwt"withtoken_types = ["JWT"]and therequired_claimsthe issuer’s tokens carry, droptoken_profile = "rfc9068", and let the issuer profile’sperson_keyname the key claim.acting_for_claimandclient_tokensare removed with[authz.professional]. The issuer’skindand profile classify the caller. Upgrade: remove the table and list a client that acts for a person in its issuer’sdelegates.- Basic users are persons only. Every
[[auth.basic.users]]entry maps to aPERSONby its binding key in[[authz.party_binding.basic_user]], an unmapped one refuses the start naming the user, and every machine, read-only included, uses OAuth 2.0 client credentials under a declared[[authz.system_client]]. Upgrade: provision each person a Basic user stands for through SCIM, map the user by that person’s key, and move every machine to client credentials. - Every committing system client needs its declaration, and the
facility rule only checks. A system caller commits into an EHR only as a
client an
[[authz.system_client]]table declares, each COMPOSITION of a template itswriteslists and naming a facility itsfacilitieslists; the server never writes the facility for it. Upgrade: declare every client that commits, with itswrites,facilitiesandorigins, and give its compositions the facility identifier. From 5.7.1 the table is gone and a system client is granted in the CDR (Operational policy). - Import needs a role. Importing an EHR Extract needs
[authz.rbac] import_roleor asystem/caller. Upgrade: setimport_roleand give it to the accounts that import. From 5.7.1import_roleis gone, and every caller, person or system, imports only under animport_ehrorimport_ehr_extractgrant in the CDR.
Binding and the committer
- Unbound, inactive, abandoned and deprovisioned persons are refused.
A
personslogin whose key noPERSONcarries is refused with403(refused-unbound), and so is one whosePERSONis800|inactive|,801|abandoned|or deleted. Upgrade: provision every professional before you add apersonsissuer, through the four steps. - The professional
ROLEis what makes aPERSONbindable. APERSONbinds only while it performs aROLEof the mapping’s role template naming it asperformer. Upgrade: give each existing person itsROLEwithferroehr party-binding adoptbefore the first SCIM run. - The committer is the server’s. A bound caller commits under the
committer the server writes, and a stated committer must equal it or be
the placeholder
{"_type": "PARTY_IDENTIFIED", "identifiers": [{"_type": "DV_IDENTIFIER", "issuer": "<iss>", "id": "<sub>"}]}, which names the authenticated caller; any other is refused with403. Upgrade: stop sending a committer, or send the placeholder. - Every person’s committer carries the provider identifier, type
healthcare-provider, beside the login identifier and theexternal_refto thePERSON, and a representative commits as aPARTY_RELATEDnaming their ownPERSONand the coded relationship. Upgrade: read the provider and the representative from these committers. - A patient’s committer is
PARTY_SELFwithoutexternal_ref. Upgrade: find a person’s own entries by the committer’sPARTY_SELFtype, not by a formerexternal_ref. - System callers and patient context are strict. A system caller holds
system/scopes only, and a token carrying auser/orpatient/scope is refused with403; a patient-context token commits no demographic version. Upgrade: give each system clientsystem/scopes alone. - The parties binding relies on are protected. A key-bearing
PERSON, its professionalROLE, a representation relationship and a provisionedGROUPare written through the demographic API by an administrator only, and a present binding key changes only throughPOST /admin/party/binding-key. Upgrade: write these parties as an administrator.
Versions committed before the upgrade keep their committer: versions are
immutable, and nothing rewrites an AUDIT_DETAILS (RM Common
master06-change_control_package.adoc §Committal and Audits).