PCA Identity and Access Manager

Provider Connect Australia (PCA) - Local Development build (v24.2.0.1) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Introduction
User-based authorisation
System-based authorisation
Role based authorisation model
Information requirements
PCA API access token
PCA API access token scope
Client system credential
OAuth2 implementation
Token endpoint
Management of tokens
Introspect endpoint
Register endpoint
Client configuration endpoint

Introduction

The PCA servers (see PCA API) are OAuth 2.0 resource servers. That is, PCA API clients require valid OAuth 2.0 access tokens.

The PCA API access tokens are issued by the PCA Identity and Access Manager - i.e. it implements an OAuth 2.0 authorization server. The PCA Identity and Access Manager issues PCA API access tokens in accordance with two patterns:

user-based authorisation - in this pattern applications invoke PCA API operations in the context of active PCA user sessions.
system-based authorisation - in this pattern applications invoke PCA API operations independently of a PCA user session.

In both patterns, a PCA API access token represents the permissions that the PCA Identity and Access Manager determines for the subject (user or system) at the time when that token is presented i.e. when a PCA API operation is invoked. It determines these permissions from the current set of Authorisations stored by the PCA Identity and Access Manager for the subject (see below).

A client application must be a ‘confidential’ client as described in section 2.1 of RFC 6749. Public clients are not supported by PCA.

All client systems must be registered via the register endpoint.

User-based authorisation

In user-based authorisation, the users must be authenticated by PRODA before they will be granted authorization codes by the PCA Identity and Access Manager. That is, as well as implementing an OAuth2.0 authorization server, the PCA Identity and Access Manager also implements an OpenId Connect client of PRODA.

The PCA user-based authorisation pattern is aligned with the SMART on FHIR approach. The SMART on FHIR OAuth2.0 access token scopes are, however, insufficient to model the role based authorisation model which is used for PCA operations. Note that PCA API access token scopes (see below), unlike SMART on FHIR scopes, may depend on resource instances, e.g. "read-only access to all HealthcareServices associated with a particular Location".

The following diagram shows a typical sequence by which a client system accesses a PCA API under user-based authorisation.

Steps

The user of a PCA API client system triggers a function that requires the client system to invoke a PCA API.
The user (via a HTTP user-agent ) requests an authorization code from the authorization endpoint of the PCA Identity and Access Manager (which is acting as an OAuth2.0 authorization server).
- note that, depending on its architecture, the client system may need to launch this HTTP user-agent.
The PCA Identity and Access Manager (now acting as a OpenIDConnect client of PRODA) redirects the user-agent to the PRODA authorization endpoint and requests a PRODA authorization code.
User authenticates to PRODA.
PRODA provides the PRODA authorization code to the PCA Identity and Access Manager via the OAuth2.0 authorization code grant type.
The PCA Identity and Access Manager requests PRODA for UserInfo access and identity tokens (providing the PRODA authorization code).
If PRODA successfully authenticates the PCA Identity and Access Manager, and validates the PRODA authorization code, it responds with the requested PRODA UserInfo access and identity tokens.
If the PCA Identity and Access Manager can match the PRODA user identity to one of its existing PCA user identities, then it returns a PCA API authorization code (linked to that PCA user identity) to the user-agent.
The user-agent receives the PCA API authorization code and passes this to the client system via the OAuth2.0 authorization code grant type.
The client system requests a PCA API access token from the token endpoint of the PCA Identity and Access Manager (providing the PCA API authorization code).
If the PCA Identity and Access Manager successfully authenticates the client system, and validates the PCA API authorization code, it responds with a PCA API access token.
The client system makes a request of a PCA Server and provides the PCA API access token.
The PCA Server queries the introspect endpoint of the PCA Identity and Access Manager to validate the PCA API access token and to obtain the scope of this access token (this scope is set by the PCA Identity and Access Manager to reflect the current set of authorizations of the user that is associated with the authorization code in step 8).
The PCA Server either grants or rejects the client system request based on the status and scope obtained from the introspect endpoint.

