Server authorization

NB: This is a draft specification!

Before a data consumer can collect data at the data provider it has to get access to the FHIR server of the data provider. This resource server must be secured using the OAuth2 protocol. This protocol defines the following actors:

Resource server: the network node of the data provider that is able to serve resources to external network nodes.
Authorization server: the network node of the data provider that manages access to the resource server.
Client: the network node of the data consumer that wants to access resources at the resource server.
Resource owner: the party or user that owns the resources at the resource server. Only the resource owner can allow clients to access to those resources.

The OAuth2 protocol requires the client to obtain a valid access token from an authorization server to request data at the resource server. That access token must then be presented to the resource server when querying the resource server. The full authorization flow follows the steps below:

Client obtains approval from the resource owner to access resources at the resource server.
Client presents proof of the resource owner’s approval (also known as the “authorization grant”) to the authorization server to request an access token.
Authorization server validates the authorization grant and the access token request. If valid, it issues an access token.
Client requests resources from the resource server and presents an access token with the request.
The resource server validates the access token. If valid, it serves the requested resources to the client.

Resource owner authorization grant

To obtain an access token at the authorization server, the resource owner has to authorize the client application to access that data in the resource server. There are different ways by which the resource owner can authorize the client application to access its data. The OAuth2 protocol specifies this in a number of different authorization grants that represent the proof of the resource owner’s approval for the client to access the data at the resource server (also see RFC 6749, section 4). ZorgDomein supports two different authorization grant types:

The Authorization Code Grant is used for front channel authorization using single sign-on to or from ZorgDomein.
The JWT Bearer Grant (RFC 7523) is used for backchannel authorization, i.e. backend requests between FHIR clients and servers where there is no user in the loop.

The remainder of this page focuses on the JWT Bearer Grant. See the specifications SSO to ZorgDomein or SSO from ZorgDomein for more details about the implementation of the Authorization Code Grant using SMART on FHIR.

Access token request specifications

Conform RFC 6749 and RFC 7523, the client must send a HTTP POST request with the following parameters to the authorization server to request an access token:

Headers:
- Content-Type: application/x-www-form-urlencoded
Body:
- grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
- assertion: security token (see security token specifications below).

Processing and responding to the access token request

The authorization server must validate the request before issuing an access token. The following rules must be applied to validate the request:

Check if the right grant type was used.
Validate the authorization grant by validation of the security token.
Check if the client and resource owner have access to the requested scopes.

If the request was valid, the authorization server responds with HTTP 200 response having the following parameters:

Headers:
- Content-Type: application/json;charset=UTF-8
- Cache-Control: no-store
- Pragma: no-cache
Body: JSON object with the following attributes:
- access_token: access token string.
- token_type: bearer (fixed value).
- expires_in: lifetime of the token in seconds. Access tokens provided by ZorgDomein will have a lifetime of 60 seconds.
- patient: id of the FHIR Patient resource at the resource server containing the details of the active patient context in the serving application during SSO.
- task: id of the FHIR Task resource at the resource server containing the details of the active transaction in the serving application during SSO.

If the request was invalid, the authorization server responds with HTTP 400 response having the following parameters:

Headers:
- Content-Type: application/json;charset=UTF-8
Body: JSON object with the following attributes:
- error: A single ASCII error code. Supported codes:
  - invalid_request: The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
  - invalid_grant: The provided grant (JWT assertion) is invalid.
  - unauthorized_client: The authenticated client is not authorized to use this authorization grant type.
  - unsupported_grant_type: For any grant type other than urn:ietf:params:oauth:grant-type:jwt-bearer.
- error_description: OPTIONAL. Human-readable ASCII text providing additional information, used to assist the client developer in understanding the error that occurred. Values for the error_description parameter must not include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
- error_uri: OPTIONAL. A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error. Values for the error_uri parameter must conform to the URI-reference syntax and thus must not include characters outside the set %x21 / %x23-5B / %x5D-7E.

Security token specifications

Conform RFC 7523 a JWT security token is used to represent the authorization grant of the resource owner for back channel authorization. This JWT must conform to the following specifications:

