Pan-Canadian HALO Specification
HALO is a standardized “visual interactive framework” that would enable web applications to plug into their existing design.
The HALO Framework extends the SMART on FHIR launch specification to support both standard and accelerator workflows, enabling integration of third-party healthcare applications within Point of Care (PoC) systems of varying capabilities. This means that whether a PoC system is advanced or limited in its FHIR capabilities, it can still seamlessly integrate with modern healthcare applications. By bridging these gaps, the framework promotes interoperability and ensures consistent access to innovative tools, ultimately enhancing patient care across diverse healthcare settings.
Standard SMART on FHIR Launch: For PoC systems equipped with their own FHIR server and Identity Provider (IdP), the framework fully supports the standard launch sequence using OAuth 2.0 and FHIR interfaces.
SMART on FHIR Accelerator Launch (SoFA): For PoC systems that do not expose their own FHIR API or OAuth 2.0 IdP for any reason, the framework introduces the SoFA workflow. This allows them to leverage centralized services—such as jurisdictional FHIR servers and IdPs—to facilitate application integration on their behalf.
The launch URL is the entry point for a SMART application initiated by the Point of Care (PoC) system. When a user chooses to launch an app, the PoC system opens the app's registered launch URL and includes specific parameters to establish the necessary context.
The launch URL includes two critical parameters:
iss (required): Specifies the base URL of the FHIR server that the app uses to retrieve contextual resources during launch. The app interacts with this server to access FHIR resources. Additionally, the FHIR server at this endpoint SHALL offer support for the /.well-known/smart-configuration endpoint described below.
launch (required): An opaque identifier generated by the PoC system for this specific launch instance. It represents any context associated with the launch, such as patient or user session information. The app must include this launch parameter when requesting authorization to allow the server to associate the request with the initial context.
Example of a Launch URL: https://app.example.com/launch?iss=https%3A%2F%2Ffhir.example.com&launch=xyz123
In this example, iss is set to https://fhir.example.com, indicating the FHIR server's base URL. launch is xyz123, an opaque identifier representing the launch context. For more information on the launch URL and parameters, refer to the EHR Launch section of the SMART App Launch specification.
In a healthcare setting, context refers to the relevant information surrounding a patient’s care, such as the patient’s identity, current treatment details, care provider information, clinical setting, and any ongoing encounters or procedures. This contextual data is essential for understanding a patient’s immediate health needs, enabling accurate decision-making, and ensuring that all members of the care team operate with the most up-to-date information. Properly managed, context allows healthcare providers to maintain continuity of care and a holistic view of the patient's health, which can lead to improved outcomes and more efficient care delivery.
In the HALO Framework and SMART on FHIR standards, context is the backbone of application interoperability within clinical systems. It ensures that healthcare applications can communicate seamlessly with Point of Care systems by standardizing how clinical context is shared. For example, when launching a SMART app from an Electronic Medical Record (EMR), context parameters like the patient's ID, current encounter, or attending practitioner are passed alongside the access token by the IdP. This enables the app to target the appropriate clinical data without requiring the user to re-enter information or duplicate workflows.
HALO extends this by supporting both local and jurisdictional context management. In standard SMART on FHIR launches, context is managed locally within the PoC system, directly linking apps with PoC-controlled FHIR resources. In the SMART on FHIR Accelerator workflow, however, context is managed at the jurisdictional level, allowing PoC systems without native FHIR servers to securely transmit context to a centralized service. Through operations like $set-context, SoFA facilitates the secure storage and sharing of essential clinical details, enabling seamless app launches and access to required patient data.
See the Operation: $set-context for more information.
The /.well-known/smart-configuration endpoint is a standardized location on FHIR servers that require authorization. By accessing this endpoint—formed by appending /.well-known/smart-configuration to the server's base URL—clients can dynamically discover and retrieve a JSON document containing essential OAuth2 and OpenID Connect configuration details, as well as the server's supported SMART capabilities.
For a more in-depth overview, see the FHIR Authorization Endpoint and Capabilities Discovery using a Well-Known Uniform Resource Identifiers (URIs) section of the SMART App Launch specification as well as the RFC for RFC 5785.
In alignment with the base SMART on FHIR specification's authentication and authorization mechanisms, the HALO Framework employs standard OAuth 2.0 and OpenID Connect (OIDC) protocols, regardless of whether the Point of Care system's IdP or a jurisdictional IdP is used. This ensures that both the standard SMART on FHIR and the SMART on FHIR Accelerator workflows adhere to a consistent, secure, and interoperable approach to authorization. Identity Providers (IdPs) are responsible for validating tokens issued during the authorization process to ensure secure access to protected resources. Implementers SHALL follow these protocols as specified.
For detailed specifications and guidance on authentication mechanisms, including Single Sign-On (SSO) strategies and security considerations, please refer to the Security, Authentication and Authorization section of the Design Considerations page.
In the standard SMART on FHIR workflow, the Point of Care system directly provides the current user context—such as patient and encounter—to the Identity Provider, with the IdP then including this context information in the access token response to the SMART app. In the SMART on FHIR Accelerator flow, the PoC system instead uses the $set-context operation to store the necessary context in the SoFA prior to launch. This enables the SoFA to manage the context and share it with the jurisdictional IdP as part of the app launch sequence.
In either workflow, there is an expectation that the implementing IdP vendor will support a mechanism for associating the context with the opaque context identifier passed during the authorization code request. This means that IdP implementations SHALL support the inclusion of SMART-specific artifacts that extend the standard OAuth 2.0 and OIDC specifications. For example, session context parameters such as patient, encounter, and fhirContext should be included as parameters alongside the access token in the response, based on the scopes requested. Furthermore, when the openid and fhirUser scopes are requested, the id_token must contain the fhirUser claim, representing the current user as a FHIR resource (e.g., Practitioner, Patient, RelatedPerson, etc.).
For more information on the expectations for identity provider platforms in this flow, please see the Launch context arrives with your access_token section of the SMART App Launch specification.
Regardless of which Identity Provider is driving the launch, whether it is the Point of Care system's IdP or a jurisdictional IdP, there is an underlying assumption that the implementer of that IdP has the necessary functionality and business processes in place to support standard OAuth 2.0 client registration for applications. This includes the ability to register, manage, and authenticate client applications in compliance with OAuth 2.0 specifications. For more detailed information on OAuth 2.0 client registration, refer to RFC 6749: OAuth 2.0 Authorization Framework and the SMART on FHIR App Launch: Launch and Authorization specifications for more information.
Ensuring consistent patient identification across systems is critical for accurate and coordinated care. In the HALO Framework, patient identity reconciliation is recommended whenever patient data is exchanged at the jurisdictional level. This process typically involves matching patient records from different sources to maintain a single, accurate identity across all systems. Common approaches include using an Enterprise Master Patient Index (EMPI) or similar tools to match demographic data.
Standard transactions, like the Patient Identifier Cross-reference (PIXm) and Patient Demographics Query (PDQm) from IHE, can support this reconciliation. However, organizations may also implement custom FHIR operations to achieve the same goal. HALO recommends that all Point of Care (PoC) systems and other actors participating in data exchanges apply patient reconciliation practices as necessary to uphold patient identity integrity across the ecosystem.
The base SMART on FHIR App Launch workflow enables the integration of third-party healthcare applications within PoC systems through standardized OAuth 2.0 and FHIR-based interfaces. This section outlines the standard SMART App Launch sequence from the HALO framework perspective, which includes the addition of the HALO App Catalog. Described below, are the interactions between the user, the PoC system, and the various components involved, including the SMART application, FHIR server, and Identity Provider.
| Actor | Description |
|---|---|
| App Catalog | A centralized repository for healthcare applications that extend the capabilities of clinical systems such as Electronic Medical Records (EMRs). A primary goal of the App Catalog is to provide healthcare providers across Canada with access to jurisdictionally approved third-party applications, streamlining the discovery, configuration, and rollout of applications to improve patient care and clinical workflows. For more information, see the App Catalog page. |
| Identity Provider (IdP) | In the SoF context, the Identity Provider (IdP) is typically managed by the Point of Care (PoC) system, offering local control over authentication and authorization. However, it is also possible to support a base SoF launch with an external IdP, as long as the external IdP can securely provide access to PoC-managed user context and FHIR resources through OAuth 2.0 and OIDC protocols. |
| Point of Care (PoC) | A local system (e.g., an EMR), used by healthcare professionals to support the delivery of care. |
| SMART Apps | Healthcare applications that adhere to the SMART on FHIR specification, allowing them to be launched from within point of care applications and integrate seamlessly to enhance clinical workflows and patient care. |
| FHIR Server | A secure server that hosts FHIR resources and supports the SMART App Launch sequence. In the SoF workflow, the FHIR server is managed by the PoC system, directly handling data access for authorized SMART applications. It provides endpoints and resources per the PoC’s requirements, ensuring compliant, reliable access to patient data and contextual resources. |
User Login: The user logs into their Point of Care system.
Patient Selection (optional): The user selects a patient within the PoC system. This step is optional and depends on the workflow.
App Catalog Fetching (optional): If needed, the PoC system queries the jurisdictional app catalog to retrieve a list of available SMART apps approved for use.
Catalog Response: The app catalog returns a JSON response that includes each app's CapabilityStatement(s), outlining supported FHIR resources and operations.
App Selection and Launch Initiation: The user selects an application from the catalog and initiates the launch sequence within the PoC system.
Generate Opaque Launch Identifier: The PoC system generates an opaque launch identifier representing the current context (e.g., selected patient, practitioner).
SMART App Launch: The PoC system launches the SMART app by passing the opaque launch identifier (launch) and the FHIR server's base URL (iss) via the launch URL.
Well-Known Configuration Fetch: Upon launch, the SMART app queries the FHIR server's well-known SMART configuration endpoint (/.well-known/smart-configuration) to obtain metadata including the authorization and token endpoints necessary for the standard OAuth 2.0 & OIDC Authorization Code flow.
Return Well-Known Metadata: The FHIR server responds with the requested metadata.
Authorization Request: Using the retrieved metadata, the SMART app redirects the user to the PoC Identity Provider's authorize endpoint. This request includes the opaque launch identifier and the required resource scopes.
Authorization Code Retrieval: The IdP redirects back to the SMART app with an authorization code based on the users current session.
Access Token Exchange: The SMART app exchanges the authorization code for an access token by querying the IdP's token endpoint.
Access Token Response: The IdP responds with an access token, an ID token (if requested), a refresh token (if requested), context resource IDs (e.g., patient ID, encounter ID, etc.), and any other relevant context that the IdP may choose to share. The IdP ensures that the issued tokens are valid, properly scoped, and contain the necessary claims before providing them to the app.
Resource Fetching: The SMART app uses the access token to fetch necessary FHIR resources from the PoC FHIR server as specified in the iss parameter. This may include resources like Patient, Practitioner, ServiceRequest and any resources for which the application has been approved.
Resource Response: The FHIR server returns the requested FHIR resources to the SMART app.
Display App to User: The SMART app presents the ready state to the user, displaying data and functionality based on the fetched FHIR resources.
The base SMART on FHIR App Launch workflow enables the integration of third-party healthcare applications within PoC systems through standardized OAuth 2.0 and FHIR-based interfaces. In the HALO framework, this sequence includes enhancements such as the HALO App Catalog and supports jurisdictions where PoC systems leverage centralized services. This design allows PoC systems to access jurisdictional FHIR servers and IdPs, facilitating integration on their behalf. These centralized services enable PoC systems, regardless of their individual technical capabilities, to provide healthcare applications with necessary FHIR resources and authentication via a consistent, interoperable platform. Below is an outline of the standard SMART App Launch sequence, describing interactions among users, the PoC system, the SMART application, the jurisdictional FHIR server, and the Identity Provider.
The $set-context operation is a custom FHIR operation that enables Point of Care (PoC) systems to securely transmit essential contextual FHIR resources to the SMART on FHIR Accelerator (SoFA) before launching an application. By invoking this operation, the PoC system passes relevant FHIR resources — such as Patient, Practitioner, and Encounter — to the SoFA. The SoFA then stores these resources in a centralized jurisdictional FHIR server, to be retrieved later by the SMART applications after launch.
For more information on this operation, including the full $set-context FHIR OperationDefinition resource, see the Operation: $set-context section of this specification.
| Actor | Description |
|---|---|
| App Catalog | A centralized repository for healthcare applications that extend the capabilities of clinical systems such as Electronic Medical Records (EMRs). A primary goal of the App Catalog is to provide healthcare providers across Canada with access to jurisdictionally approved third-party applications, streamlining the discovery, configuration, and rollout of applications to improve patient care and clinical workflows. For more information, see the App Catalog page. |
| Identity Provider (IdP) | In the SoFA context, the Identity Provider (IdP) is managed at the jurisdictional level to support PoC systems without native identity management. This central IdP securely coordinates with both the PoC system and a jurisdictional FHIR server, enabling clinical context sharing through operations like $set-context |
| Point of Care (PoC) | A local system (e.g., an EMR), used by healthcare professionals to support the delivery of care. |
| SMART Apps | Healthcare applications that adhere to the SMART on FHIR specification, allowing them to be launched from within point of care applications and integrate seamlessly to enhance clinical workflows and patient care. |
| SMART on FHIR Accelerator (SoFA) | The SMART on FHIR® Accelerator is intended to be used when a PoC system does not have the ability to make a FHIR® server available for access by external systems. Jurisdictions are expected to provide a Context Management System and a FHIR® server to support its use. |
User Login: The user logs into their Point of Care system.
Patient Selection (optional): The user selects a patient within the PoC system. This step is optional and depends on the workflow.
App Catalog Fetching (optional): If needed, the PoC system queries the jurisdictional app catalog to retrieve a list of available SMART apps approved for use.
Catalog Response: The app catalog returns a JSON response that includes each app's CapabilityStatement(s), outlining supported FHIR resources and operations.
App Selection and Launch Initiation: The user selects an application from the catalog and initiates the launch sequence within the PoC system.
Authorization Request to IdP: The PoC system redirects the user to the jurisdictional Identity Provider's authorize endpoint to initiate authentication and authorization.
Authorization Code Retrieval: If the user is not already authenticated with the IdP, they are prompted to log in. After successful authentication, the IdP redirects back to the PoC system with an authorization code.
Access Token Request: The PoC system exchanges the authorization code for an access token by querying the jurisdictional IdP's token endpoint, passing the required scopes.
Access Token Response: The jurisdictional IdP responds with an access token, an ID token (if requested), a refresh token (if requested), context resource IDs (e.g., patient ID, encounter ID, etc.), and any other relevant context that the IdP may choose to share. The IdP ensures that the issued tokens are valid, properly scoped, and contain the necessary claims before providing them to the app.
Context Preparation: The PoC system prepares the context based on the selected app's CapabilityStatement. This includes identifying the relevant FHIR resources needed for the app to function (e.g., Patient, Practitioner).
Set Context via SoFA: The PoC system executes the $set-context operation against the SoFA, passing the necessary FHIR resources to establish the clinical context for the selected app.
FHIR Resource Storage: The SoFA stores the contextual FHIR resources and generates an opaque launch identifier that acts as a reference to the current clinical context.
Context Metadata Response Returned: The SoFA returns the identifier it generated along with any other relevant context metadata back to the PoC application.
Note: From this step onward, the workflow mirrors the traditional SMART on FHIR launch sequence, with the primary differences being that the driving application passes centralized services (e.g., the SoFA) in the launch parameters (
issandlaunch) instead of PoC-provided services, and the Identity Provider (IdP) is informed of the context by the jurisdictional SoFA rather than by the PoC.
SMART App Launch: The PoC system launches the SMART app by passing the opaque launch identifier (launch) and the SoFA's base FHIR URL (iss) via the launch URL.
Well-Known Configuration Fetch: Upon launch, the SMART app queries the SoFA's well-known SMART configuration endpoint (/.well-known/smart-configuration) to obtain metadata including the authorization and token endpoints necessary for the standard OAuth 2.0 & OIDC Authorization Code flow.
Return Well-Known Metadata: The SoFA responds with the requested metadata.
Authorization Request: Using the retrieved metadata, the SMART app redirects the user to the PoC Identity Provider's authorize endpoint. This request includes the opaque launch identifier and the required resource scopes.
Authorization Code Retrieval: The IdP redirects back to the SMART app with an authorization code based on the users current session.
Access Token Exchange: The SMART app exchanges the authorization code for an access token by querying the IdP's token endpoint.
Access Token Response: The IdP responds with an access token, an ID token (if requested), a refresh token (if requested), context resource IDs (e.g., patient ID, encounter ID, etc.), and any other relevant context that the IdP may choose to share. The IdP ensures that the issued tokens are valid, properly scoped, and contain the necessary claims before providing them to the app.
Resource Fetching: The SMART app uses the access token to fetch necessary jurisdictional FHIR resources from the SoFA as specified in the iss parameter. This may include resources like Patient, Practitioner, ServiceRequest and any resources for which the application has been approved.
Resource Response: The SoFA returns the requested FHIR resources to the SMART app.
Display App to User: The SMART app presents the ready state to the user, displaying data and functionality based on the fetched FHIR resources.