New Zealand NHI IG - Local Development build (v1.5.4) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Consumer Facing Application Authentication

Background

Te Whatu Ora has implemented a Consumer Facing API Authentication Pattern to allow a person to access and update information held about them using their NHI number. The pattern describes how an end user’s NHI can be securely established and communicated to a resource provider via a REST API. This is an implementation of the OAUTH2/OIDC Authorisation Code flow.

The trusted identity provider (idp) is My Health Account (MHA). For more information click here

Prerequisites

• The person’s NHI must be verified with MHA to a confidence level of at least 3N.
• The API will only grant the end user access to their own NHI information.
• The Client Application must be registered with MHA.
• The Client Application must be permitted SMART patient scopes on the resource being accessed.
• The IdP must issue access tokens with SMART patient scopes
• The IdP must have obtained end user consent prior to issuing the access token.

Consumer Facing API and the NHI FHIR Service

Client Onboarding

The client registration process involves both the NHI FHIR service and the IdP.

• The IdP will provide the client_ID, client_secret and SMART on FHIR scopes.
• The NHI FHIR service will provide an API Key and approve any scopes granted to the client.
  • OAuth2 scopes are granted by the IdP to the client application, not the end user. For more information see online onboarding request form.

Compliance Testing

Compliance testing will need to be completed for both the idp and the NHI FHIR service.
For MHA Compliance information For more information click here.
To view the NHI FHIR Consumer Facing API Compliance tests Click here.

Consumer Facing API - Component View

• Health Consumer - a person with an NHI
• Resource Provider (NHI FHIR API)- the system that implements the API and provides access to a resource referenceable by NHI (NHI FHIR API).
• Client Application - a system that consumes the API on behalf of the health consumer
• My Health Account
  • IDP - Identity Provider, able to grant access tokens
  • Login - login UI via which the Health Consumer presents their credential’s to MHA in order to establish their identity, and provide their consent to the Client Application
  • User Info - OIDC endpoint which enables the Resource Provider to obtain the NHI number assigned to the Health Consumer

Access my NHI

Communication View

Access my NHI - Important information

Reference	Comments
Oauth scope	patient:Patient.r
Operation	Patient read GET[Endpoint]/Patient/[nhi-id]
Get Rule	A request from a consumer facing application can only access the NHI record of the requester i.e. the NHI linked to the MHA
Attributes returned with a Get Request	NHI numbers Live and all dormants Names All names and name details Addresses Residential and Postal addresses Gender Gender gender-original-text(if present) Birthdate All Birthdate details BirthPlace All BirthPlace details DeathDate All Date of death details Ethnicity All ethnicity details NZ Citizenship All NZ Citizenship status details DHB The DHB code, derived from the person's residential address
Future scope	Telecom / Contacts All contact details (email address, mobile phone and home phone(if present) General practitioner Returns the person's enrolled General Practice details included as a contained ‘PractitionerRole resource’

For more information on the attributes please see the NHI FHIR Patient profile

Update my NHI

Communication View

Update my NHI - Important information

Reference	Comments
Oauth scope	patient:Patient.u
Operations available	$set-preferred-name $set-address $remove-postal-address $update-identity
Rules - general	An update request from a consumer facing application can only update the NHI record of the requester i.e. the NHI linked to the MHA
Rules - $set-preferred-name	All rules from $set-preferred-name apply, and Must not set Preferred name to a BabyOf name
Rules - $set-address	All rules from $set-address apply
Rules - $remove-postal-address	All rules from $remove-postal-address apply
Rules - $update-identity	All rules from $update-identity apply Ethnicity Application must present the standard ethnicity question and supply the consumer selected reponses Gender Application must present the and supply the consumer selected or entered text response
Future scope	TBC