# Obtain an OAuth 2.0 authorization

# Alias

`CscOauth2Authorize`

# Description

Makes an OAuth 2.0 authorization request.

The signature application sends this request to the TRIDENT via the browser, either through an HTTP redirect, an invisible form with automatic POST, or any other similar method, and can leverage the authorization request data it previously pushed to the authorization server.

Provided the user (the signer) grants the authorization, an authorization code will be provided, and the signature application must exchange it to obtain an access token.

TRIDENT only accepts authorization requests with the `service` or `credential` scope. An error is returned if any other scope is specified. An error is also returned if authorization is requested with the `service credential` scope, i.e., simultaneously with the two scope values.

# Request

The request is made via the user's browser, which generates a GET or POST request like the following:

`GET /trustedx-resources/csc/v2/oauth2/authorize`
`POST /trustedx-resources/csc/v2/oauth2/authorize`
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

This header is only present if the request is made via POST since the request parameters are put in the body in this case.

`Content-Type: application/x-www-form-urlencoded`

## Request Parameters

Request parameters vary depending on whether the request refers to (leverages) a previously pushed authorization request:

### Request parameters when referring to a previously pushed authorization request

Name | Type | Usage | Description
`client_id` | String | Required | Identifier of the client assigned by TRIDENT to the signature application.
`request_uri` | String | Required | URI that points to a pushed authorization request previously uploaded by the signature application.

### Request parameters when not referring to a previously pushed authorization request

These parameters are only allowed when using long-term certificates. For short-term certificates the use of a previously pushed authorization request is mandatory.

Name | Type | Usage | Description
`response_type` | String | Required | Its value must always be `code`.
`client_id` | String | Required | Identifier of the client assigned by TRIDENT to the signature application.
`redirect_uri` | String | Conditionally required | URL where the TRIDENT must redirect the browser to provide the signature application with the authorization code corresponding to the authorization the user grants. This must be one of the redirect URIs configured in the TRIDENT for the signature application. This parameter can be omitted if only one redirect URI was registered for the application since this URI is considered the default redirect URI for the signature application in this particular case.
`scope` | String | Optional | Scope of the authorization requested by the application (see section 3.3 of RFC 6749). Only the `service` (which is the default) or the `credential` scopes can be requested.
`code_challenge` | String | Optional | The value that results from transforming a `code_verifier` value using the method indicated by the `code_challenge_method` parameter. The `code_verifier` value, in turn, must be a random secret value (namely, a high-entropy value with a minimum length of 43 characters and a maximum length of 128 characters) that must be included in the later token request so that the required access token is indeed exchanged for the authorization code grant that is eventually obtained in this operation. See RFC 7636 for more details.
`code_challenge_method` | String | Optional | Method used to calculate the `code_challange` parameter's value from the value that is to be put in the `code_verifier` parameter of the subsequent request to the Obtain an OAuth 2.0 access token operation. The only value supported is `"S256"`. This means that the `code_challenge` value is obtained by calculating `base64url_encode(SHA-256(ASCII(code_verifier))))`, where `code_verifier` is a high-entropy random string between 43 and 128 characters (see [RFC 7636]).
`state` | String | Optional | Up to 255 random data bytes that the TRIDENT has to return in the response. This value can be used as a transaction identifier or any other application aim. Although this parameter is optional, we recommend its use to protect against cross-site request forgery attacks.
`lang` | String | Optional | Language in which the signature application prefers that the TRIDENT provides the browser the pages for getting authorization from the user. The language is specified as per RFC 5646. This parameter is optional. If this parameter is not included (or it is, but it specifies an unsupported language), the language set by the browser will be used. However, US English (en-US) will be used if the TRIDENT does not support this language.
`credentialID` | String | Conditionally required | Identifier of the credential bound to the signing key for which the signature application wants authorization. It must be used only if the scope of the OAuth 2.0 authorization request is `credential,` when the application requests authorization for generating one or more signatures, it is required.
`numSignatures` | Number | Conditionally required | Number of signatures for which the signature application asks authorization. This parameter can only be used if the scope of the authorization requested is `credential` and the `hashes` parameter is present`.` If this is the case, including this parameter is mandatory to be granted authorization. The value of this parameter must be equal to or less than the value of the `multisign` parameter for the signature credential (`credentialID`) for which the authorization is being requested (see Obtain a Signature Credential of a User for information on the `multisign` parameter).
`hashes` | String | Conditionally required | List (separated by commas) of the hashes of the data to be signed and for which the signature application requests signature generation authorization. Each hash must be encoded in base64. The number of elements in the list must be equal to the value of the `numSignatures` parameter. This parameter can only be used if the scope of the authorization requested is `credential`, a nd when the `numSignatures` `` parameter is present .
`hashAlgorithmOID` | String | Conditionally required | Identifier (OID) of the algorithm with which the hashes were generated based on which the signatures will be generated. It must be used only if the `hashes` parameter is present (it is mandatory in that case).

