PCA™ - Register client

Quick intro

Initial access token

Access to register endpoint requires an initial access token (IAT) of type bearer. Publisher and Subscriber organisations must now request an IAT by registering their software details with the PCA™ Operator first.

This will be in the form of an email to help@digitalhealth.gov.au

Subject: IAT request – Vendor name - Software name and version

Body:

• Environment: Production / Vendor Testing
• Vendor name: Cool Vendor
• Software name: my-client-name (as it will appear in the 'software_id' client registration request)
• Software version: 1.0.0 (as it will appear in the 'software_version' client registration request)
• Contact name: Bob Cool
• Contact email: cool@vendor.com
• Contact telecom: 1800 800 800
• Access control authorisation: User-based / System-based
• Redirect URI: https:://myapp (only needed for User-based authorisation)
• Scopes requested:
  • Publishing system:
    • Read only (PS_Read): Y/N
    • Manage Healthcare Services (PS_ServicesMgr): Y/N
    • Manage Practitioner Roles (PS_PractitionerMgr): Y/N
    • Manage publication of service offerings (PS_PublicationMgr): Y/N
    • Synchronise data (PS_Synchroniser): Y/N
  • Subscribing system:
     
    • Update subscriber identifiers and match status (SS_Updater): Y/N
    • Retrieve service offerings (SS_Receiver): Y/N

The response to the email will contain the initial access token.

Production IATs are issued to organisations (one per product version) who have declared to meet the mandatory conformance requirements for scopes selected and submit an Implementation Conformance Statement (ICS).

Public key registration

The client needs to register the public key it will use to authenticate itself to the PCA™ Identity and Access Manager.

The public key needs be conveyed to the PCA™ Identity and Access Manager in a JWK structure outlined in the generate JWK set above.

The client’s JWK SHALL be shared with the PCA™ Identity and Access Manager using one of the following techniques:

• URL to JWK Set. This URL communicates the TLS-protected endpoint where the client’s public JWK Set can be found. When provided, this URL SHALL match the jku header parameter in the client’s Authorisation JWT. Advantages of this approach are that it allows a client to rotate its own keys by updating the hosted content at the JWK Set URL, assures that the public key used by the PCA™ Identity and Access Manager is current, and avoids the need for the PCA™ Identity and Access Manager to maintain and protect the JWK Set.
• JWK Set directly. If a client cannot host the JWK Set at a TLS-protected URL, it MAY supply the JWK Set directly to the PCA™ Identity and Access Manager at registration time. In this case, the PCA™ Identity and Access Manager SHALL protect the JWK Set from corruption, and SHOULD remind the client to send an update whenever the key set changes. Conveying the JWK Set directly carries the limitation that it does not enable the client to rotate its keys in-band. Including both the current and successor keys within the JWK Set helps counter this limitation. However, this approach places increased responsibility on the PCA™ Identity and Access Manager for protecting the integrity of the key(s) over time, and denies the PCA™ Identity and Access Manager the opportunity to validate the currency and integrity of the key at the time it is used.

Roles

The ClientSystem will need to declare the role types as "scope". The following role types are available:

Role types assigned to systems operated on behalf of publishers

PS_Read

Organisation

Location

HealthcareService

PS_ServicesMgr

Organisation

Location

HealthcareService

PS_PractitionerMgr

Organisation

Location

HealthcareService

PS_PublicationMgr

Organisation

Location

HealthcareService

PS_Synchroniser

Organisation

Role types assigned to systems operated on behalf of subscribers

SS_Updater

Organisation

SS_Receiver

Organisation

This operation would look like this submitting the JWK public key to PCA™.