Token header:
- typ: JWT (fixed value)
- alg: one of PS256, PS384, PS512, ES256, ES384 or ES512 (fixed value)
- x5c: contains the X.509 public key certificate or certificate chain corresponding to the key used to digitally sign the token. Does not apply to Nuts-compliant interfaces.
- kid: contains the identifier of a key published in the actor’s DID document. Only applies to Nuts-compliant interfaces.
Token payload:
- iss: Unique identifier of the healthcare organization that requests access. When this JWT is used in an authorization request to access transaction details hosted by ZorgDomein, this identifier identifies the organization that wants to consume transaction data hosted by ZorgDomein. When this JWT is used in an authorization request to submit a notification, this identifier identifies the organization that sends the notification. For Nuts-compliant interfaces this claim must contain the DID of the actor/requester (healthcare organization making the request). For other interfaces this claim must contain the identifier of the healthcare organization that was exchanged during activation of the interface for that healthcare organization. If the authorization request is preceded by a notification, the value of this claim matches the sub claim in the JWT of the notification.
- sub: Unique identifier of the resource owner, i.e., the healthcare organization that owns the data. When this JWT is used in an authorization request to access transaction details hosted by ZorgDomein, this identifier identifies the organization that initiated a transaction in ZorgDomein. When this JWT is used in an authorization request to submit a notification, this identifier identifies the organization that receives the notification. For Nuts-compliant interfaces this claim must contain the DID of the custodian/authorizer. If the authorization request is preceded by a notification, the value of this claim matches the iss claim in the JWT the notification.
- aud: The token endpoint URL of the authorization server OR the DID of the token endpoint as defined in the Nuts registry for Nuts-compliant interfaces.
- practitioner_id: Unique identifier of a practitioner if authorization on practitioner/user level is required. The value of this claim is extracted from the practitioner_id claim in the JWT of the notification. Does not apply to Nuts-compliant interfaces.
- jti: Unique identifier of the token.
- iat: Token creation timestamp.
- exp: Token expiration timestamp. Must not be later than 5 seconds after issuing since this call is only used to get an access token.

The JWT must be signed using the signing algorithm specified in the alg claim of the token header and the key pair corresponding to the certificate in the x5c claim or the key id in kid claim for Nuts-compliant interfaces. The certificate provided in the x5c claim must be a PKIoverheid Private CA G1 certificate.

The security token must be included in the assertion body parameter of the access token request (see specifications of the access token request).

Client authentication

The OAuth2 specification makes a distinction between confidential clients and public clients, where confidential clients are capable of secure client authentication (e.g., client implemented on a secure server with restricted access to the client credentials), and public clients are not (e.g., clients executing on a device used by the resource owner, such as an installed native application or a web browser-based application). The ZorgDomein interface only supports confidential clients, and the ZorgDomein client can be considered confidential itself as well since the application is running on a secure web server. This means that OAuth2 clients are expected to support secure client authentication. The authentication mechanism to be used by OAuth2 clients is a TLS client certificate (mutual TLS). This implies that the client has to present a valid client certificate during the TLS handshake. The client certificate must be a PKIoverheid Private CA G1 certificate.

This authentication mechanism must be used both in access token requests and resource requests. For access token requests and subsequent resource requests, the same client certificate must be used to enable the use of client-bound access tokens.

Access token specifications

OAuth2 does not define the type of access token to implement. The most common access token for REST interfaces is the bearer token as described in RFC6750. A bearer token is “a security token with the property that any party in possession of the token (a “bearer”) can use the token in any way that any other party in possession of it can. Using a bearer token does not require a bearer to prove possession of cryptographic key material (proof-of-possession).” When sending a request to the resource server (i.e. the FHIR server of the data provider), the client (i.e. the data consumer) must include the obtained access token in the “Authorization” HTTP header field using the “Bearer” authentication scheme.

Example (line breaks within values are for display purposes only):

GET /resource HTTP/1.1
Host: fhir.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
	eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.
	TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

Client registration

Before OAuth2 clients of external applications can interact with the ZorgDomein authorization and resource servers, they have to register themselves with ZorgDomein. There are two ways to register:

Nuts-compliant clients do not have to register with ZorgDomein explicitly. These clients are registered in the Nuts registry. ZorgDomein will use the Nuts registry to authenticate and identify these clients.
Other clients do have to register with ZorgDomein explicitly. During registration clients have to provide the value of the common name (CN) attribute of the certificate that will be used as client TLS certificate. This attribute will be used to identify the client.