New Zealand NHI IG
1.6.5 - Release

New Zealand NHI IG - Local Development build (v1.6.5) 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 email the integration team

#### 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