Skip to main content
ID
DG-3089
Type
Guide
Version
1.0
Status
Active
Created date
Updated date

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 [email protected]

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: [email protected]
  • 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

Role TypeDescriptionSupported scoping object type/s
PS_Read

This roleType models a set of permissions that are assigned to ClientSystems, acting on behalf of publishers, which require read-only access to either:

  • a specific healthcare service (identified by the HealthcareService scoping object) or
  • a location and all the healthcare services provided at that location (identified by the associated Location and
  • all the locations and healthcare services provided by an organisation (identified by the Organisation scoping object), including healthcare services provided by any of its subordinate organisations.

The target set of objects to which access is granted is determined by the scoping object.

Organisation
Location
HealthcareService
PS_ServicesMgr

This roleType models a set of permissions that are assigned to systems, acting on behalf of publishers, that manage either:

  • a specific healthcare service (identified by the HealthcareService scoping object) or
  • all the locations and healthcare services provided by an organisation (identified by the Organisation scoping object), including healthcare services provided by any of its subordinate organisations.
  • a location and all the healthcare services provided at that location (identified by the associated Location scopingObject)

The target set of objects to which access is granted is determined by the scoping object.

Organisation
Location
HealthcareService
PS_PractitionerMgr

This roleType models a set of permissions that are assigned to systems that manage the information about Practitioner roles associated with:

  • a specific healthcare service (identified by the HealthcareService scoping object or
  • all the healthcare services provided at a location (identified by the associated Location scopingObject)
  • all the healthcare services provided by an organisation (identified by the Organisation scoping object), including healthcare services provided by any of its subordinate organisations.

The target set of objects to which access is granted is determined by the scoping object.

Organisation
Location
HealthcareService
PS_PublicationMgr
This roleType models a set of permissions that are assigned to systems that manage the publication of service offerings (including providing subscriber-specific identifiers for published service offerings) provided by the organisation, location or healthcare service that is identified by the scopingObject, including service offerings provided by any of its subordinate organisations.
Organisation
Location
HealthcareService
PS_Synchroniser
This roleType is assigned to client systems that have declared conformance to the ‘Synchronise Data’ role.  It is used by the PCA™ Portal to indicate to users if they are using a client system that doesn’t respect changes made through other channels.
Organisation

Role types assigned to systems operated on behalf of subscribers

Role TypeDescriptionSupported scoping object type/s
SS_Updater

This roleType allows a system operating on behalf of the subscriber organisation that is identified by the scopingObject, to update:

  • subscriber identifiers for subscribing systems owned by (or shared with) the subscriber organisation
  • the match status for organisations, healthcare services, practitioner roles, and locations published to a subscribing organisation’s partner service
Organisation
SS_Receiver
This roleType allows a system operating on behalf of the subscriber organisation that is identified by the scopingObject, to retrieve service offerings that have been published to that subscriber organisation
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 setNext: Generate JWT

Trade marks of the Australian Digital Health Agency: 
Provider Connect Australia™, Helping healthcare providers stay connected™

PCA logo
PCA logo

On this page