System-based authorisation

In system-based authorisation, a client system uses the OAuth 2.0 client credentials grant type to request PCA API access tokens. The PCA Identity and Access Manager issues access tokens to client systems in accordance with the authorisation settings for the particular client system that were previously created by authorised users via the PCA portal. The PCA system-based authorisation pattern is aligned with the SMART Backend Services: Authorization Guide. A key element of this approach is that client system credentials are represented as JWT tokens that the client system signs using a private key which is not disclosed to the authorization server. The SMART Backend Services approach is profiled for PCA as described below:

PCA OAuth 2.0 access token scopes implement role based authorisations that are appropriate for the PCA operations (which support administrative, rather than clinical, workflows). The PCA role based authorisation model is described below.
PCA requires client systems to dynamically register themselves using the register endpoint of the PCA Identity and Access Manager.
PCA allows client systems to de-register themselves using the client configuration endpoint of the PCA Identity and Access Manager (the URL of this endpoint is provided in the response to the registration request).
PCA requires client systems to provide their public key, or a URL at which it can be found, to the PCA service at registration time.
If a client system provides the public key then any subsequent change of keys requires a client system to be de-registered and then re-registered (and be issued a new client id though the registration process). The PCA Operator will be able to 'replace' a client system's authorisations to avoid users having to re-authorize the new client system id.

The following diagram shows a typical sequence by which a client system accesses a PCA API under system-based authorisation.

The sequence has the following steps:

The client system creates a signed JSON Web Token which identifies itself and is signed with a RSA private key (having provided the corresponding RSA public key, or its URL, to the PCA Identity and Access Manager when the client system was registered as an OAuth 2.0 client system).
The client system requests a PCA API access token from the token endpoint of the PCA Identity and Access Manager (providing the signed JWT).
If the PCA Identity and Access Manager successfully authenticates the client system it responds with a PCA API access token.
The client system makes a request of a PCA API and provides the PCA API access token.
The PCA Server queries the introspect endpoint of the PCA Identity and Access Manager to validate the PCA API access token and to obtain the scope of this access token (this scope is set by the PCA Identity and Access Manager to reflect the current set of authorisations of the client system).
The PCA Server either grants or rejects the client system request based on the status and scope obtained from the introspect endpoint.

Role based authorisation model

Underpinning both user-based and system-based authorisation is the PCA 'role based authorisation' model. This model is outlined in the following UML class diagram.

As shown above, Authorisation specifies a roleType that the associated Subject (either a PCAUser or a ClientSystem) can perform on a set of FHIR resources that are 'contained by' the scopingObject.

The roleType attribute of an Authorisation is a coded value from the security role code system. Currently, client applications are only permitted by the PCA service operator to use system-based authorisation, so the security role code system is currently limited to system-based role types.

The various roleTypes used by system-based authorisation, and their use in Authorisations, are described in the following table:

