Netherlands - Generic Functions for data exchange Implementation Guide
0.3.0 - ci-build
Netherlands
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.3.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
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 the Verifiable Presentation.
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 | Role |
|---|---|
| Holder (Client) | Requests an access token from the authorization server by offering verifiable credentials |
| Verifier (Authorization Server) | Verifies the offered credentials and issues an access token |
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.g. 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.
The request must include the following information:
grant_type: Must be set to urn:ietf:params:oauth:grant-type:jwt-bearerassertion: A JWT assertion in the form of a verifiable presentation containing the verifiable credentials offered by the holder, typically the care organization and/or authenticated user. The JWT must be signed by the holder.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.scope: (Optional) A space-separated list of scopes that the client is requesting.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.vp: The verifiable presentation containing the verifiable credentials. The vp claim must conform to the Verifiable Credentials Data Model 1.1 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.
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:web:example.com",
"jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
"aud": "https://auth.example.com/oauth/token",
"nbf": 1541493724,
"iat": 1541493724,
"exp": 1573029723,
"vp": {
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://www.w3.org/2018/credentials/examples/v1"
],
"type": ["VerifiablePresentation"],
"verifiableCredential": ["... verifiable credential ..."]
}
}
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.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"
}