Pan-Canadian HALO Specification
HALO is a standardized technology framework that enables approved jurisdictional and vendor applications to seamlessly integrate into any authorized Point of Care system.
This profile defines the use of SMART App Launch v2.1.0 within the HALO framework to enable secure, standards-based OAuth 2.0 authorization and FHIR resource access for clinical applications and systems. It formalizes the interactions required to discover authorization metadata, obtain access tokens, and access FHIR resources under granted scopes. CA:SoF supports both user-facing and system-to-system integration patterns; its actors are designed to be composed with other HALO profiles to address a range of clinical and backend workflows.
See the App Launch and Backend Services pages for more details.
A system that initiates the launch of an external SMART on FHIR application by redirecting the user and supplying launch context such as patient or encounter identifiers.
A component of a SMART on FHIR application that receives SMART app launch requests and prepares the application for authorized access to FHIR resources.
A component of a client application that uses SMART authorization metadata and OAuth 2.0 access tokens to access FHIR resources from a Resource Server. Depending on the integration pattern, this actor may operate as a launched SMART application obtaining tokens via the Authorization Code flow, or as a backend system obtaining tokens via client credentials with a signed JWT assertion.
A SMART-enabled system that issues OAuth 2.0 access tokens to Authorization Clients based on granted scopes. It understands SMART scopes (e.g., launch, patient/*, openid fhirUser, system/*) and returns SMART-conformant token responses. When operating in a user-facing flow, it authenticates the requesting user and may include launch context (e.g., patient, encounter) in the response; in a system-to-system flow, it validates client credentials and issues tokens scoped to the permissions granted to that client.
A SMART-enabled FHIR API endpoint that hosts patient and clinical data and responds to authorized queries using access tokens issued by the Authorization Server. It publishes a .well-known/smart-configuration endpoint exposing the authorize and token endpoints and enforces access according to granted SMART scopes.
The following diagram provides an overview of the Actors directly involved in the CA:SoF profile and the relevant Transactions between them.
Note: The Launch Initiator is depicted as the web browser to reflect the fact that the launching system (e.g., an EHR) initiates the SMART on FHIR launch by directing the browser to open the target application's launch URL—typically in a new tab, window, or embedded frame. As a result, it is the browser that issues the HTTP request to the target application’s server. The "OK" response shown in the diagram represents the HTTP response returned by the target application to the browser, not to the launching system. In practice, the actual status code may vary depending on the application's implementation, and the HTTP response is not returned directly to the launching system itself.
The table below lists the transactions for each actor directly participating in the CA:SoF profile. To claim compliance with CA:SoF, an actor shall support all required transactions (labeled “R”).
| Actor | Transaction | Optionality |
|---|---|---|
| Launch Initiator | Initiate SMART Launch [CA:SoF-1] | R |
| Launch Responder | Initiate SMART Launch [CA:SoF-1] | R |
| Authorization Client | Get SMART Server Metadata [CA:SoF-2] Get SMART Authorization [CA:SoF-3] Include Access Token [CA:SoF-4] |
R R R |
| Authorization Server | Get SMART Authorization [CA:SoF-3] | R |
| Resource Server | Get SMART Server Metadata [CA:SoF-2] Include Access Token [CA:SoF-4] |
R R |
Note: In backend services scenarios, the Launch Initiator and Launch Responder actors do not participate.
Note: This profile addresses a similar space as IHE IUA (i.e., OAuth 2.0/OIDC–based protection of FHIR APIs), but it is explicitly scoped to SMART App Launch semantics (discovery, parameters, scopes) and does not require or assert IUA conformance at this time.
The Launch Initiator typically generates an opaque launch identifier that represents the current clinical context associated with the logged-in user (e.g., Patient, Encounter). The Initiator constructs a launch URL containing this launch identifier and the iss parameter, which points to the FHIR base URL of the Resource Server.
For example, the Launch Initiator may build and open a URL that looks like this: https://smart-app.example.com/launch?iss=https://emr.example.com/fhir/r4&launch=abc123
The Initiator then redirects the user’s browser to this launch URL to initiate the SMART application.
Upon receiving the request, the Launch Responder parses the launch parameters and prepares to initiate the authorization flow by acquiring the context and authentication metadata needed to proceed.
See the App Launch page of the SMART App Launch specification for more details.
This interaction allows the Authorization Client to dynamically discover the necessary endpoints for subsequent authorization and token exchange steps.
The Authorization Client queries the Resource Server’s SMART configuration endpoint located at /.well-known/smart-configuration. See Section 2.1.8 Retrieve .well-known/smart-configuration of the SMART App Launch specification.
In response, the Resource Server provides a JSON document that describes the server's authorization, token, and introspection endpoints, as well as supported capabilities required for OAuth 2.0 and OpenID Connect-based flows.
See Section 6.3 FHIR Authorization Endpoint and Capabilities Discovery using a Well-Known Uniform Resource Identifiers (URIs) of the SMART App Launch specification.
This transaction represents the token acquisition step in which an authorized client obtains an access token from the Authorization Server. The specific OAuth 2.0 flow used depends on the composed workflow: CA:SoF defines two realizations — one for user-mediated EHR Launch and one for system-to-system backend services — described in the subsections below.
Applicable when a user is present and the client is a SMART application launched via CA:SoF-1.
The Authorization Client uses the authorize endpoint discovered in CA:SoF-2 to initiate the OAuth 2.0 Authorization Code flow by redirecting the user's browser with the launch parameter (from CA:SoF-1), requested scopes, and a redirect URI. Upon successful authentication and authorization, the Authorization Server redirects back with an authorization code.
See Section 2.1.9 Obtain Authorization Code of the SMART App Launch specification.
The Authorization Client exchanges this code for access and identity tokens by issuing a request to the Authorization Server’s token endpoint. The response includes an access token, an ID token (if requested), and associated context (e.g., patient, encounter, fhirUser) derived from the initial launch. See Section 2.1.10 Obtain access token and Section 2.2 App Launch: Scopes and Launch Context of the SMART App Launch specification.
Applicable when the client is a system acting outside of the context of a specific user, as in a CA:BS composed workflow.
The Authorization Client (acting as a backend service) uses the token endpoint discovered in CA:SoF-2 to request an access token directly, authenticating with a signed JWT assertion rather than through a user-facing redirect. The Authorization Server validates the assertion and returns an access token scoped to the system-level permissions granted to that client.
See Section 7 SMART Backend Services: Authorization Guide of the SMART App Launch specification.
The Authorization Client uses the access token obtained during CA:SoF-3 to retrieve FHIR resources from the Resource Server. The request includes the access token in the HTTP Authorization header as a Bearer token.
The Resource Server validates the token and responds with the requested FHIR resources, constrained by the scopes granted during authorization. These may include contextual resources such as Patient, Encounter, and Practitioner, as well as any additional data needed to support the client system.
See the FHIR RESTful API page of the FHIR R4 specification and Section 2.1.11 Access FHIR API of the SMART App Launch specification.