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_personson theAGENTcarrying itsclient_idunder 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 carriesacting_mode = delegatedand the app. A token through an app the CDR grants nothing is no caller and is refused with401. - A Backend Services client. A client credentials token’s
subis itsclient_id(RFC 9068 §2.2), so the same table reads it as the system: apersonsissuer 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 amachinestable 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.