RoleType code	Description	Type of associated scopingObject	Required Authorisation to manage the assignment of a target Authorisation with this roleType
RoleType code	Description	Type of associated scopingObject	RoleType of required Authorisation	scopingObject of required Authorisation
PS_Read	The PS_Read roleType models a set of permissions that are assigned to systems acting on behalf of publishers, which require read-only access to either: a specific healthcare service (identified by the HealthcareService scopingObject), or a location and all the healthcare services provided at that location (identified by the associated Location scopingObject), or all the locations and healthcare services provided by an organisation (identified by the Organisation scopingObject), including healthcare services provided by any of its subordinate organisations. The target set of objects to which access is granted is determined by the scopingObject.	PCA Healthcare Service PCA Location PCA Organization	OrganisationManager	The HealthcareService scopingObject must be a healthcare service provided by an organisation they manage The Location scopingObject must be associated with an organisation they manage The Organisation scopingObject must be an organisation they manage
PS_Read		PCA Healthcare Service PCA Location PCA Organization	HealthcareServiceManager	The HealthcareService scopingObject must be a healthcare service they manage (i.e. a healthcare service their HealthcareServiceManager role is scoped to, or a healthcare service provided by an organisation their HealthcareServiceManager role is scoped to or a subordinate organisation) The Location scopingObject must be a location they manage (i.e. a location their HealthcareServiceManager role is scoped to, or a location provided by an organisation their HealthcareServiceManager role is scoped to or a subordinate organisation) The Organisation scopingObject must be an organisation they manage
PS_ServicesMgr	The PS_ServicesMgr 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 scopingObject), or; all the locations and healthcare services provided by an organisation (identified by the Organisation scopingObject), including healthcare services provided by any of its subordinate organisations, or; 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 scopingObject.	PCA Healthcare Service PCA Location PCA Organization	OrganisationManager	The HealthcareService scopingObject must be a healthcare service provided by an organisation they manage The Organisation scopingObject must be an organisation they manage The Location scopingObject must be associated with an organisation they manage
PS_ServicesMgr		PCA Healthcare Service PCA Location PCA Organization	HealthcareServiceManager	The HealthcareService scopingObject must be a healthcare service they manage (i.e. a healthcare service their HealthcareServiceManager role is scoped to, or a healthcare service provided by an organisation their HealthcareServiceManager role is scoped to, or a subordinate organisation) The Location scopingObject must be a location they manage (i.e. a location their HealthcareServiceManager role is scoped to, or a location provided by an organisation their HealthcareServiceManager role is scoped to or a subordinate organisation) The Organisation scopingObject must be an organisation they manage
PS_IdentifierUpdater	The PS_IdentifierUpdater roleType models a set of permissions that are assigned to systems, acting on behalf of publishers, that add and/or update subscriber-specific identifiers for either: a specific healthcare service (identified by the HealthcareService scopingObject), or; all the locations and healthcare services provided by an organisation (identified by the Organisation scopingObject), including healthcare services provided by any of its subordinate organisations, or; 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 scopingObject.	PCA Healthcare Service PCA Location PCA Organization	OrganisationManager	The HealthcareService scopingObject must be a healthcare service provided by an organisation they manage The Organisation scopingObject must be an organisation they manage The Location scopingObject must be associated with an organisation they manage
PS_IdentifierUpdater		PCA Healthcare Service PCA Location PCA Organization	HealthcareServiceManager	The HealthcareService scopingObject must be a healthcare service they manage (i.e. a healthcare service their HealthcareServiceManager role is scoped to, or a healthcare service provided by an organisation their HealthcareServiceManager role is scoped to, or a subordinate organisation) The Location scopingObject must be a location they manage (i.e. a location their HealthcareServiceManager role is scoped to, or a location provided by an organisation their HealthcareServiceManager role is scoped to or a subordinate organisation) The Organisation scopingObject must be an organisation they manage
PS_PractitionerMgr	The PS_PractitionerMgr 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 scopingObject, or; all the healthcare services provided at a location (identified by the associated Location scopingObject), or; all the healthcare services provided by an organisation (identified by the Organisation scopingObject), including healthcare services provided by any of its subordinate organisations. The target set of objects to which access is granted is determined by the scopingObject.	PCA Healthcare Service PCA Location PCA Organization	OrganisationManager	The HealthcareService scopingObject must be a healthcare service provided by an organisation they manage The Location scopingObject must be associated with an organisation they manage The Organisation scopingObject must be an organisation they manage
PS_PractitionerMgr		PCA Healthcare Service PCA Location PCA Organization	HealthcareServiceManager	The HealthcareService scopingObject must be a healthcare service they manage The Location scopingObject must be a location they manage (i.e. a location their HealthcareServiceManager role is scoped to, or a location provided by an organisation their HealthcareServiceManager role is scoped to or a subordinate organisation) The Organisation scopingObject must be an organisation they manage
PS_PublicationMgr	The PS_PublicationMgr 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.	PCA Healthcare Service PCA Location PCA Organization	OrganisationManager	The HealthcareService scopingObject must be a service offering provided by an organisation they manage The Location scopingObject must be associated with an organisation they manage The Organisation scopingObject must be an organisation they manage value)
PS_PublicationMgr		PCA Healthcare Service PCA Location PCA Organization	HealthcareServiceManager	The HealthcareService scopingObject must be a service offering they manage The Location scopingObject must be a location they manage (i.e. a location their HealthcareServiceManager role is scoped to, or a location provided by an organisation their HealthcareServiceManager role is scoped to or a subordinate organisation) The Organisation scopingObject must be an organisation they manage
SS_Updater	The SS_Updater 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 the subscribing organisation’s partner service/s	PCA Organization	OrganisationManager	The Organisation scopingObject must be the subscriber’s ParticipatingOrganisation
SS_Receiver	The SS_Receiver 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	PCA Organization	OrganizationManager	The Organisation scopingObject must be the subscriber’s ParticipatingOrganisation

