This method results in an access token with which the requesting party can gain access to a service at the providing party. The format of an access token is not defined by this specification. They are left to the server and should be opaque to a requesting party.

DSGO.Basis: Parties MUST support a POST call to a /token endpoint to create a new access token

Pre-registration of clients

In OAuth 2.0 clients are typically “pre-registered” by the server. DSGO offers the option to create and provide a new access token based on authentication through OAuth2.0 ClientPassword, where pre-registration is mandatory.

In general, this is not desirable in the DSGO because data transactions should be possible with previously unknown clients. Therefore, DSGO offers a preferred solution based on OAuth2.0 Client Credentials (private key jwt). Here, client identification and authentication is performed via a check in the DSGO participant registry.

DSGO.Basis: When using authentication with private key JWTs, parties MUST NOT pre-register clients

DSGO.Basis: When using authentication with ClientPassword, parties MUST pre-register clients

Request Headers (private key JWT)

DSGO.Basis: When using authentication with private key JWTs, parties MUST validate that a POST request to a /token endpoint contains the HTTP headers as described in the table below

Header		Description

Header		Description
`Content-Type`	Required	as the OAuth 2.0 JWT bearer profile, specified in RFC7523. Defines request body content type. MUST be equal to `application/x-www-form-urlencoded`

Parameters

For information about the parameters that are common to trust framework’s API’s see Generic API Requirements.

DSGO.Basis: Parties MUST validate that a POST request to a /token endpoint contains the parameters as described in the table below

DSGO.Basis: When using authentication with private key JWTs, Parties MUST validate the client credentials in the client_assertion received in a POST to a /token endpoint, by comparing the client_id to the iss and sub claim in the client_assertion and the subject_name of the Electronic Seal used to sign the client_assertion

Parameters		Description

Parameters		Description
`grant_type`	Required	as the OAuth 2.0 grant type. MUST be equal to `client_credentials`.
`scope`	Required	as the OAuth 2.0 scope. MUST contain the value `iSHARE` to indicate usage within the iSHARE framework.
`client_id`	Required	as the OAuth 2.0 JWT bearer profile, specified in RFC7523. MUST contain a valid Organisation ID of the data service consumer. Used in DSGO for client identification.
`client_assertion_type`	Required	as the OAuth 2.0 JWT bearer profile, specified in RFC7523. MUST be equal to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
`client_assertion`	Required	as the OAuth 2.0 JWT bearer profile, specified in RFC7523. MUST contain a signed JWT (Authentication JWT or Onweerlegbaarheid JWT). Used in DSGO for authentication of the client.

{ 
    "grant_type"="client_credentials"&
    "scope"="iSHARE"& 
    "client_id"="did:ishare:EU.NL.NTRNL-98765432"& 
    "client_assertion_type"="urn:ietf:params:oauth:client-assertion-type:jwt-bearer"&
    "client_assertion"="eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.eyJpc3Mi[...omitted for brevity...].cC4hiUPo[...omitted for brevity...]"
}

Response

For information about the parameters that are common to trust framework’s API’s see Generic API Requirements.

200 OK

When a valid request is sent an OK result should be returned and an access token is sent.

Headers

DSGO.Basis: Parties MUST include the HTTP headers as described in the table below in a response to a POST request to a /token endpoint

Header		Description

Header		Description
`Content-Type`	Required	Defines response body content type. MUST be equal to `application/json`.

Parameters

DSGO.Basis: When using authentication with private key JWTs, Parties MUST include an access token as described in the table below in the HTTP payload in a response to a successful POST request to a /token endpoint

DSGO.Basis: Parties MUST NOT issue refresh tokens

Parameters		Description

Parameters		Description
`access_token`	Required	as the OAuth 2.0 access token, specified in RFC6749. This MUST contain an access token which will be used to access endpoints that require authorization.
`token_type`	Required	as the OAuth 2.0 JWT bearer profile, specified in RFC7523. MUST be equal to `bearer`.
`expires_in`	Required	Access token expiration time in seconds. SHOULD be `3600`.

An example M2M Authorization response (200 OK) is presented below

{
    "access_token":"aW2ys9NGE8RjHPZ4mytQivkWJO5HGQCYJ7VyMNGGDLIOw",
    "token_type":"bearer",
    "expires_in":3600
}

400 Bad Request

When invalid request is sent a bad request result should be returned.

DSGO.Basis: Parties MUST include the parameters as described in the table below in the HTTP payload in a response to a failed POST request to a /token endpoint

Parameters		Description

Parameters		Description
`error`	Required	as specified in OAuth 2.0 section 5.2, MUST be an error code.
`error_description`	Optional	as specified in OAuth 2.0 section 5.2, MUST be a human-readable text providing additional information.
`error_uri`	Optional	as specified in OAuth 2.0 section 5.2, MUST be an URI identifying a human-readable web page with information about the error.

{
    "error":"invalid_request"
}

POST /token

Pre-registration of clients

Request Headers (private key JWT)

Parameters

Response

200 OK

Headers

Parameters

400 Bad Request