POST /PcaAuthApi/v2/auth/register HTTP/1.1
Content-Type: application/json
Authorization: Bearer 4e4d0357-f9b5-0498-65f0-c08cad509852
User-Agent: PostmanRuntime/7.29.0
Accept: */*
Cache-Control: no-cache
Postman-Token: df66efa2-c7f0-4d67-b106-6fbc3113e78d
Host: bne-drp-trp.digitalhealth.gov.au
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 703
 
{
"software_id": "PMC Client",
"software_version": "1.0.0",
"scope": "pca:PS_ServicesMgr pca:PS_PractitionerMgr pca:PS_PublicationMgr pca:PS_Read pca:SS_PartnerServiceMgr pca:SS_Updater pca:SS_Receiver",
"jwks":
{
"keys": [
{"kty":"RSA","n":"WHD6zUYNpfdXhtx3VwxEczeUdqc5xeov6rNjf4NL3agksEfCqAx1F8Hqzv-rWFO4Ogexr5p9_fM4Gsn2Cq7sKwxxYJL-Wpg_ZVQV2C_m7c43Cr4jBgJsMHxF7LK_vpBwILpQUimJljLjfhEqFDlYaekl8bkf6TLAuX2Qu0kq1_Jlf4Q9PhnAz_EUmCox7ugMqLevF8dJWX5E4DGhsv1lqBDJ5JOpobyduzhQtOl2dpDKGwZuqogfstj2zZIqZLSCbM7TYKpiG_Zjm3YmQ9A6Rqvf4_mj9TERtjj_pWMguowsQ1YGDGd9XkAOeS-pcyqCiBjMBP7Gx8wq3waEXBewdQ","e":"AQAB","kid":"M6ElsobEdVU2G9427ZL1b7XKiHqoqKZp-2Bf3hPap_s"}
]
}
}
 
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
X-Frame-Options: DENY
Date: Wed, 19 Jan 2022 05:05:49 GMT
 
{
"client_id":"4405e420-a099-4c34-a0d2-f6cde1dba732",
"registration_client_uri":"https://bne-drp-trp.digitalhealth.gov.au/PcaAuthApi/v2/auth/register/4405e420-a099-4c34-a0d2-f6cde1dba732",
"registration_access_token":"54186715-b1b0-435f-9e05-d240b82c7759",
"software_id":"PMC Client",
"software_version":"1.0.0",
"redirect_uris":null,
"scope":"pca:PS_ServicesMgr pca:PS_PractitionerMgr pca:PS_PublicationMgr pca:PS_Read pca:SS_PartnerServiceMgr pca:SS_Updater pca:SS_Receiver",
"jwks":
{
"keys":[
{"e":"AQAB","n":"WHD6zUYNpfdXhtx3VwxEczeUdqc5xeov6rNjf4NL3agksEfCqAx1F8Hqzv-rWFO4Ogexr5p9_fM4Gsn2Cq7sKwxxYJL-Wpg_ZVQV2C_m7c43Cr4jBgJsMHxF7LK_vpBwILpQUimJljLjfhEqFDlYaekl8bkf6TLAuX2Qu0kq1_Jlf4Q9PhnAz_EUmCox7ugMqLevF8dJWX5E4DGhsv1lqBDJ5JOpobyduzhQtOl2dpDKGwZuqogfstj2zZIqZLSCbM7TYKpiG_Zjm3YmQ9A6Rqvf4_mj9TERtjj_pWMguowsQ1YGDGd9XkAOeS-pcyqCiBjMBP7Gx8wq3waEXBewdQ","kty":"RSA","kid":"M6ElsobEdVU2G9427ZL1b7XKiHqoqKZp-2Bf3hPap_s"}
]
},
"jwks_uri":null
}

What is interesting here is the following that is returned by the server:

• client_id - OAuth 2.0 client identifier string
• registration_client_uri - String containing the fully qualified URL of the client configuration endpoint for this client
• registration_access_token - String containing the access token to be used at the client configuration endpoint to perform subsequent operations upon the client registration
• redirect_uris - String containing the client's redirection endpoint, the PCA™ Identity and Access Manager redirects the user-agent to this URI upon successful authentication

 Home | Back: Generate JWK set | Next: Get authorization code