# Obtain an OAuth 2.0 access token

# Alias

`CscOauth2Token`

# Description

Obtains an OAuth 2.0 access token.

# Request

To obtain the access token attesting to an authorization grant, the client application must send a request like the following to the TRIDENT using TLS. Note that this request is sent directly from the client application to the TRIDENT and does not go through the browser, the same as in Push an OAuth 2.0 authorization request and the opposite to the exchange described in Obtain an OAuth 2.0 Authorization.

`POST /trustedx-resources/csc/v2/oauth2/token`
Important

[CSC_STANDARD_V2] requires that the base path of all requests of the access API to a remote signature services provider be `/csc/v2/`. Thus, if the TRIDENT administrator decides to follow the standard strictly, they must deploy the system so that the base path of the request is `/csc/v2` instead of`/trustedx-resources/csc/v2`. To determine if this is the case in your situation, check the "`oauth2`" property of the JSON object provided by the Obtain information on the CSC signature service operation.

## Content-Type Header

`Content-Type: application/x-www-form-urlencoded; charset=UTF-8`

## Request Parameters

The parameters of the request (in its body) vary according to the type of OAuth 2.0 flow in which the token is requested:

- Parameters in the Case of the Authorization Code Grant Flow

- Parameters in the Case of the Client Credentials Grant Flow

### Parameters in the Case of the Authorization Code Grant Flow

Name | Type | Usage | Description |
`grant_type` | String | Required | Must have the value `authorization_code`. |
`code` | String | Required | Code of the authorization for which a token is requested (i.e., the access token). This code must be the code received in the response of the Obtain an OAuth 2.0 authorization operation previously invoked. |
`code_verifer` | String | Conditionally required | Value from which was derived the `code_challenge` included in the Obtain an OAuth 2.0 authorization's request that obtained the `code` parameter (or in the associated pushed authorization request). This value must be generated randomly with a high entropy as per RFC 7636. It must be used only if the `code_challenge` was included in the Obtain an OAuth 2.0 authorization request ( or in the associated pushed authorization request) being mandatory in that case. |
`client_id` | String | Required | Identifier of the client assigned by TRIDENT to the signature application. |
`redirect_uri` | String | Optional | URI where the authorization response was received with the authorization code put in `code`. It must match the `redirect_uri` parameter of the authorization request (see Obtain an OAuth 2.0 authorization). It must be omitted if it is also omitted in the authorization request. |

### Parameters in the Case of the Client Credentials Grant Flow

Name | Type | Usage | Description
`grant_type` | String | Required | Must have the value `client_credentials`.
`client_id` | String | Required | Identifier of the client assigned by TRIDENT to the signature application.

In Client Credential flows, the scope of the access token requested will always be `service` implicitly.

## Authentication of the Client Application

The application must include an Authorization header with the following structure:

`Authorization: Basic {credentials}`

Where `{credentials}` is the result of encoding the client identifier of the application (`client_id`) and its secret (`client_secret`) as follows:

`base64(url_encode(utf8(client_id)) ':' url_encode(utf8(client_secret)))`

The meaning of the above pseudocode is:

- Encode `client_id` in UTF-8. Next, encode the results obtained by applying the URL character escape rules.

- Encode `client_secret` in UTF-8. Next, encode the results obtained by applying the URL character escape rules.

- Concatenate both using colons ("`:`") as the separator.

- Encode the resulting string in base64 without line breaks.

The rules for escaping characters in URLs are those defined for the `application/x-www-form-urlencoded` MIME format in the HTML specification, and must be applied to the bytes resulting from encoding the identifier or secret in UTF-8. See the example below.

Note

The HTTP basic authentication scheme defined in RFC 2617 does not specify that the credentials must be encoded in UTF-8 and URL format. The use of these additional encoding rules is part of OAuth 2.0. If a software library or tool that generates the Authorization header as per RFC 2617 is used, remember this, especially when the identifier or secret contains extended symbols or characters.

## Authorization

No access token is required.

# Response

As a response, the TRIDENT generates a bearer access token and returns it in a JSON structure. The application must later use this token to invoke the API's required functions.

## Status-Line

`HTTP/1.1 200 OK`

## Content-Type Header

`Content-Type: application/json;charset=UTF-8`

## Body

JSON object containing the access token and the associated information.

`{`
`"access_token" : {string},`
`"token_type" : "Bearer",`
`"expires_in" : {number},`
`"credentialID": {string}`
`}`

