fresh.
About

About

How access works in Fresh

Fresh does not hold clinical data. It holds the configuration that decides which person, acting as which clinical record, may open which workspace, and what the token their apps carry is allowed to do. This page follows that chain from one end to the other.

The chain

Eleven links, each configured in the console except the last three, which happen at runtime on every request.

How a request reaches a clinical recordAn organization configures a FHIR backend, its authorization service and its SMART app registrations, then composes an EHR workspace. A workspace assignment lets a clinical identity open that workspace; the identity’s access profile narrows the scopes of the access token the authorization service issues; the backend’s policy layer validates that token before the record is read or written.1. Organizationowns the configuration2. FHIR backendthe clinical record service3. Authorization servicesandbox, Fresh or brokered4. SMART registrationsclient id, redirects, scopes5. EHR workspaceshell, listing, desk, chart6. Workspace assignmentwho may open it7. Clinical identitymember × backend → reference8. Access profilefull, read only or own record9. Access tokennarrowed scopes10. Backend policyvalidates and enforces11. The recordread or written
  1. 1. Organization — owns the configuration
  2. 2. FHIR backend — the clinical record service
  3. 3. Authorization service — sandbox, Fresh or brokered
  4. 4. SMART registrations — client id, redirects, scopes
  5. 5. EHR workspace — shell, listing, desk, chart
  6. 6. Workspace assignment — who may open it
  7. 7. Clinical identity — member × backend → reference
  8. 8. Access profile — full, read only or own record
  9. 9. Access token — narrowed scopes
  10. 10. Backend policy — validates and enforces
  11. 11. The record — read or written

Three authorization families

Every FHIR backend carries one. It decides where the app authorizes, who signs the token and who checks it when the app calls the API.

SMART App Launcher sandbox

The launcher plays the authorization server. Fresh encodes the launch context and the sandbox issues the token.

What it does. Fresh encodes the launch context into a launch parameter and hands the app to the SMART App Launcher, which plays the authorization server.

Who validates the token. The sandbox issues the token and the sandbox FHIR endpoint accepts it.

Fresh issues tokens

Fresh is the SMART authorization server. Apps authorize against Fresh, which signs a short-lived token carrying the user, the patient in context and the scopes; the backend's policy layer validates it.

What it does. Fresh publishes discovery, authorize, token and JWKS endpoints for the backend and signs an ES256 access token narrowed by the identity's access profile.

Who validates the token. Fresh's own resource facade at /fhir/<backend>/… verifies the signature, the audience, the scopes and the patient compartment before proxying upstream.

Brokered to an external issuer

Fresh's authorize and token endpoints front an external issuer that owns the backend's tokens. Not launchable yet.

What it does. Fresh's endpoints front an external issuer, such as a national identity service, that owns the backend's tokens. Modelled but not launchable yet.

Who validates the token. The external issuer signs the token and the backend's own policy layer checks it.

A Fresh issuer launch, step by step

What happens between a clinician selecting an app in the listing and the app drawing the patient’s record, when the backend’s family is fresh (Fresh issues tokens).

The Fresh issuer launch, from the workspace shell to the clinical record1Shell2Launch URL3App4Discovery5Authorize6Code7Token8Facade9Record
  1. 1Shell. The workspace shell asks Fresh to launch an installed app for the identity and the patient in context.
  2. 2Launch URL. Fresh records a launch context and opens the app's launch URL with iss set to /fhir/<backend> and launch set to that context.
  3. 3App. The app's SMART client reads iss and launch and begins the authorization code flow.
  4. 4Discovery. It fetches <iss>/.well-known/smart-configuration for the authorize, token and JWKS endpoints.
  5. 5Authorize. GET /oauth/authorize checks the Fresh session, the launch context, the audience, the client, the redirect URI, the requested scopes and PKCE.
  6. 6Code. Fresh narrows the granted scopes to the identity's access profile and redirects back with a one-time code.
  7. 7Token. POST /oauth/token exchanges the code and the PKCE verifier for a short-lived ES256 JWT carrying the user, the patient, the scopes and the profile.
  8. 8Facade. The app calls /fhir/<backend>/… with that token. The resource facade verifies the signature and audience, checks the scope for the action, and enforces the patient compartment.
  9. 9Record. The facade proxies the call upstream to the backend's base URL and streams the record back. The client's token is never forwarded upstream.

Three places access is enforced

No single check is trusted on its own. An access profile of read only or own record is applied when the token is minted and again when the record is fetched.

Workspace assignment

An identity opens a workspace only when an assignment pairs the two, and only when the identity's backend is the workspace's backend and its kind matches the workspace's audience. Without an assignment there is no launch and so no token.

Token issuance

The authorize step intersects what the app registered with what it asked for, then narrows the result by the identity's access profile: a read-only practitioner loses the create, update and delete letters, and a patient's token carries their own patient id.

Backend policy

Every FHIR call is checked again where the data lives. Fresh's resource facade requires a scope that covers the resource and the action, enforces the patient compartment for patient-prefixed scopes, and never forwards the app's token to the upstream service.

Try it locally

The seeded demo carries both worlds side by side. Sign in as practitioner@demo.example and the EHR start page offers two clinical workspaces:

  • The sandbox workspace — its backend’s family is sandbox (SMART App Launcher sandbox), so the SMART App Launcher issues the token and the apps read the open sandbox FHIR endpoint directly.
  • The Fresh issuer workspace — its backend is demo-fresh. Fresh signs the token and every app reads its data through /fhir/demo-fresh/…, where the scopes and the patient compartment are enforced before the call is proxied upstream. The same seven bundled apps run unchanged in both.

The patient account sees the matching pair of charts. To watch the enforcement, open the backend in the console, set its identity to read only, relaunch, and the write scopes are gone from the token the app receives.

Back to About · Console · EHR