New Zealand NHI IG
1.5.4 - Release

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.

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
Strict OAuth2 Authorization Code FlowHealth ConsumerHealth ConsumerClient applicationClient applicationMHA LoginMHA Login«idp» B2C«idp» B2C<FHIR API> NHI<FHIR API> NHIView my NHI record302 redirect to MHA login(client_id, scope, callback)Post login form (username,password, consent)Consent requiredConsent providedVerify credentials()302 redirect to client appcallback (code)Callback (code)Get access token (code,client_id, client_secret)return access token()Get Patient (NHI,token,APIkey)Validate[]Strict OIDC user infoGet user NHIAuthorise()Return Patient resourceDisplay Patient resource
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
Strict OAuth2 Authorization Code Flow - Update my NHI recordHealth ConsumerHealth ConsumerClient applicationClient applicationMHA LoginMHA Login«idp» B2C«idp» B2C<FHIR API> NHI<FHIR API> NHIProvide details to beupdatedUpdate Patient(NHI,PatientVersion,Token,APIkey)Validate[]Strict OIDC user infoGet user NHIAuthorise()Update Patient recordReturn Updated PatientresourceDisplay updated Patientresource
Update my NHI - Important information
Reference Comments
Oauth scope patient:Patient.u
Operations available
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
Rules - $set-address
  • All rules from $set-address apply
  • Rules - $remove-postal-address
  • All rules from $remove-postal-address apply
  • Rules - $update-identity
    Future scope
  • TBC