Actors and Roles

• Payer System – Hosts the FHIR server (e.g. Smile Digital Health) containing the member's claims, clinical, and prior authorization data. Validates access tokens and limits each request to the authenticated member's records.
• Identity Provider (IdP) – The payer's OAuth 2.0 / OpenID Connect authorization server. Authenticates the member and issues access tokens to registered applications.
• Third-Party Application – The health app chosen by the member. Registers with the payer's IdP as an OAuth 2.0 client and calls the Patient Access API on the member's behalf.
• Member (Patient) – The individual whose data is being accessed. Signs in to the IdP and authorizes the application.
• Reporting Consumer – The payer's downstream system that reads Patient Access API usage events from Kafka and produces usage reports.

Data Flow Overview

Administrative Setup (Pre-requisites)

1. Client Registration: The third-party application registers as an OAuth 2.0 client with the payer's IdP.
2. Trust Configuration: The SMART on FHIR Inbound Security module is configured to trust access tokens issued by the IdP.

Member and Application Session

1. Authorization Request: The member launches the application, which redirects the member to the IdP to sign in and approve the requested scopes (for example, patient/*.read).
2. Token Issuance: The IdP issues an access token. The token includes the application's client ID, the member's user identifier, and the member's Patient resource ID as claims.
3. Data Request: The application calls the Patient Access API FHIR endpoint with the access token.
4. Token Validation: The SMART on FHIR Inbound Security module validates the token. Its onAuthenticateSuccess callback script: -Grants the session read access to the member's Patient compartment. -Stores the Patient ID, client ID, and user identifier claims as user data on the session.
5. The payer returns the member's FHIR resources permitted by the session.

Usage Capture

1. Enrichment: An interceptor on the Patient Access API endpoint adds the session's Patient ID, client ID, and user identifier to the request's transaction log event.
2. Publication: A Transaction Log Broker module publishes the Patient Access API endpoint's FHIR request events to a dedicated Kafka topic.
3. Reporting: The payer's reporting consumer reads the topic and aggregates usage by member, application, and day.

Sequence Diagram

The following diagram shows how a single FHIR request from a third-party application is authenticated, how the member and application claims are taken from the access token, and how they are added to the request's transaction log event.

sequenceDiagram
    autonumber
    participant App as Third-Party Application
    participant Endpoint as Patient Access API Endpoint
    participant Smart as SMART Inbound Security
    participant Script as onAuthenticateSuccess Script
    participant Interceptor as PatientAccessTxLogEnrichmentInterceptor
    participant TxLog as Transaction Log
    participant Kafka as Kafka Topic

    App->>Endpoint: GET /Patient/patient-005<br/>Authorization: Bearer access token
    Endpoint->>Smart: Authenticate request
    Smart->>Smart: Validate token against the trusted IdP
    Smart->>Script: onAuthenticateSuccess(theOutcome, theOutcomeFactory, theContext)
    Script->>Script: Read claims patient, client_id or azp, sub
    Script->>Script: Grant FHIR_READ_ALL_IN_COMPARTMENT Patient/patient-005
    Script->>Script: setUserData patient_id, client_id, subject
    Script-->>Smart: User session with permissions and user data
    Smart-->>Endpoint: Authenticated user session
    Endpoint->>Interceptor: SERVER_INCOMING_REQUEST_PRE_HANDLED
    Interceptor->>Interceptor: Read user data from the user session
    Interceptor-->>Endpoint: addAdditionalJsonProperty stores each value on the request
    Endpoint->>Endpoint: Read Patient/patient-005 within the member's compartment
    Endpoint-->>App: 200 OK with Patient resource
    Endpoint->>TxLog: Write FHIR_REQUEST event, with the stored values as additionalJson
    TxLog->>Kafka: Publish event to channel_patient_access_txlog