10.2.5 | TTA FHIR - Authentication & Authorization

Resource server authorization: OAuth 2.0

On application level both the Notification endpoint of the Receiving System and the FHIR endpoint of Sending System are considered as resource endpoints that must be secured by https://www.rfc-editor.org/rfc/rfc6749. This implies that a client that wants to interact with a resource server (FHIR or Notification endpoint) must obtain an access token from an authorization server before it can interact with that resource server. The client must present this access token as bearer token in the HTTP Authorization header of each request to the resource server as specified in https://www.rfc-editor.org/rfc/rfc6750#section-2.1.

Client authentication

The resource server must be able to authenticate the client as a trusted client. The client is specified as the system that submits the access token request (not to be confused with the organization for which that system is acting). The OAuth specs leave room for different authentication methods for client authentication. The authentication methods that are proposed in the OAuth 2.0 core specifications (https://www.rfc-editor.org/rfc/rfc6749.html#section-2.3) all rely on the exchange of shared secrets. The use of shared secrets is considered as a security risk since they are prone to leakage. The use of an authentication method that relies on digital signatures using asymmetric cryptography offers better security. Therefore, the client must authenticate itself by providing a client assertion by means of a signed JWT as specified in https://www.rfc-editor.org/rfc/rfc7523#section-2.2.

The client assertion is a JWS Compact Serialized JWT that consists of a header, a payload, and a signature. The signature is created using a key pair belonging to the initiating system or to a third party trusted by the initiating system.

The header carries the claims listed below:

The payload contains a set of claims listed below:

Claim	Description	Required
jti	Unique identifier of the client assertion. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7.	Yes
iss	Identifier of the system that issued the client assertion. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 and https://www.rfc-editor.org/rfc/rfc7523.html#section-3.	Yes
iat	The time at which the client assertion was issued. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6. If there is an agreed age of a client assertion.	Conditional
exp	The expiration time on or after which the client assertion shall not be accepted for processing. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 and https://www.rfc-editor.org/rfc/rfc7523.html#section-3.	Yes
nbf	The time before which the token shall not be accepted for processing. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5 and https://www.rfc-editor.org/rfc/rfc7523.html#section-3.	No
aud	Identifier of the authorization server token endpoint where this client assertion is to be used. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 and https://www.rfc-editor.org/rfc/rfc7523.html#section-3. System vendors have to make mutual agreements about the value of this identifier.	Yes
sub	Identifier of the OAuth client that requests access. This claim must match the value of the client_id parameter in the access token request. Note that the client is specified as the system that submits the access token request. System vendors have to make mutual agreements about the value of this identifier.	Yes

The Issuer of the client assertion may include additional claims in the assertion, but the Issuer shall not require the authorization server to process these claims.

The exchange of the public key that was used to sign the client assertion between the Assertion Issuer and the authorization server is beyond the scope of this normative specification. This is the added value of Twiin. Twiin unambiguously describes the agreements that system providers typically need to make with each other.Note that the authorization server can authenticate the client on network level by the client certificate that the client must present during the mTLS handshake (see section Network level security). In theory, this could be used by the authorization server to authenticate the client on application level. However, this may cause problems since it introduces additional and potentially unwanted requirements on TLS termination and related matters. Therefore, a client must always provide a client assertion in the access token request.

Authorization grant

OAuth 2.0 requires the use of an authorization grant to request an access token. As specified in https://www.rfc-editor.org/rfc/rfc6749#section-1.3 “an authorization grant is a credential representing the resource owner's authorization (to access its protected resources) used by the client to obtain an access token.” OAuth 2.0 specifies several different authorization grants. Additionally, there are several RFC’s that specify extension grants, e.g. https://www.rfc-editor.org/rfc/rfc6749#section-4.5. Because this TA applies to situations where a resource client is acting on behalf of a user (health professional) that works for an organization (healthcare provider), the use of the JWT Bearer Assertion authorization grant as specified in https://www.rfc-editor.org/rfc/rfc7523#section-2.1 is the most suitable authorization grant. This means that the resource client must provide an authorization assertion in each access token request to identify the acting user, organization, and authorization base to prove that it is authorized to access the requested data. This authorization assertion acts as the authorization grant that the client can present to prove that it is authorized to access the protected resources.

The authorization assertion is a JWS Compact Serialized JWT that consists of a header, a payload, and a signature. The signature is created using a key pair belonging to the initiating organization or to a third party trusted by the initiating organization.

The header carries the claims listed below:

The payload contains a set of claims that carry information required by NEN7512 and NEN7513.

Claim	Description	Required
jti	Unique identifier of the authorization assertion. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7.	Yes
iss	Identifier of the system that issued the authorization assertion. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1 and https://www.rfc-editor.org/rfc/rfc7523.html#section-3. System vendors have to make mutual agreements about the value of this identifier.	Yes
iat	The time at which the authorization assertion was issued. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6. This is only required if there is an agreed age of an authorization assertion.	Conditional
exp	The expiration time on or after which the authorization assertion shall not be accepted for processing. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4 and https://www.rfc-editor.org/rfc/rfc7523.html#section-3.	Yes
nbf	The time before which the token shall not be accepted for processing. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5 and https://www.rfc-editor.org/rfc/rfc7523.html#section-3.	No
aud	Identifier of the authorization server token endpoint where this authorization assertion is to be used. See https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3 and https://www.rfc-editor.org/rfc/rfc7523.html#section-3.	Yes
sub	Identifier of the organization (healthcare supplier) that requests access. URA nummer 5.1 | Vertrouwen: Identificatie	Yes
user_id	Identifier of the responsible user (healthcare professional) who requests access. Preferred: UZI nummer 5.1 | Vertrouwen: Identificatie User identification (user_id and user_role claims) is only required in the authorization assertion when access to patient data is requested. This implies that these claims are not required in authorization assertions used in access token requests for Notification endpoints.	Conditional
user_role	Code of the role of the responsible user (healthcare professional) who requests access. Preferred: UZI rolcode 5.1 | Vertrouwen: Identificatie User identification (user_id and user_role claims) is only required in the authorization assertion when access to patient data is requested. This implies that these claims are not required in authorization assertions used in access token requests for Notification endpoints.	Conditional
authorizer	Identifier of the healthcare organization that grants access. URA nummer 5.1 | Vertrouwen: Identificatie	Yes
authorization_base	See Authorization base	No
patient	Identifier of the patient for whom data is exchanged. Must be an OID encoded BSN (I.e., BSN with the “urn:oid:2.16.840.1.113883.2.4.6.3.” prefix and without a leading zero) 5.1 | Vertrouwen: Identificatie Patient identification is only required when the Sending System requests access to the Notification endpoint of the Receiving System and the Sending System does not provide a Workflow Task that refers to a Patient resource containing the BSN of the patient. This way, the Receiving System is always able to identify a patient by BSN based on a Notification. The Receiving System must support receiving the BSN through the patient claim.	Conditional

The Issuer of the authorization assertion may include additional claims in the authorization assertion, but the Issuer shall not require the authorization server to process these claims.

The exchange of the public key that was used to sign the authorization assertion between the Assertion Issuer and the authorization server is beyond the scope of this normative specification. Therefore, system vendors have to make mutual agreements about the exchange of these public keys.

Authorization scope

The scope defines the requested access to the FHIR Server as specified in https://www.rfc-editor.org/rfc/rfc6749#section-3.3 . If a scope is provided in the access token request or access token response, it must be expressed in a string of space delimited scopes as defined in http://hl7.org/fhir/smart-app-launch/scopes-and-launch-context.html#scopes-for-requesting-clinical-data . The following additional requirements apply to the scope values:

• When requesting an access token for a Notification endpoint at the Receiving System, the scope value must be one of:

  • system/Task.c?code=http://fhir.nl/fhir/NamingSystem/TaskCode|pull-notification (create)

  • system/Task.u?code=http://fhir.nl/fhir/NamingSystem/TaskCode|pull-notification (update)

• When requesting an access token for a FHIR endpoint at the Sending System, the query parameters in the scopes must match (a subset of) the queries in the FHIR search requests listed in Task.input of the Notification Task (see Notification message).

The client must provide the requested scope in the access token request, except for cases where an authorization base is provided in the access token request as part of the authorization assertion.

The authorization server must provide the granted access scope in the access token response in accordance with https://www.rfc-editor.org/rfc/rfc6749#section-5.1 and the requirements mentioned above. The issued access token must grant access to the granted scope that the authorization server specifies in the access token response. The granted scope must be equal to or less than the scope that can be derived from the authorization base consent token.

Access token request

Based on the paragraphs above each access token request contains the parameters listed below:

Note that the access token request effectively contains two JWT assertions:

1. A client assertion that is used to authenticate the client. This assertion identifies and authenticates the system that is requesting access. 

2. An authorization assertion that is used as an authorization grant. This assertion identifies both the organization and user that are requesting access.

Separating client authentication from client authorization in two separate assertions enables the client to select different Assertion Issuers for the two assertions. The targeted authorization server must register both Issuers as trusted Assertion Issuers for a specific client.

Access token requirements

The access token will be processed only by the party that issued the access token. Therefore, the form and contents of the token are determined by the authorization server (audience), so the access token is opaque to the resource client. The resource client should not take any dependency on the format or contents of an access token. The authorization server MAY issue certificate bound access tokens as specified in https://www.rfc-editor.org/rfc/rfc8705 , but this is not mandatory. To enable the server to issue certificate bound access tokens, the client MUST support mTLS for access token and resource requests as specified in section Network level security: mTLS 1.3.

Authorization base

When the Sending System receives a request from the Receiving System to access certain data, it is the primary responsibility of the Sending System to verify that the Receiving System is authorized to access that data. When publishing data on a resource server to be collected by the Receiving System, many Sending Systems register the authorization to access that data as an authorization base of some kind. To facilitate that authorization process, the Sending System may submit the authorization base (or a reference to it) to the Receiving System as part of the Notification (see section Notification message). If the Receiving System received an authorization base in the Notification, it must include that authorization base in the access token request to the Sending System (see section Authorization grant). This enables the authorization server of the Sending System to determine if the requested access can be granted based on the provided authorization base.

Since an authorization base is to be processed by the Sending System only, the form and contents of an authorization base are determined by the Sending System. The Receiving System should not take any dependency on the format or contents of an authorization base.

User authentication

Healthcare professionals are identified in their EHR system by logging in with their personal account. When a user of the Receiving System wants to request resources at the Sending System, the Sending System must be able to identify the user at the Receiving System as a legitimate healthcare professional who is working for the receiving organization before it can provide the requested data. Therefore, the Receiving System must implement the appropriate means to ensure the authenticity of the user.

The Sending System can identify the healthcare professional at the receiving organization that is requesting patient data by the following claims in the authorization assertion of the access token request (see Authorization grant):

• sub: Identifier of the healthcare organization

• user_id: Identifier of the responsible user (healthcare professional)

• user_role: Code of the role of the responsible user (healthcare professional)

The type of identifiers used for organizations and users is beyond the scope of this TA. The same applies to the use of role codes.

Trust relationships

The picture below shows the different roles involved in the interactions, and clarifies the dependencies between these roles.

The Sending System hereby performs the following roles:

• Notification Client;

• Resource Server Endpoint.

The Receiving System performs the roles:

• Notification Server Endpoint;

• Resource Client.

Sending System and Receiving System both implement the role of Authorization Server.

The role of Assertion Issuer can be performed by a third-party, but can also be performed by the Sending System or by the Receiving System. Assertion Issuers producing client assertions do not necessarily have to produce authorization assertions as well. Different Issuers can be used for these types of assertions. Before issuing an client assertion or an authorization assertion, the Assertion Issuer has to make sure that applicable requirements regarding user authentication and other mutual security agreements between the Sending System and Receiver System have been met.

Trust and required level of user authentication between parties has to be arranged and agreed upon prior to performing the interaction.