Pan-Canadian HALO Specification
HALO is a standardized “visual interactive framework” that would enable web applications to plug into their existing design.
This profile defines the use of the EHR Launch flow from SMART App Launch v2.1.0 within the HALO framework to enable secure, standards-based integration of clinical applications using OAuth 2.0 and OpenID Connect. It formalizes the interactions required to initiate application launch, discover authorization and token endpoints, and retrieve FHIR resources based on context and granted scopes. Future iterations may expand this profile to include the Standalone Launch and Back-end Services flows.
See the App Launch page 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 SMART on FHIR application that initiates the OAuth 2.0 authorization flow with a SMART Authorization Server to obtain access tokens and contextual launch information. It interprets the retrieved context and uses the access token to access relevant FHIR resources from the Resource Server in support of the application's workflow.
A SMART-enabled system that authenticates users and issues OAuth 2.0 access tokens to Authorization Clients based on predefined scopes and launch context. It understands SMART scopes (e.g., launch, patient/*, openid fhirUser) and returns SMART-conformant token responses (including context such as patient and encounter when applicable).
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: 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 an open a URL that looks like this: https%3A%2F%2Femr.example.com%2Ffhir%2Fr4
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 flow.
See Section 6.3 FHIR Authorization Endpoint and Capabilities Discovery using a Well-Known Uniform Resource Identifiers (URIs) of the SMART App Launch specification.
The Authorization Client begins by retrieving the Resource Server’s configuration from the .well-known/smart-configuration endpoint, which supplies metadata such as the authorize and token endpoints. Using the discovered authorize endpoint, the client initiates 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.
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 SMART application.
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.