National Digital Health Authorisation Service - Developer Guide

Introduction

The Health Connect Australia Provider Directory (HCAPD) server is an OAuth 2.0 resource server requiring valid OAuth 2.0 access tokens presented by a client to access resources.

The HCAPD API access tokens are issued by the National Digital Health Authorisation Service (NDHAS), which implements an OAuth 2.0 authorization server. The HCAPD APIs currently offers access to organisations using system-based authorisation, which is implemented following the OAuth 2.0 client credentials grant as described in section 1.3.4 of RFC 6749.

A HCAPD API access token represents the permissions that the NDHAS determines for the OAuth 2.0 client at the time when the access token is requested. A HCAPD client must

• be a confidential client that is registered with the NDHAS following the Dynamic Client Registration protocol as described in RFC 7591 
• authenticate using a trusted certificate as described in RFC 8705. The current trusted certificates are issued by the National Authentication Service for Health (NASH). 
• perform Dynamic Client Registration using a Conformant Software and possess a NASH certificate.

Conformant Software

A client seeking registration with the NDHAS must use a software product that has achieved the relevant conformance status and recorded within the Register of Conformance. 

Client

A client is an instance of a conformant software that an Organisation uses to digitally interact with the NDHAS or the HCAPD.

NASH Certificate

To connect to the NDHAS and HCAPD, either of the following two types of NASH certificate can be used 

• HPI-O NASH certificate - issued to a Healthcare Provider Organisation 
• CSP NASH certificate - issued to a Contracted Service Provider

Please refer Services Australia: Apply for a NASH Certificate for further information and process to obtain NASH Certificate.

When to use HPI-O NASH Certificate?

If the conformant client is operated by an entity registered as a Healthcare Provider Organisation with the Services Australia Health Identifiers (HI) Service, then the client will

• use CIS as the value for client system type data item, 
• use Healthcare Provider Organisation (the operator)’s HPI-O NASH certificate for Dynamic Client Registration and access token request.

When to use CSP NASH Certificate?

If the conformant client is operated by an entity registered as a Contracted Service Provider with the HI Service, then the client will

• use CSP as the value for client system type data item, 
• use Contracted Service Provider (the operator)’s CSP NASH certificate for Dynamic Client Registration and access token request.

Please refer to the HI Service web page for further information and process to register with the HI Service.

Dynamic Client Registration

A client must submit a dynamic client registration request to the NHDAS to register its client details and obtain a client_id. 

The client_id is then used to identify the client to NHDAS in any subsequent access token requests. 

Dynamic client registration requires that the client must authenticate by presenting a trusted certificate, which is currently issued by NASH. The client must support mTLS version 1.2 or later.

Step 1: Initial Registration

The following diagram shows the high-level sequence of activities of Dynamic Client Registration

The sequence has the following steps:

1. The client generates a dynamic client registration http request with registration content as the request payload (body) as a JSON object. The table below describes the JSON object (i.e. registration parameters)

Registration Parameters:

Example Request

2. The client sends the dynamic client registration request to the NDHAS registration endpoint via a https POST and presents a client NASH certificate for mTLS.
    
3. The NDHAS validates the client’s NASH certificate and checks it against the Certificate Revocation List (CRL).
    
4. The NDHAS checks the software product details (software_id and software_version) provided in the dynamic client registration request against the Register of Conformance to ensure the software product is conformant for accessing the HCAPD. NDHAS validates the Scope value if provided.
    
5. The NDHAS generates a client_id and record it with the registration details.
    
6. The NDHAS returns the client_id to the client.

Example Response:

• client_id is the OAuth 2.0 client identifier string. It is unique to the registered client within NDHAS.
• registration_client_uri is a string containing the fully qualified URL for the client configuration endpoint, which can be used to read/modify/cancel client registration.
• registration_access_token is a string containing the access token to be used at the client configuration endpoint.

Step 2: Read Registration

Upon successful completion of a client registration, the client can read the registration information by issuing a GET operation against the endpoint in registration_client_uri and using registration_access_token as authorisation. This operation requires the client's certificate for mTLS.

Example Request

Step 3: Modify Registration

After a successful client registration, the client may modify the registration by issuing a PUT operation against the endpoint in registration_client_uri and using registration_access_token as authorisation. 

Only client_name and scope can be modified. This operation requires the client's certificate for mTLS.

Example Request

Step 4: Cancel Registration

To cancel an existing registration, the client issues a DELETE operation against the endpoint in registration_client_uri and using registration_access_token as authorisation. This operation requires the client's certificate for mTLS.

Example Request

Step 5: Access Token Request

The access token request requires the registered client to present a certificate that has the same common name as the certificate used for dynamic client registration. 

Client certificate renewal does not require the client to be re-registered, as long as the renewed certificate has the same common name. The client must support mTLS version 1.2 or later.

The following diagram shows the high-level sequence of access token request.

The sequence has the following steps:

A: The client generates a token request which includes the following parameters.

Token Request Parameters:

Example Request

B: The client sends the token request to the NDHAS via a http POST and presents a client NASH certificate for mTLS.

C: The NDHAS validates the client’s NASH certificate and checks it against the Certificate Revocation List (CRL).

D: The NDHAS checks the software product details registered for the client against the Register of Conformance to ensure the software product remains conformant since registration.

E: If the client_system_type is CIS the NDHAS checks that the access_org_id in the request matches the organisation identifier in the client certificate presented for mTLS.

F: If the client_system_type is CSP the NDHAS checks with the Healthcare Identifiers Service that the CSP as identified by the client certificate is authorised to access the HCAPD on behalf of the organisation identified by the access_org_id (HPI-O).

G: The NDHAS determines the scope to be included in the access token.

H: The NDHAS generates a JWT access token and signs it using the HCAAS private key.

I: The NDHAS returns the access token to the client.

Step 6: Access Token Response

The successful access token response will contain the following details:

Access Token JWT Structure

Header

Payload

Signature

• The JWT is signed using the NDHAS private key and assembled using JWS compact serialisation as per RFC 7515.
• Computed over base64url(header) + "." + base64url(payload) using the private key corresponding to kid.

Step 7: Using An Access Token

After obtaining an access token, the client can access the HCAPD APIs by presenting the access token and the client’s NASH certificate for mTLS.