In addition to roleType, Authorisations have the following attributes which are all set by the PCA service:

lastUpdated: The time when the Authorisation was last updated.
id: A unique identifier assigned by the PCA service.
approvalStatus: Either "approved" or "revoked".

Information requirements

This section contains conformance requirements for exchanging security related information objects over the PCA API.

PCA API access token

The PCA API access tokens are opaque “handles” (as defined in section 3.1 of RFC 6819).

A PCA API access token is represented as a string of at least 128 bits that is constructed from a cryptographically strong random or pseudo-random number sequence that conforms to the current practices described in RFC 4086.

PCA API access token scope

In accordance with Section 3.3 of RFC 6749, each PCA issued OAuth 2.0 access token has a scope that is represented as a JSON string containing a space-separated list of elements.

If the Authorisation has a scopingObject then it is represented as follows:

    <scopingObject type> / <resource_id>:<roleType>

Where

scopingObject type is either “organisation”, “location”, “healthcareService”, or “partnerService”
resource_id is the FHIR resource id of the scopingObject
roleType is a coded value from the security role code system.

If the Authorisation does not have a scopingObject then it is represented as follows:

     pca:<roleType>

Client system credential

Client systems authenticate themselves to the OAuth2 endpoints implemented by the PCA Identity and Access Manager by presenting signed JSON Web Tokens (JWTs).

A client system SHALL authenticate itself by presenting a signed JWT that conforms to section 2.2 of RFC 7523.

A client system SHALL include the following Authentication JWT Header Values:

alg: The algorithm used for signing the authentication JWT SHALL be RS256.
kid: The value SHALL be the identifier of the key-pair used to sign this JWT. Note that the client’s JWK Set was provided to the PCA Identity and Access Manager when the client system was registered.
typ: The value SHALL be JWT.

A client system SHALL include the following Authentication JWT Claims:

iss: The value SHALL be the client system’s client_id.
sub: The value SHALL be the client system’s client_id.
aud: The value SHALL the URL of the endpoint (token or introspect) which is authenticating the client system.
exp: The value SHALL be no more than five minutes after the time when the JWT was signed.
jti: The value SHALL be a nonce string value that uniquely identifies the authentication JWT.

A client system SHALL sign its client credential JWTs with an RSA private key which they generate prior to registration (see register endpoint).

OAuth2 implementation

This section specifies the OAuth2 endpoints that are implemented by the PCA Identity and Access Manager for system-based authorisation.

Token endpoint

The token endpoint conforms to section 3.2 of RFC 6749.

The token endpoint currently only supports the client credentials grant type (as client systems are currently only permitted by the PCA service operator to use system-based authorisation) in accordance with RFC 6749 section 4.4.

Request - client credentials grant type

A client system using the client credentials grant type to request a PCA API access token SHALL conform with section 4.4.2. of RFC 6749, in particular it SHALL request an access token via a HTTP POST using content-type application/x-www-form-urlencoded and a body containing the following parameters:

