Netherlands - Generic Functions for data exchange Implementation Guide, published by Stichting Nuts. This guide is not an authorized publication; it is the continuous build for version 0.2.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/nuts-foundation/nl-generic-functions-ig/ and changes regularly. See the Directory of published versions

Request Access Token [GFI-004]

Scope

The transaction Request Access Token is used by a client to obtain an access token from an authorization server. The client offers credentials from an holder to the authorization server which then verifies the credentials and answers with an access token that can be used to access a protected resource.

In order to proof possession of the credentials, the holder uses its private key to sign a challenge provided by the verifier in the form of a nonce.

This interaction is scoped on the interaction between two computers with not necessarily a human in the loop. Therefore the interaction is a back-channel interaction without a user-agent such as a web browser. For this reason the OAuth 2.0 Extension RFC 7523 is used to offer the credentials in the form of a JWT assertion directly to the token endpoint without the use of a authorization request.

Actor Roles

Referenced standards

• OAuth 2.0 Authorization Framework
• RFC 7523: JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants
• Verifiable Credentials Data Model 1.1
• OAuth 2.0 Demonstration of Proof-of-Possession (DPoP)

Messages

1. Nonce Request
2. Nonce Response
3. Access Token Request
4. Access Token Response

Nonce Request

Trigger events

• A client needs to obtain an access token from an authorization server and needs a nonce to include in the access token request.

Message semantics

The client initiates a nonce request using a HTTP POST request to the authorization server's nonce endpoint. No further parameters are required.

Example

Below is a non-normative example of a Nonce Request:

POST /nonce HTTP/1.1
Host: example.com
Content-Length: 0

Nonce Response

Trigger events

• The authorization server responds to the nonce request with a nonce that the client can use in the access token request.

Message semantics

The authorization server responds with a HTTP 200 OK response containing the nonce in the body of the response. The nonce is a random value that is used to prevent replay attacks.

The nonce must be an opaque and non predictable value. Authorization server should implement a mechanism to ensure the nonce is only used once and has a limited lifetime.

Due to the temporal nature of the nonce, the response should include a Cache-Control: no-store header to prevent caching of the nonce.

Example

Below is a non-normative example of a Nonce Response:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
  "nonce": "n-0S6_WzA2Mj"
}

Expected Actions

• The client extracts the nonce from the response and includes it in the access token request.
• The authorization server stores the nonce and ensures it is only used once and has a limited lifetime.

Access Token Request

Trigger events

• A client needs to obtain an access token from an authorization server and has obtained a nonce from the authorization server.

Message semantics

The client requests an access token from the authorization server using the OAuth 2.0 JWT bearer token flow as defined in RFC 7523.

If an authorization server is shared between multiple (care) organizations (e.t. a multi-tenant setup), the authentication server must have a path parameter or a different endpoint to identify the organization the client is requesting the access token for. The client should not have to know the internal identifier of the organization. The access token must be bound to the requested organization.

If the client wants to bind the access token to a private key, it can include a DPoP header in the request as defined in OAuth 2.0 Demonstration of Proof-of-Possession (DPoP).

Verifiable Credentials and Verifiable Presentations must be encoded as JWTs as defined in Section 6.3.1 of the Verifiable Credentials Data Model 1.1.

Request parameters

The request must include the following information:

• grant_type: Must be set to urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion: A JWT assertion in the form of a verifiable presentation containing the verifiable credentials offered by the holder. The JWT must be signed by the holder and the proof must contain the nonce obtained from the authorization server.
• client_assertion: A JWT signed by the client to authenticate itself to the authorization server. The JWT is in the form of a Verifiable Presentation containing a verifiable credentials which contain the identifier of the client and its certifications/affiliations which authorizes the client to request the scopes it is requesting. Just like the assertion the client_assertion must also contain the nonce obtained from the authorization server to proof the ownership of the credentials.
• scope: (Optional) A space-separated list of scopes that the client is requesting.

Assertions

The assertion and the client_assertion must include the following properties:

• iss: The issuer of the JWT. For the assertion this is the identifier of the holder. For the client_assertion this is the identifier of the client.
• aud: The audience of the JWT. This must be the identifier of the authorization server.
• jti: A unique identifier for the JWT.
• nbf: (Optional) The time before which the JWT must not be accepted for processing.
• iat: The time at which the JWT was issued.
• exp: The expiration time on or after which the JWT must not be accepted for processing.
• nonce: The nonce obtained from the authorization server.
• vp: The verifiable presentation containing the verifiable credentials. The vp claim must conform to the Verifiable Credentials Data Model 1.0 specification.

The request must be sent as a HTTP POST request to the authorization server's token endpoint with the Content-Type header set to application/x-www-form-urlencoded.

Example

Below is a non-normative example of an Access Token Request:

POST /oauth/{tenant-id}/token HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&
assertion=eyJhbGciOiJFUzI1NiIsInR5c&
client-assertion-type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
client_assertion=eyJhbGciOiJFUzI1NiIsInR5c&
scope=use-case1 use-case2

Below is a non-normative example of a JWT assertion in the form of a verifiable presentation:

{
  "iss": "did:example:ebfeb1f712ebc6f1c276e12ec21",
  "jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
  "aud": "did:example:4a57546973436f6f6c4a4a57573",
  "nbf": 1541493724,
  "iat": 1541493724,
  "exp": 1573029723,
  "nonce": "n-0S6_WzA2Mj",
  "vp": {
    "@context": [
      "https://www.w3.org/2018/credentials/v1",
      "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "type": ["VerifiablePresentation"],
    "verifiableCredential": ["... verifiable credential ..."]
  }
}

Access Token Response

Trigger events

• The authorization server responds to the access token request with an access token that the client can use to access a protected resource.

Message semantics

The verifier responds with a HTTP 200 OK response containing the access token in the body of the response.

The access token is opaque to the client and the format is determined by the authorization server.

If the client provided a DPoP header in the access token request, the authorization server must issue a DPoP-bound access token.

The response must include the following information:

• access_token: The access token issued by the authorization server.
• token_type: The type of the token issued. Must be set to Bearer or DPoP.
• expires_in: (Optional) The lifetime in seconds of the access token.
• scope: (Optional) The scope of the access token.

Example

Below is a non-normative example of an Access Token Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "access_token": "SlAV32hkKG",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "use-case1 use-case2"
}

Expected Actions

• The client extracts the access token from the response and uses it to access the protected resource.