This page describes the transaction of the retrieval of the oAuth tokens

Scope

Open

This transaction supports the request of an authentication token by the Requesting System to the Resource Server.

Use Case Roles

Actor: Authorization Client

Role: Client requesting an access token to authorize RESTful transactions.

Actor: Authorization Server

Role: Server that grants access tokens

Referenced Standards

• OAuth 2.1: The OAuth 2.1 Authorization Framework, published as draft-ietf-oauth-v2-1-01, 1 February 2021.

• JWT Access Token: JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens, published as draft-ietf-oauth-access-token-jwt-10, September 2020.

• RFC7519: JSON Web Token (JWT), May 2015.

• RFC7522: Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants, May 2015.

• RFC7515: JSON Web Signature (JWS), May 2015.

• RFC7518: JSON Web Algorithms (JWA), May 2015.

• RFC4648: The Base16, Base32, and Base64 Data Encodings, October 2006

Messages

Request message

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:

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.

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.

Open

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.