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
- Publishing system:
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 Type | Description | Supported 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:
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:
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:
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 Type | Description | Supported 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:
| 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 set | Next: Generate JWT
