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], [admin], [tenancy], [smart], [management], and [signing]. Precedence, the environment-name grammar, and file discovery are on the Configuration reference index.

• [auth]
  • The Basic-auth user store
  • [auth.oidc]: bearer validation
• [authz]
  • [authz.rbac]
  • [authz.abac]
• [admin]
• [tenancy]
• [smart]
• [management]
• [signing]

[auth]

Authentication: Basic credentials, OAuth2/OIDC bearer tokens, or both.

[auth]
enabled = true
verified_cache_ttl_seconds = 60

[[auth.basic.users]]
username = "clinician"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$…$…"   # never a plaintext password
roles = ["USER"]

[auth.oidc]
issuer = "https://keycloak.example.com/realms/ferroehr"
audiences = ["ferroehr"]
algorithms = ["RS256"]

Warning

auth.enabled = true with 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: a 401 challenge must name a scheme applicable to the target resource. Configure [[auth.basic.users]], configure [auth.oidc], or set auth.enabled = false for a development server.

The Basic-auth user store

[[auth.basic.users]] is an array of tables and therefore file-only — the environment grammar cannot spell an array index.

Warning

Every password_hash must meet the OWASP Argon2id floor: m>=19456 (19 MiB), t>=2, p>=1, algorithm argon2id. Anything weaker — or a non-argon2id PHC 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.

[auth.oidc]: bearer validation

The table’s absence disables bearer authentication entirely. When present, the server validates tokens as a resource server; it never issues them.

The boot rules, and what each one prevents:

• audiences must name at least one audience. RFC 7519 §4.1.3 obliges a recipient that does not identify itself with a value in a present aud claim to reject the JWT, and RFC 9068 §4 step 4 makes the check unconditional for an access token. A resource server that declares no audience cannot reject a token minted for a different resource server, and cannot tell an OpenID Connect ID token (whose aud is a client id) from an access token (RFC 8725 §3.9, §3.12). Set it to whatever your identity provider puts in aud for this CDR.
• issuer must be an https URL with no query or fragment. That is the RFC 8414 §2 definition of an issuer identifier, and §6.2 requires TLS for issuer metadata — over plain HTTP an attacker on the network can serve their own signing keys. A development issuer is opted in explicitly with allow_insecure_issuer = true; the no-query/no-fragment rules still apply, since those are structural.
• clock_skew_leeway_seconds is capped at 300. RFC 7519 §4.1.4 allows “some small leeway, usually no more than a few minutes, to account for clock skew”, and RFC 9068 §4 step 6 repeats the bound. A large leeway silently extends the life of every token past its exp.
• hmac_secret must be at least 32 bytes. RFC 8725 §3.5: a human-memorizable password must not be used directly as the key to a keyed-MAC algorithm such as HS256. A symmetric key is also shared with the authorization server — meaning this server could mint the very tokens it accepts — so the boot log warns that it is a development posture. Prefer discovery or jwks_json.
• The algorithm set is bound to the key source. A key belongs to one algorithm family, and accepting an algorithm the configured key material cannot verify is the algorithm-confusion setup RFC 8725 §3.1 warns about — most famously an RS256 deployment that also accepts HS256, letting an attacker sign with the public key as if it were a shared secret.

The signing-key source is exactly one of: the symmetric secret, the static JWKS, or — when neither is set — the issuer’s OIDC discovery document. Configuring both hmac_secret and jwks_json (in either direct or *_file form) is a boot error, never resolved by silent precedence. 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.

The last three keys apply only when keys come from OIDC discovery. The timeouts stop an unresponsive identity provider from parking bearer requests until the operating system’s TCP timeout; the negative cache means a provider outage costs one discovery attempt per negative_cache_ttl_seconds rather than one per incoming request, so callers get fast 401s instead of slow ones. Keep the negative TTL short — it is also how long recovery takes to be noticed after the provider comes back.

[authz]

Role-based (RBAC) and attribute-based (ABAC) authorization. The full evaluation order and design rationale are in Security.

[authz.rbac]

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 is off and is not mounted. Only the admin_only level consults authz.rbac.admin_role.

[authz.abac]

• [authz.abac.cedar] — policy_dir (path, required when engine = "cedar" and ABAC is on) and reload_secs (int, unset — an optional hot-reload interval).
• [authz.abac.remote] — server (string, required when engine = "remote", and it must end with /, because the policy name is appended), connect_timeout_ms (int, 2000), request_timeout_ms (int, 5000).
• [authz.abac.policy.<kind>] — one entry per resource kind, with kind ∈ ehr, ehr_status, composition, contribution, query, directory. Keys: name (string, the policy to evaluate) and parameters (list of enum{organization,patient,template}). A key that is not one of those six kinds is a boot error, and template is rejected on ehr and ehr_status — neither carries a template.

Warning

With engine = "remote", every resource kind the enforcement point consults needs a policy entry: ehr, ehr_status, composition, contribution, query — plus directory when check_directory = true. A missing one is a boot error. At runtime a kind with no policy can only be denied, since there is no policy to ask and permitting would be a silent hole, so the misconfiguration is caught at startup rather than turning into blanket 403s on live traffic. The Cedar engine reads its policies from authz.abac.cedar.policy_dir and needs no entries here.

[admin]

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.

[tenancy]

Multi-tenancy. Off by default: the tenant middleware is not installed, the pool takes no per-acquire hook, and the tenant CRUD routes answer 404, so a single-tenant deployment is unchanged.

[smart]

SMART App Launch. Off by default; when off the discovery document is not served and the scope gate is inert. See SMART App Launch.

[smart]:

[smart.episode]: enabled (bool, false) — advertises episode context and accepts the launch/episode scope and episodeId claim, but applies no episode-scoped filtering.

[smart.endpoints] carries the external authorization-server endpoints the discovery document publishes verbatim: issuer, jwks_uri, authorization_endpoint, token_endpoint, registration_endpoint, introspection_endpoint, revocation_endpoint, management_endpoint (all string, unset ⇒ omitted from the document); the advertised lists token_endpoint_auth_methods_supported, grant_types_supported, response_types_supported, code_challenge_methods_supported, scopes_supported and capabilities (all list of string, [] — capabilities appends operator-advertised HL7 base capabilities such as launch-ehr or sso-openid-connect to the derived openEHR set); and allow_insecure_endpoints (bool, false).

Everything in [smart.endpoints] is published at /.well-known/smart-configuration for third-party applications to act on, so smart.enabled = true boot-validates it rather than relaying whatever is configured:

Note

An empty advertised list is not silence — it claims the authorization server supports none of that thing, and a conforming application will believe it.

[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_seconds = 30
max_frequency = 999

[management.endpoints] — info, metrics, prometheus, env, loggers and flamegraph, each enum{off,admin_only,private,public}, default off.

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):

Warning

probes_enabled and endpoints.health do 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.

[signing]

VERSION signing. On by default in digest mode, with read-time verification of the server’s own signatures strict by default.

retired_key_paths 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__SIGNING__RETIRED_KEY_PATHS=/keys/a.pub.asc,/keys/b.pub.asc).

Note

verify_on_read resolves to strict when signing is enabled. On every read the server recomputes the signature of a version it signed and, on a mismatch, returns a 500 integrity fault rather than silently serving a provably corrupt record. Set it explicitly to warn (log + meter version_signature_invalid_total, still serve) or off (never check) to opt out. 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

pgp mode fails closed at boot if the key is missing or unusable — the server will not start. Verify the key and passphrase before switching modes.

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_path: /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 — 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.