grant_type: The value SHALL be client_credentials.
client_id: The value SHALL be the client_id of the client system.
client_assertion_type: The value SHALL be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion: The value SHALL be a signed client system authentication JWT (see client system credentials).

Response

On receipt of a valid token request, the PCA Identity and Access Manager will validate the client credentials in accordance with section 3 of RFC 7523.

The PCA Identity and Access Manager will either issue a PCA API access token or return an error in accordance with section 5 of RFC 6749.

Management of tokens

Token management - client systems

A client system SHALL only send PCA API access tokens over an encrypted link to an authenticated PCA service endpoint (i.e. over TLS).

A client system that receives PCA API access tokens as a result of a client credential grant SHALL only store these tokens in transient memory.

Note:
PCA API tokens used for system-based authorisation are short lived (default is 5 minutes). Rather than managing token expiry, a client system may simply request a new token for each set of PCA API invocations that it makes without significant intervening delay (such as would be caused by user interaction).

Token management - server systems

The PCA Identity and Access Manager will invalidate a PCA API access token that was granted via the client credentials code grant, and reject requests that present that access token, when a configurable period of time (default will be 5 minutes) has elapsed since that access token was granted.

Introspect endpoint

The introspect endpoint is invoked by a PCA server whenever a PCA API access token is presented to it. The response reflects the current state of the access token and the current Authorisations of the user (in the case of user-based authorisation) or of the client system (in the case of system-based authorisation).

The introspect endpoint conforms to RFC 7662.

Request

A client system SHALL request token introspection in accordance with section 2.1. of RFC 7662, in particular it SHALL do so using a HTTP POST using content-type application/x-www-form-urlencoded and a body containing the following parameters:

token: The value SHALL be the PCA API access token to be introspected.
client_assertion_type: The value SHALL be urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion: The value shall be a signed client system authentication JWT (see client system credentials).

Response

On receipt of a valid request, the PCA Identity and Access Manager will validate the client credentials in accordance with section 3 of RFC 7523.

The PCA Identity and Access Manager will reject a request to introspect a token if the token was not granted to the client system making the request.

The PCA Identity and Access Manager will either respond with a JSON object or return an error in accordance with section 2.2 or 2.3 of RFC 7662.

If there is no error then the PCA Identity and Access Manager will return a JSON object that contains the following elements:

active: Whether or not the presented token is currently active.
scope: An OAuth2 scope that conforms to PCA scope specification.
client_id: The client_id of the client system.
exp: The present day & timestamp.
iat: The present.

Register endpoint

The register endpoint conforms to RFC 7591.

The PCA Identity and Access Manager implements the "protected dynamic registration" model, as described in RFC 7591 appendix A.1. That is, the PCA service operator issues initial access tokens that are required to be presented by client systems in order to be registered.

The PCA service operator will generate an initial access token that is unique to each software product that has been approved by the PCA service operator for connection to the production environment of the PCA service, where each software product is identified by its unique combination of values for software_id, software_version, scope and redirect_uris.

The PCA service operator will provide a initial access token to the manufacturer of each approved software product via a secure communications channel.

The manufacturer of each software product SHALL ensure that the initial access token is secured within their software product and is only exposed via the secure network link between a client-system (i.e. an operating instance of that software product) and the PCA register endpoint.

A client system SHALL, prior to registration, generate a 2048-bit RSA key pair as defined in RFC 8017.

A client system SHALL securely store the generated RSA private key.

Request

A client system SHALL dynamically register itself using the register endpoint of the PCA Identity and Access Manager prior to accessing the PCA API.

A client system SHALL present its initial access token as a bearer token using the Authorization http request-header field.

A client system SHALL request registration in accordance with section 3.1. of RFC 7591, in particular it SHALL do so using a HTTP POST using content-type application/json and a body containing a JSON object that comprises the following client metadata elements:

software_id: The value SHALL identify the software manufacturer and product name of the software product that implements the client system. This product SHALL have been previously approved for connection to the PCA service.
software_version: The value SHALL identify the software version number of the software product that implements the client system.
scope: The value SHALL identify the roleTypes that the client system is configured to use, this SHALL be a sub-set of the roleTypes that the software product that implements the client system has been approved for.
redirect_uris: If the client system supports user-based authorisation then exactly one URL SHALL be provided.

The JSON object SHALL also contain either a jwks_uri or a jwks element where:

jwks: The value contains the public key used to validate the client system's client credentials, if present it SHALL represent the public key as a bare key, i.e. by including its modulus and exponent (n and e values), the key identifier (i.e. kid) SHALL also be included.
jwks_uri: The value contains the URL string referencing the client's JSON Web Key (JWK) Set document, if present it SHALL provide a link to the client's public key used to validate the client system's client credentials.

Response

On receipt of a registration request, the PCA Identity and Access Manager will validate the initial access token provided in the request header. An initial access token is invalid if either of the following are true:

software_id, software_version, scope or redirect_uris, as specified in the registration request, do not match the corresponding values that were associated with the initial access token when it was issued.
The PCA service operator has determined that the initial access token is no longer valid.

The PCA Identity and Access Manager will reject a registration request if the initial access token is invalid.

The PCA Identity and Access Manager will process a registration request in accordance with section 3.2 RFC 7591.

The PCA Identity and Access Manager will reject a registration request if the public key (either contained in, or referenced by, the client metadata) has been previously associated with any successfully executed client system registration request. (This requirement prevents a client system from being de-registered and then re-registered without also generating a new key pair.)

On successful registration the PCA Identity and Access Manager will respond in accordance with 3.2.1 RFC 7591 and the response will include the following:

client_id: The client_id created by the PCA Identity and Access Manager.
registration_client_uri: The URL, provided by the PCA Identity and Access Manager, that is available to manage the client registration in accordance with RFC 7592.
registration_access_token: The bearer token, created by the PCA Identity and Access Manager, that is required to manage the client registration.
software_id: A value that identifies the software manufacturer and product name of a software product that has been approved for connection to the PCA service.
software_version: A value that identifies the software version number of a software product that has been approved for connection to the PCA service.
scope: The roleTypes that the client system is configured to use, this will be a sub-set of the roleTypes that the software has been approved for.
redirect_uris: This value will not be provided, as client applications are currently only permitted by the PCA service operator to use system-based authorisation.
either jwks or jwks_uri will be provided and the value will be the corresponding meta-data element which was provided by the client system in the registration request.

Client configuration endpoint

The PCA Identity and Access Manager provides a unique client configuration endpoint to each registered client system.

The URLs of these endpoints are of the form:

<registration endpoint URL>/<client_id>.

Each client configuration endpoint conforms to RFC 7592.

While RFC 7592 allows for other types of request message, the client configuration endpoints provided by the PCA Identity and Access Manager are only used to enable client systems to deregister themselves and therefore only Client Delete requests are supported. It is recommended that a client system send a client delete request as a step in the process by which it is un-installed or decommissioned.

Deregister client request

A client system SHOULD de-register itself before it is de-installed or decommissioned by an organisation.

A client system SHALL de-register itself by sending a Client Delete request to the client configuration endpoint of the PCA Identity and Access Manager that was identified in the registration_client_uri field of the client metadata that was returned by the PCA Identity and Access Manager when the client system was registered, in doing so it SHALL comply with section 2.3 of RFC 7592.

A client system SHALL authenticate itself to the client configuration endpoint by providing the registration_access_token as a bearer token in the HTTP Authorization header. The registration_access_token was provided in the register endpoint response.

Deregister client response

On receipt of a client delete request, the PCA Identity and Access Manager will validate the bearer token in Authorization in the request header.

The PCA Identity and Access Manager will process a client delete request in accordance with section 2.3 RFC 7592.