## Authorization

No access token is required.

# Response

Once the user has been authenticated (or SSO applied), and the user has granted their authorization, the signature application receives an HTTP GET request like the one shown below from the user's browser. This HTTP request is an OAuth 2.0 authorization response message. The signature application receives this request at the redirect URL specified in the `redirect_uri` parameter of the request (see Request Parameters) or if this parameter was not used, at the redirect URL that the signature application has registered in the TRIDENT

`GET {redirection_uri_path}?code={code}&state={state} HTTP/1.1`
`Host: {redirection_uri_host}`

Where `{redirection_uri_host}{redirection_uri_path}` is the above-mentioned redirect URI.

## Response parameters

Name | Type | Description
`code` | String (in `application/x-www-form-urlencoded` format) | Authorization code granted to the signature application for obtaining the access token. This authorization code has the length (in bytes) and expiry (in seconds) specified in the settings of the TRIDENT authorization server that processed the authorization request. The signature application must invoke the Obtain an OAuth 2.0 access token operation and include the authorization code obtained in the request before this code expires. Each authorization code can only be used in one invocation to the Obtain an OAuth 2.0 access token operation
`state` | String (in `application/x-www-form-urlencoded` format) | This parameter is only received if the signature application included it in the request. It contains the same value as that put in the request (see Request Parameters)

# Error Management

If an error occurs during the authorization phase, TRIDENT does not return an authorization response to the signature application. Instead it returns an error. In certain cases, the error is displayed directly in the user's browser.

## Errors without Redirection to the Client Application

If the authorization request is invalid for any of the following reasons, TRIDENT does not redirect the browser to the client application:

- The client identifier (`client_id`) does not correspond to any registered client application.

- The request includes a redirect URL not allowed in the `redirect_uri` field

In these cases, TRIDENT displays a generic error message in the user's browser advising the user to contact the administrator. For reasons of security, no redirection to the application is performed. To diagnose this problem, the TRIDENT administrator must browse the log. In some cases, no event may be registered in the log (in this situation, the message displayed in the browser includes an error code that can be used to diagnose the problem

## Errors with Redirection to the Client Application

If the authorization request fails for another reason, for example, because the user canceled the authentication process, TRIDENT redirects the browser to the specified redirect URI and adds in the following parameters, which are described in the standard. In this case, it is the signature application's responsibility to inform the user that an error has occurred (except where the authentication is canceled).

- `error`: Error code. See the standard and the list below for more details.

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

- `state`: The same value that the application included in the request (Request Parameters)

Error case | error | error_description
The server could not process the request owing to an unexpected error. | `server_error` |
The server could not process the request owing to an excessive workload or because it was under maintenance. | `temporarily_unavailable` |
The server does not support the response type (`response type`) specified in the authorization request. | `unsupported_response_type` |
The authorization request lacks a required parameter. | `invalid_request` |
The user canceled the authentication process or did not grant the requested authorization. | `access_denied` |
The authorization request is for generating one or more signatures, but it does not contain the hash parameter `hash.` | `access_denied` | `MissingDigestsSummaryException`
The scope specified in the request is invalid, unknown, or in an incorrect format | `invalid_scope` |

# Examples

## Service Authorization

### Request

The signature application sends the following request via the browser (e.g., via a browser redirect).

`GET /trustedx-resources/csc/v2/oauth2/authorize?response_type=code&`
`client_id=signatureapp&`
`scope=service&`
`state=IxtdZtOguYVF&`
`redirect_uri=https%3A%2F%2Fsignatureapp.corporation.com%2Foauth%2Fback HTTP/1.1`
`Host: rse.corporation.com:8082`

### Response

After authenticating the user and obtaining their authorization, TRIDENT responds by redirecting the browser so that it sends the following HTTP request to the signature application:

`GET /oauth/back?code=4515...e0ba&state=IxtdZtOguYVF HTTP/1.1`
`Host: signatureapp.corporation.com`

## Credential Authorization

### Request

The signature application sends the following request via the browser (e.g., via a browser redirect).

`GET /trustedx-resources/csc/v2/oauth2/authorize?response_type=code&`
`client_id=signatureapp&`
`scope=credential&`
`state=IxtdZtOguYVF&`
`credentialID=GX0112348&`
`numSignatures=1&`
`hashes=TMkLHG9F5EE1X3YxkimehiuRDV9RcepZnKZ1dUAlHiQ%3D&`
`hashAlgorithmOID=2.16.840.1.101.3.4.2.3&`
`redirect_uri=https%3A%2F%2Fsignatureapp.corporation.com%2Foauth%2Fback HTTP/1.1`
`Host: rse.corporation.com`

### Response

After authenticating the user and obtaining their authorization, TRIDENT responds by redirecting the browser so that it sends the following HTTP request to the signature application:

`GET /oauth/back?code=4515...e0ba&state=IxtdZtOguYVF HTTP/1.1`
`Host: signatureapp.corporation.com`