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

Behind FerroSMART

FerroSMART is the FerroHEALTH family’s SMART App Launch 2.x authorization server. It signs people in at any OpenID Connect provider and uses that provider for login alone. It issues plain RFC 9068 access tokens that carry the launch context: patient, encounter, fhirUser and, at an openEHR base, ehrId. FerroEHR runs behind it as a resource server. The person never signs in to FerroEHR, and FerroEHR never sees the provider’s tokens. FerroSMART’s architecture describes the whole deployment in §13.21, A product behind FerroSMART, of its architecture. This page is FerroEHR’s side of it.

 SMART app ── /authorize, /token ──▶ FerroSMART ── login ──▶ OpenID Connect provider
     │                                   │
     │  Bearer access token              │ jwks_uri
     ▼                                   ▼
 FerroEHR (resource server) ── reads the token under the `ferrosmart` preset

FerroSMART serves the openEHR base

FerroSMART issues a token only for a base it serves. Its [[ferrosmart.resource]] table names FerroEHR’s openEHR REST base as an openehr resource. Its subject_namespace is the namespace FerroSMART’s patient picker looks EHRs up under:

[[ferrosmart.resource]]
base = "https://ehr.example.org/ferroehr/rest/openehr/v1"
kind = "openehr"
subject_namespace = "examples"

FerroEHR trusts FerroSMART

One [[auth.issuer]] table names FerroSMART’s issuer with kind = "persons" and profile = "ferrosmart" (Authentication & access). The preset keeps every rfc9068 default but two: typ is at+jwt alone (RFC 9068 §2.1), and every token carries scope (SMART App Launch 2.2.0, Obtain access token, Response). A token without scope is refused with 401.

[[auth.issuer]]
issuer = "https://smart.example.org"
kind = "persons"
profile = "ferrosmart"
audience = ["https://ehr.example.org/ferroehr/rest/openehr/v1"]
  • A person through a SMART app. FerroEHR reads who may act for a person from the CDR, never from the configuration. Grant each SMART app act_for_persons on the AGENT carrying its client_id under FerroSMART’s issuer (Enterprise identity providers). A person’s token through a granted app reads as that person, delegated to the app, and the access record carries acting_mode = delegated and the app. A token through an app the CDR grants nothing is no caller and is refused with 401.
  • A Backend Services client. A client credentials token’s sub is its client_id (RFC 9068 §2.2), so the same table reads it as the system: a persons issuer also signs its machines’ app-only tokens. Its grants in the CDR decide what it reaches, as for any system caller.
  • One table per issuer. Name FerroSMART in this one table. A second [[auth.issuer]] table of the same issuer, such as a machines table beside it, refuses the start, naming the issuer (FerroHEALTH/FerroSMART#591).

The scopes a token grants still meet FerroEHR’s own access decisions on top.

The discovery document describes FerroSMART

With [auth.smart] discovery = true, GET https://ehr.example.org/ferroehr/rest/openehr/v1/.well-known/smart-configuration describes the issuer ferrohealth-smart’s shared rule picks (SMART App Launch). With FerroSMART as the one persons issuer, that is FerroSMART: the document names its authorization_endpoint and token_endpoint, so an app that starts at FerroEHR’s base finds FerroSMART (SMART App Launch 2.2.0, Conformance, Metadata). When FerroEHR trusts another issuer that signs user tokens beside it, [auth] described_issuer names FerroSMART.

Try it

The quickstart runs FerroEHR behind FerroSMART with Keycloak or ZITADEL upstream (Docker Compose), and Enterprise identity providers lists every upstream FerroSMART supports with its setup.

No specification governs this deployment shape: our own design, built on SMART App Launch 2.2.0 and RFC 9068.