Provincial Client Registry (PCR) HL7 FHIR® Contribution Implementation Guide v1.0.0-draft1
For a full list of available versions, see the Directory of published versions
Client systems contributing demographic information to PCR through FHIR-based interfaces are required to connect through the Ontario Health ONE Access Provider Gateway. The gateway acts as the secure access point between authorized contributing systems and provincial FHIR services. It supports controlled connectivity, identity and access enforcement, transport security, and routing of approved contribution transactions to provincial registries, including the Provincial Client Registry (PCR) and Provincial Provider Registry (PPR).
For PCR contribution, the ONE Access Provider Gateway provides the non-functional connectivity layer used by contributing systems to securely submit FHIR contribution transactions such as Patient Add, Patient Update, Patient Merge, and Patient Unmerge. The gateway does not replace the functional requirements defined by this implementation guide; rather, it enables secure delivery of conformant contribution payloads to PCR. Functional requirements, including payload structure, FHIR profiles, validation rules, identifier requirements, processing outcomes, and OperationOutcome handling, remain governed by the PCR FHIR contribution specification.
Implementers are responsible for ensuring that their client systems are properly onboarded, configured, authenticated, and authorized before submitting contribution messages. This includes confirming the correct environment endpoint, obtaining required gateway and identity configuration, applying approved transport security requirements, including required request headers, and ensuring that contribution traffic can be monitored through client-side logging and audit controls.
Connectivity implementation should be coordinated with Ontario Health onboarding activities because endpoint availability, credentials, certificates, OAuth2 configuration, environment-specific URLs, and access permissions may vary between testing and production environments. Contributing systems should not submit production PHI until the required onboarding, conformance, privacy, security, and connectivity readiness activities have been completed.
To support PCR contribution connectivity through the provider gateway, implementers should use the Ontario Health connectivity documentation and contact channels summarized below. These references should be used together with PCR onboarding material, environment-specific endpoint details, and contribution conformance guidance.
| Connectivity Support Item | Purpose | Implementer Action | Reference / Contact |
|---|---|---|---|
| ONE Access Gateway Transport Specification | Defines the transport-level requirements for securely connecting client systems to the ONE Access Provider Gateway for PCR FHIR contribution traffic. | Review and implement the required transport configuration, endpoint access approach, security controls, certificate expectations, and environment-specific connection details before submitting PCR contribution messages. | ONE Access Gateway Transport Specification Download Link |
| ONE ID OpenID Connect Specification | Defines authentication and authorization expectations for securing PCR FHIR contribution requests through the approved identity and access model. | Configure the approved OAuth2/OpenID Connect flow, obtain and protect required credentials, include required token information in PCR contribution requests, and validate that access permissions align with the contributing organization and environment. | ONE ID OpenID Connect Specification Download Link |
| Gateway Connectivity Questions | Provides a contact channel for questions related to gateway connectivity, endpoint access, transport, authentication, authorization, and integration support. | Contact Ontario Health when clarification is required on gateway connectivity requirements, environment access, connectivity readiness, or gateway-specific implementation issues. | architecture@ehealthontario.on.ca |
Before submitting PCR FHIR contribution transactions, implementers should confirm the required onboarding and connectivity prerequisites with Ontario Health. At minimum, the contributing organization should confirm gateway access, environment endpoint details, certificate requirements, OAG Client ID, identity enrollment status, OAuth2 configuration, and logging readiness.
Client systems may be required to use approved certificates to establish secure transport with the ONE Access Provider Gateway. Certificate use, renewal timelines, subject details, trust chain requirements, and environment-specific installation steps should be confirmed through Ontario Health onboarding and the applicable transport specification. Implementers should ensure certificates are installed in the correct environment, protected from unauthorized access, monitored for expiry, and rotated before expiration.
The OAG Client ID identifies the approved client application or integration that is authorized to connect through the gateway. Implementers should confirm that the Client ID is assigned to the correct organization, environment, application, and PCR contribution use case. If PNEID enrollment is required, the contributing organization must complete enrollment and ensure that the enrolled identity is associated with the correct permissions before requesting or submitting PCR contribution transactions.
PCR FHIR contribution connectivity should adopt the OAuth2/OpenID Connect authorization paradigm approved through Ontario Health onboarding. The selected authorization flow must align with the contributing system type, whether the integration is system-to-system, user-delegated, or certificate-backed. Implementers should confirm the applicable flow during onboarding and should not assume that all OAuth2 flows are available for every PCR contribution use case.
| Authorization Flow | Typical Use | PCR Contribution Consideration |
|---|---|---|
| JWT Bearer Grant | Used where a signed assertion is exchanged for an access token. | May be appropriate for trusted system integrations where certificate-backed assertions or signed client assertions are required. |
| Client Credentials Flow | Used for server-to-server integrations where no individual end user is directly involved. | May be suitable for automated PCR contribution services submitted by an authorized application or source system. |
| Authorization Code Flow | Used where an authenticated user authorizes access through an interactive sign-in process. | Generally, applies to user-context scenarios and should be used only where Ontario Health confirms user-delegated access is required for the PCR contribution workflow. |
PCR FHIR contribution requests must include an OAuth access token where required by the approved gateway identity model. The token should represent the authorized client, organization, environment, and permitted scope for PCR contribution. Implementers should obtain the token using the Ontario Health-approved OAuth2/OpenID Connect flow, protect all credentials used to obtain the token, and include the access token in the request authorization header. Token claims and required scopes should be validated during onboarding and conformance testing.
| Issue Area | Potential Cause | Recommended Action |
|---|---|---|
| Certificate failure | Expired certificate, incorrect certificate, missing trust chain, or environment mismatch. | Validate certificate installation, expiry, trust chain, and environment assignment with onboarding guidance. |
| Unauthorized request | Invalid, expired, missing, or incorrectly scoped OAuth access token. | Request a new token, confirm required claims and scopes, and verify the authorization header. |
| Forbidden access | Client ID, PNEID enrollment, or permissions are not authorized for the environment or PCR contribution operation. | Confirm OAG Client ID, enrollment status, assigned permissions, and applicable PCR contribution access. |
| Endpoint or routing error | Incorrect base URL, wrong environment, unavailable route, or misconfigured gateway endpoint. | Verify the endpoint, environment, routing configuration, and PCR base URL before retrying. |