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.
While the App Launch component defines HALO's primary application launch flow, including both the baseline SMART EHR Launch pattern and the SoFA variant used where jurisdictional infrastructure is introduced, this component addresses an important flow not covered by those patterns: system-to-system integrations that must operate without a user-driven app launch, interactive authorization step, or active clinical session. It defines how HALO leverages the SMART Backend Services authorization specification in the context of PoC systems that host their own FHIR server and authorization server, enabling trusted external services to read from or write to PoC-managed FHIR resources where that access has been pre-authorized using the OAuth 2.0 client credentials grant with a signed JWT client assertion to obtain short-lived access tokens.
Note: Support for backend service patterns in PoC systems that rely on centralized jurisdictional infrastructure (e.g., the SoFA workflow) is out of scope for this release and will be addressed in a future iteration of the HALO Framework.
Backend services authorization is applicable in several system-to-system scenarios within the HALO ecosystem, including:
In all cases, the backend service SHALL have been pre-approved by the PoC's authorization server to access the specific set of FHIR resources required for its function, prior to making any runtime access token requests.
Backend service onboarding and registration are one-time setup activities performed before a backend service can operate against a PoC system. This process establishes trust between the backend service client and the PoC authorization server, records the client's approved scope of access, and defines how the authorization server will later verify the client's signed assertions.
In HALO, onboarding and registration are distinct from runtime authorization. Registration is where the backend service is identified, approved, assigned a client_id, and associated with the public key material that will be used to validate its future authentication requests. Runtime authorization, by contrast, occurs later when the backend service requests short-lived access tokens and uses those tokens to access the PoC FHIR API.
One-time onboarding steps:
| Actor | Description |
|---|---|
| Backend Service | A system-to-system client that authenticates using the SMART Backend Services pattern to obtain access tokens and interact with PoC-hosted FHIR APIs. |
| PoC FHIR Server | The Point of Care FHIR server that exposes the SMART well-known configuration and serves protected FHIR resources to authorized backend services. |
| PoC Authorization Server | The Point of Care authorization server that supports backend service registration, validates client assertions, and issues access tokens. |
PoC systems that support Backend Services SHALL expose a SMART configuration document at /.well-known/smart-configuration relative to the FHIR base URL. The configuration SHALL advertise the following metadata to enable discovery of support for Backend Services:
grant_types_supported: SHALL include client_credentials, indicating that the authorization server supports the OAuth 2.0 Client Credentials grant used by SMART Backend Services.token_endpoint: SHALL identify the absolute URL of the OAuth 2.0 token endpoint used by Backend Services to request access tokens.capabilities: SHALL include client-confidential-asymmetric, indicating support for SMART confidential clients that authenticate using asymmetric keys and signed JWT assertions.token_endpoint_auth_methods_supported: SHALL include private_key_jwt, indicating that Backend Services can authenticate to the token endpoint using a signed JWT client assertion.token_endpoint_auth_signing_alg_values_supported: SHALL include at least one of RS384 or ES384, identifying an asymmetric signing algorithm supported by the authorization server for validating client authentication JWTs.scopes_supported: SHALL advertise the SMART scopes available to Backend Services, including applicable system/ scopes supported by the PoC.For more information, see the FHIR Authorization Endpoint and Capabilities Discovery using a Well-Known Uniform Resource Identifiers (URIs), Retrieve .well-known/smart-configuration, and Client Authentication: Asymmetric (public key) sections of the SMART App Launch specification.
Backend services in HALO are registered as entries in the App Catalog, enabling PoC administrators to discover available services and initiate the onboarding process.
Because the next step after PoC approval may vary by jurisdiction and deployment, HALO introduces a bootstrap mechanism through which the PoC can provide the backend service with the initial context it needs to discover metadata, evaluate trust, and determine how backend service interactions should proceed.
Backend services that rely on PoC-initiated onboarding SHALL advertise an onboardingEndpoint identifying the URL of the client's Operation: $initiate-onboarding operation endpoint. This pattern is particularly applicable to standalone backend services that do not provide a user-facing launch mechanism through which onboarding can otherwise be initiated. Other backend services SHOULD support this mechanism where appropriate.
When onboarding is initiated through this mechanism, the PoC SHALL invoke the $initiate-onboarding operation at the endpoint advertised within the App Catalog, passing the base URL of its FHIR server as the iss parameter along with an offboardingChallenge derived from a verifier it generates and retains for later use during offboarding. The backend service uses this information to evaluate the requesting PoC and determine the appropriate next onboarding steps. These may include retrieving the PoC's SMART configuration, Dynamic Client Registration where supported, jurisdiction-specific trust-establishment processes, or preparation for future FHIR API access.
For details on the $initiate-onboarding operation, including its parameters and expected behaviour, see Operation: $initiate-onboarding. For the App Catalog onboardingEndpoint property definition, see App Catalog.
When a PoC disables or removes a previously onboarded backend service, it SHALL invoke the Backend Service's $offboard operation at the offboardingEndpoint advertised in the App Catalog. The request includes the PoC FHIR server base URL as the iss parameter along with the offboardingVerifier retained from the original $initiate-onboarding invocation, allowing the Backend Service to confirm the request originates from the same PoC before it withdraws the relationship.
Upon accepting the request, the Backend Service SHALL cease requesting access tokens from the identified PoC authorization server and SHALL cease attempting to access that PoC's FHIR APIs. The Backend Service SHALL treat the operation as idempotent and return a successful OperationOutcome when no active relationship exists, since the requested end state has already been reached.
The $offboard operation does not itself revoke previously issued access tokens or prescribe whether the PoC authorization server retains or removes the client's registration. Those activities remain subject to the capabilities and policies of the participating systems. For complete operation requirements, see Operation: $offboard.
Before a backend service can request an access token at runtime, it SHALL be registered with the PoC authorization server. In the HALO Framework, this is a one-time onboarding step that establishes trust between the backend service and the PoC, records the client's approved scope of access, and defines how the authorization server will later verify signed client assertions. HALO recommends that PoC authorization servers that support backend services support the OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591) for this registration step.
HALO adopts the registration_endpoint metadata element as defined by RFC 8414 and exposed through the SMART .well-known/smart-configuration endpoint. For HALO, PoC authorization servers supporting Dynamic Client Registration for Backend Services SHALL include this element in their SMART configuration. This endpoint identifies where a Backend Service submits its Dynamic Client Registration request to initiate registration with the PoC authorization server.
At registration time, the backend service SHALL declare that it will use the OAuth 2.0 client credentials grant (client_credentials) together with asymmetric client authentication (private_key_jwt). In practical terms, this tells the PoC authorization server that the client will authenticate itself by signing a JWT with its private key and that no end-user authorization interaction will occur during token acquisition.
The backend service SHALL also register the public key material that the PoC authorization server will use to validate those signatures. This key material SHALL be represented as a JSON Web Key Set (JWKS), as defined in RFC 7517, and the client SHALL protect the corresponding private key against unauthorized disclosure, use, or modification.
The SMART App Launch v2.1.0 — Client Authentication: Asymmetric (public key) profile supports use of a hosted JWKS endpoint through jwks_uri and also permits public keys to be supplied inline during client registration. HALO supports the hosted jwks_uri pattern only. PoC authorization servers SHALL support jwks_uri, and backend services SHALL host and register a JWKS endpoint containing their public key material. Although permitted by the base SMART App Launch specification, inline JWKS submission is strongly discouraged by SMART and is considered out of scope for HALO. Backend services SHOULD manage their JWKS, including key rotation, in accordance with RFC 7517.
In the hosted JWKS endpoint pattern, the backend service exposes a TLS-protected URL from which its JWKS can be fetched without client authentication. This approach allows the PoC authorization server to use current public keys while avoiding the need to maintain and protect a stored JWK Set. The backend service SHOULD include a Cache-Control header in its JWKS response. The PoC authorization server SHOULD cache the JWKS in accordance with that header and SHALL NOT cache it for longer than the period indicated by the header.
Once registration is complete, the PoC authorization server assigns the backend service a client_id. The backend service SHALL use that client_id in all subsequent token requests.
For the complete SMART requirements underlying this registration pattern, refer to the Registering a client (communicating public keys) section of the SMART App Launch v2.1.0 specification.
The following sequence diagram illustrates the dynamic client registration (DCR) interaction between the backend service and the PoC authorization server. DCR is not required but is strongly recommended over other manual out-of-band registration mechanisms.
Fetch Well-Known Configuration: The backend service retrieves the PoC FHIR server's /.well-known/smart-configuration document.
Return Well-Known Metadata: The PoC FHIR server returns SMART metadata, including the registration_endpoint when the PoC advertises one.
Determine Registration Endpoint: The backend service identifies the Dynamic Client Registration endpoint from the returned metadata.
Prepare Registration Metadata and Key Material: The backend service prepares the client metadata and public key material that it will provide to the PoC authorization server.
Submit Dynamic Client Registration Request: The backend service sends a DCR request to the PoC authorization server, including its metadata, JWKS URL, and a signed software statement endorsed by the jurisdiction.
Validate and Record JWKS URL: The PoC authorization server validates the registration request and records the backend service's registered JWKS URL for subsequent key retrieval.
Record Approved Registration Details: The PoC authorization server verifies the client's identity and validity and then stores the approved registration details and associated pre-authorized backend service access.
Return Registration Confirmation: The PoC authorization server returns a registration response, including the assigned client_id.
Runtime authorization is the recurring process used by a registered backend service to obtain access to protected PoC FHIR resources. Unlike onboarding and registration, which establish the client's identity, trust relationship, approved access, and key material ahead of time, runtime authorization occurs each time the backend service needs an access token to interact with the PoC FHIR API.
At runtime, the backend service discovers the PoC authorization server configuration and authenticates to the token endpoint using the SMART Backend Services pattern. The authorization server evaluates the request against the client's registered identity, validated client assertion, and pre-authorized permissions and, if successful, issues a short-lived access token. The backend service then presents that token when accessing protected FHIR resources. No interactive user launch, user authorization screen, or active clinical session is involved.
Runtime authorization steps:
At runtime, before requesting an access token, the backend service SHALL retrieve the PoC authorization server's SMART configuration metadata from the well-known endpoint, formed by appending /.well-known/smart-configuration to the PoC FHIR server's base URL. The client inspects the returned JSON document to identify the token_endpoint URL and verify that the server supports the asymmetric confidential-client pattern required for backend services.
PoC authorization servers that support backend services using asymmetric client authentication SHALL advertise support for the SMART client-confidential-asymmetric capability in their SMART configuration metadata and SHALL include private_key_jwt in token_endpoint_auth_methods_supported. The backend service SHALL verify that this capability is present and SHALL NOT assume that asymmetric confidential-client authentication is supported if it is absent. The client SHALL also verify that the returned metadata is consistent with that advertised capability by confirming that token_endpoint_auth_methods_supported includes private_key_jwt and that token_endpoint_auth_signing_alg_values_supported includes one or both of the RS384 or ES384 signing algorithms.
For more information on this discovery mechanism, refer to the FHIR Authorization Endpoint and Capabilities Discovery section of the SMART App Launch specification.
To obtain an access token, the backend service uses the OAuth 2.0 client credentials grant (grant_type=client_credentials), authenticating to the token endpoint via a JWT client assertion rather than an interactive user authorization step. Unlike the user-facing EHR Launch flow, no runtime end-user authorization interaction occurs as part of this token request.
Before making the token request, the backend service SHALL generate a one-time-use authentication JWT and sign it with the private key corresponding to the public key material it provided the PoC authorization server during registration.
The backend service then submits an HTTP POST to the token endpoint using application/x-www-form-urlencoded content with, at minimum, the following parameters: grant_type=client_credentials, client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer, client_assertion=<signed JWT>, and the requested scope value.
The authorization server validates the JWT signature and claims, confirms that the jti has not already been used within the allowed JWT lifetime, verifies that the assertion is consistent with the client's registered key material, and checks that the requested scopes are within the client's pre-authorized permissions. If the request is valid and authorized, the authorization server issues a short-lived bearer access token. Refresh tokens SHALL NOT be issued; clients requiring continued access can request new access tokens as needed by repeating this step.
For full details on the JWT assertion structure, token request parameters, and token response properties, refer to the Obtain access token section of the SMART App Launch specification and the Client Authentication: Asymmetric (public key) profile.
With a valid access token, the backend service MAY issue FHIR API requests to the PoC FHIR server. Each request SHALL include the access token as a Bearer token in the Authorization HTTP header:
Authorization: Bearer <access_token>
The PoC FHIR server SHALL validate the access token, confirm that it has not expired, and verify that the token's granted scopes are sufficient for the requested resource and interaction type. The mechanism by which the FHIR server validates the token (e.g., via introspection or local JWT validation) is beyond the scope of this specification.
The following sequence diagram illustrates the runtime authorization portion of the backend services flow after onboarding has been completed.
Fetch Well-Known Configuration: The backend service retrieves the PoC FHIR server's /.well-known/smart-configuration document.
Return Well-Known Metadata: The PoC FHIR server returns the SMART metadata document, including the endpoints and capabilities needed for backend services authorization.
Validate Metadata: The backend service validates the returned metadata and confirms that the PoC supports the required backend services capabilities.
Generate Client Assertion: The backend service creates a one-time-use signed JWT client assertion for token endpoint authentication.
Submit Access Token Request: The backend service sends a token request to the PoC authorization server using the client credentials grant and the signed JWT assertion.
Validate Assertion and Requested Scopes: The PoC authorization server validates the client assertion, applies replay protections, and confirms that the requested scopes are within the backend service's pre-authorized permissions.
Return Access Token: If the request is valid, the authorization server returns an access token response, including the access token, token type, expiry, and granted scope.
Access FHIR API: When an access token is issued, the backend service uses it to request FHIR resources or interactions from the PoC FHIR server.
Validate Access Token: The PoC FHIR server validates the access token and verifies that the granted scope permits the requested interaction.
Return FHIR Response: The PoC FHIR server returns the requested resources or confirmation of the interaction.
Return Authorization Error: If the token request fails validation or authorization, the PoC authorization server returns an authorization error.
Backend services clients SHALL request access using system/ scopes. These scopes follow the SMART scopes syntax and allow a client to request access to resources across all patients, independent of any individual user context. For example:
system/Patient.rs — access to read Patient resources and search for Patient resourcessystem/Observation.r — read access to Observation resourcessystem/*.rs — read and search access to all resource typesThe authorization server applies the requested scopes as an additional constraint on top of the pre-authorized access that was established at registration time. The client SHALL only request scopes that are consistent with its pre-approved access. The server SHALL NOT grant a scope that exceeds the client's pre-authorized permissions.
The SMART App Launch specification supports wildcards at two levels within the system/ scope syntax:
*, granting access to all resource types for the specified interactions (e.g., system/*.rs)..*, granting all interactions for the specified resource type (e.g., system/Patient.*).Both forms are not explicitly prohibited within HALO; however, their use requires careful consideration by both parties. PoC vendors should consider the use of wildcard scopes with extreme caution, given the breadth of access they convey. Backend services SHOULD NOT request wildcard scopes unless absolutely necessary, and SHOULD operate under the assumption that most PoC vendors will not support them. Backend services SHOULD instead enumerate the specific resource types and interactions they require, both at registration time and in each token request.
For full details on the SMART scopes syntax, see the Scopes and Launch Context section of the SMART App Launch specification.
Backend Services and SMART Apps may be implemented independently or used together in a broader workflow:
A Backend Service does not inherit the user's identity, launch context, access token, authorization, or scopes from a SMART App session. It remains a separate OAuth client and accesses the PoC FHIR API under its own pre-authorized permissions and granted system/ scopes. Where both integrations participate in the same workflow, the service's internal implementation is responsible for correlating identity and context and for enforcing the appropriate relationship between the user's SMART App permissions and the Backend Service's independently granted access.
Implementers of backend services authorization in the HALO Framework SHALL adhere to the following security requirements and recommendations:
expires_in value SHOULD NOT exceed 300 seconds (five minutes). Clients SHALL request new tokens as needed rather than caching tokens for extended periods, as per the SMART Backend Services specification.jti value has not been previously encountered for the same iss within the permitted JWT lifetime, as per the Client Authentication: Asymmetric (public key) profile.For broader security, authentication, and privacy guidance applicable to all HALO integration patterns, see the Design Considerations and Privacy and Security Guidance pages.