Property | Type | Description
`access_token` | String | Access token generated by the TRIDENT. If the scope of the authorization granted is `service`, a "`Bearer`" token is obtained and must be put as the value of the `Authorization: Bearer` header of the HTTP message with which an operation is subsequently invoked If the scope of the authorization granted is `credential`, a "`SAD`" token is obtained and must be put as the value of the `SAD` parameter in the body of the HTTP message later used to invoke the Generate digital signatures from hashes operation
`token_type` | String | Type of access token: "`Bearer`": the token is proof of authorization with the `service` scope and must be put as the value of the `Authorization: Bearer` header of the HTTP message used to invoke an operation. "`SAD`": the token is proof of authorization with the `credential` scope and must be put as the value of the SAD parameter of the request used to invoke the Generate digital signatures from hashes operation
`expires_in` | Number | Lifetime (in seconds) of the access token. The application must perform the access the token authorizes before the token expires.
`credentialID` | String | The identifier of the credential associated with the signing key whose use was authorized in the corresponding authorization request. This response parameter will be present in case the scope "`credential"` is used in the pushed authorization request along with the `"eu_eidas_qes"` signature qualifier (`signatureQualifier`) . This can then be used to obtain the authorized signing key certificate.

# Error Management

If the access token request cannot be successfully processed (because the request is invalid, the authentication of the client application fails, the authorization code is expired, etc.), the TRIDENT returns an HTTP response with the `HTTP 400 (Bad Request)` status code, the `Content-Type: application/json;charset=utf-8 header` and a JSON object in the body with the following properties:

- `error`: Error code.

- `error_description`: Additional description of the error. Not required.

Error case | Status Code (HTTP) | error | error_description
The `client_id` of the application requesting the access token was not provided. | 400 Bad Request | `invalid_request` | `noCredentials`
The `client_secret` of the application requesting the access token was not provided. | 400 Bad Request | `invalid_request` | `invalidCredentials`
The `grant_type` parameter was not provided. | 400 Bad Request | `invalid_request` | `unsupported_grant_type`
The value of the `grant_type` parameter is invalid (i.e., it is neither `authorization_code` nor `client_credentials`) | 400 Bad Request | `invalid_request` | `unsupported_grant_type`
The `code` parameter was not provided | 400 Bad Request | `invalid_request` | `missingAuthzCode`
The `client_id` provided is invalid. | 400 Bad Request | `invalid_request` | `unregisteredClient`
The `client_secret` provided is invalid. | 400 Bad Request | `invalid_request` | `invalidCredentials`
The r`edirect_uri` parameter does not match that specified in the authorization request. | 400 Bad Request | `invalid_request` | `redirectUriMismatch`
The authorization code is invalid (e.g., it has expired). | 400 Bad Request | `invalid_request` | `invalidOrExpiredCode`

# Examples

## Obtaining an Access Token in an Authorization Code Grant Flow

### Request

The signature application (`client_id``= signatureapp, client_secret = 12345678`) sends the following request to the TRIDENT:

`POST /trustedx-resources/csc/v2/oauth2/token HTTP/1.1`
`Host: rse.corporation.com`
`Authorization: Basic c2lnbmF0dXJlYXBwOjEyMzQ1Njc4`
`Content-Type: application/x-www-form-urlencoded`
`grant_type=authorization_code&`
`code=FhkXf9P269L8g&`
`code_verifer=F7RZvUwaOgyGpv3y0ar27EsxLnhBnUAXM4IjCvHcxXo&`
`client_id=signatureapp&`
`redirect_uri=https%3A%2F%2Fsignatureapp.corporation.com%2Foauth%2Fback`

### Response

TRIDENT responds to the application, providing it with an access token that has a lifetime of 1 minute.

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=UTF-8`
`{`
`"access_token": "3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5H3XlFQZ3ndFhkXf9P2",`
`"token_type": "Bearer",`
`"expires_in": 60`
`}`

## Obtaining an Access Token in a Client Credentials Grant Flow

### Request

The signature application `(client_id = signatureapp, client_secret = 12345678)` sends the following request to TRIDENT:

`POST /trustedx-resources/csc/v2/oauth2/token HTTP/1.1`
`Host: rse.corporation.com`
`Authorization: Basic c2lnbmF0dXJlYXBwOjEyMzQ1Njc4`
`Content-Type: application/x-www-form-urlencoded`
`grant_type=client_credentials&`
`client_id=signatureapp`

### Response

TRIDENT responds to the application, providing it with a bearer access token that has a lifetime of 1 hour.

`HTTP/1.1 200 OK`
`Content-Type: application/json;charset=UTF-8`
`{`
`"access_token": "4/CKN69L8gdSYp5_pwH3XlFQZ3ndFhkXf9P2_TiHRG-bA",`
`"token_type": "Bearer",`
`"expires_in": 3600`
`}`