# Push an OAuth 2.0 authorization request

# Alias

`CscOauth2PushedAuthorize`

# Description

Pushes an OAuth 2.0 authorization request as defined in RFC 9126. That is, it pushes the payload of an OAuth 2.0 authorization request to the TRIDENT's authorization server via a direct request and provides the requesting application with a request URI that must be used to reference the pushed data in a subsequent authorization request.

This mechanism protects the contents of the authorization request from modification and eavesdropping, allows for practically arbitrary request sizes, and enables the authorization server to authenticate the signing application in advance of the authorization process.

The application is required to authenticate to the authorization server as it does in Obtain an OAuth 2.0 access token. The authorization server will respond with a request URI, and the application must include it alongside its `client_id` in a shortened authorization request that only contains these two parameters.

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 client application must send the following request to TRIDENT, using TLS.

`POST /trustedx-resources/csc/v2/oauth2/pushed_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 use case is long-term or short-term.

### Request parameters for the long-term use case

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 is requested to redirect the browser to provide the signature application with the authorization code corresponding to the authorization the user grants. If a list of redirect URIs was configured in the TRIDENT for the signature application, this value must be one of them. 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` (it is mandatory in that case).
`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 . I f 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`, and 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).

### Request parameters for the short-term use case

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 is requested to redirect the browser to provide the signature application with the authorization code corresponding to the authorization the user grants. If a list of redirect URIs was configured in the TRIDENT for the signature application, this value must be one of them. 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 `credential` scope can be requested.
`code_challenge` | String | Required | 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 | Required | 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.
`login_hint` | String | Required | Identifier of the user to be authenticated. It must be the user's email.
`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` and if there is no parameter `signatureQualifier` present (it is mandatory in that case).
`signatureQualifier` | String | Conditionally required | Identifier of the signature type, and hence the signing key, for which the signature application wants authorization. `eu_eidas_qes:` Q ualified electronic signatures as per the EU eIDAS regulation . `eu_eidas_aes:` Advanced electronic signatures as per the EU eIDAS regulation . This parameter must only be used if the scope of the OAuth 2.0 authorization request is `credential` and the `credentialID` parameter is not present (it is mandatory in that case).
`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 both the `hashes` and the `credentialID` parameters are 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`, and both the `numSignatures` and the `credentialID` parameters are 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).
`account_token` | String | Required | The whole point of this property is to identify the organization with whom the user who has to grant the authorization is dealing or interacting. It consists of a compactly serialized JWS object (as per RFC 7515) generated by the application with the HMAC function and using the `client_secret`'s SHA256 hash value as a shared secret. I.e., as follows: `base64UrlEncode(JWT_Header).base64UrlEncode(JWT_Payload).base64UrlEncode(JWT_Signature)` Where `JWT_Header` is as follows, as per RFC 7518 and RFC 7519: `{` `"typ": "JWT",` `"alg": "HS256",` `}` `JWT_Payload` is the following JWT object, as per RFC 7519, where `sub` is the organization's identifier and `azp` is the signature application's `client_id`: `{` `"sub": {string},` `"iat": {number},` `"jti": {string}` `"iss": {string},` `"azp": {string}` `}` And `JWT_Signature` is as follows as per RFC 7518 and RFC 7519: `HS256(base64UrlEncode(JWT_Header) + "." + base64UrlEncode(JWT_Payload), SHA256(<client_secret>))`

## 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

## Status-Line

`HTTP/1.1 201 Created`

## Content-Type Header

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

## Body

JSON object containing the URI of the authorization request data sent and their lifetime.

`{`
`"request_uri" : {string},`
`"expires_in" : {number}`
`}`

Property | Type | Description
`request_uri` | String | URI that the TRIDENT assigned to the authorization request sent.
`expires_in` | Number | Lifetime (in seconds) of the URI of the authorization request sent. The application must use this URI before it expires to reference the associated authorization request via the user agent. If the lifetime expires, the URI becomes invalid, and the application must get a new one by sending an authorization request directly to the TRIDENT.

# Error Management

If the request cannot be successfully processed (because the request is invalid, the authentication of the client application fails, etc.), the TRIDENT returns an HTTP response with a 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 request lacks a required parameter. | 400 Bad Request | `invalid_request` |
The scope specified in the request is invalid, unknown, or in an incorrect format | 400 Bad Request | `invalid_scope` |
The server does not support the response type ( `response type` ) specified in the request. | 400 Bad Request | `unsupported_response_type` |
The client could not be correctly authenticated | 401 Unauthorized | `invalid_client` |

# Examples

## Service Authorization

### Request

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

`POST /trustedx-resources/csc/v2/oauth2/pushed_authorize HTTP/1.1`
`Host: rse.corporation.com`
`Authorization: Basic c2lnbmF0dXJlYXBwOjEyMzQ1Njc4`
`Content-Type: application/x-www-form-urlencoded`
`response_type=code&`
`client_id=signatureapp&`
`scope=service&`
`code_challenge=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU&`
`code_challenge_method=S256&`
`state=IxtdZtOguYVF&`
`redirect_uri=https%3A%2F%2Fsignatureapp.corporation.com%2Foauth%2Fback HTTP/1.1`

### Response

TRIDENT responds to the application, providing it with the URI of the authentication request sent and its lifetime :

`HTTP/1.1 201 OK`
`Content-Type: application/json;charset=UTF-8`
`{`
`"request_uri": "urn:ietf:params:oauth:request_uri:f277a0a8-1ef7-4dcd-ae4e-0f2d804f0e24",`
`"expires_in": 60`
`}`

## Credential Authorization

### Request

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

`POST /trustedx-resources/csc/v2/oauth2/pushed_authorize HTTP/1.1`
`Host: rse.corporation.com`
`Authorization: Basic c2lnbmF0dXJlYXBwOjEyMzQ1Njc4`
`Content-Type: application/x-www-form-urlencoded`
`response_type=code&`
`client_id=signatureapp&`
`scope=credential&`
`code_challenge=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU&`
`code_challenge_method=S256&`
`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`

### Response

TRIDENT responds to the application, providing it with the URI of the authentication request sent and its lifetime :

`HTTP/1.1 201 OK`
`Content-Type: application/json;charset=UTF-8`
`{`
`"request_uri": "urn:ietf:params:oauth:request_uri:46cb6e2a-2105-4663-aa6a-d27e335fe22b",`
`"expires_in": 60`
`}`