# Pushed an Authorization Request

# Description

This operation pushes an OAuth 2.0 authorization request or an OpenID Connect authentication request directly to the TRIDENT (i.e., without going through the user agent). It obtains as the response a URI (`request_uri`) that the user agent must later provide to the TRIDENT to reference the request and grant consent (see [RFC 9126]). To do this, after receiving from the TRIDENT the response to the authorization request, the application must perform the Obtain Authorization operation via the user agent and include in the parameters of the request for this operation the above-mentioned URI.

Note

The only parameters that must be specified in the subsequent request for the Obtain Authorization operation are the application identifier (`client_id`), the URI obtained (`request_uri`) and the type of response to be obtained (`response_type=code`).

# Request

`POST /trustedx-authserver/oauth/par`

## Alternative Endpoints

The request can also be made via the `/trustedx-authserver/oauth/{as}/par` endpoint. However, this must only be done if the TRIDENT's administrator associated the application with several authorization servers that recognize, for all authorization code grant flows, all the values included in the scope field of the authorization request (this is an advanced scenario). In all other cases, the browser must go to the `/trustedx-authserver/oauth/par` endpoint.

## Parameters

Name | Type | Usage | Description
`as` | path | Optional. Should only be used if the application has associated two or more Authorization Server entities that support the scope requested for Authorization Code Grant flows. | Identifier of the TRIDENT authorization server to which the authorization request is sent (Server ID field of one of the Authorization server entities). If this parameter is not specified, the TRIDENT automatically selects the authorization server, choosing the one associated with the application that supports Authorization Code Grant for the requested scope (for all the values included). If no authorization server or several meet this condition, the TRIDENT rejects the authorization request and returns an error.

## Content-Type Header

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

## Body

El cuerpo de la petición contiene los siguientes parámetros:

Name | Usage | Description
`response_type` | Required | Must take the `code` value, which indicates that an authorization code is requested.
`client_id` | Required | Identifier of the OAuth 2.0 application registered in TRIDENT (Client identifier field of one of the Client application entities). The application must be associated with the authorization server and have the use of the Authorization Code Grant enabled.
`code_challenge` | Recommended as it protects against theft of the authorization code that the application will receive in the response to the Obtain Authorization operation | Value calculated from the `code_verifier` parameter that must be included in the subsequent request for the Obtain a Token operation (see [RFC 7636]).
`code_challenge_method` | Conditionally required | Method used to calculate the value of the `code_challenge` parameter from the value that will be put in the `code_verifier` parameter of the subsequent request for the Obtain a Token operation. This parameter is required if the `code_challenge` parameter is used. The only value supported is `"S256"`, which means that the `code_challenge` value is obtained by calculating the `base64(url_encode(utf8(code_verifier)))`, where `code_verifier` is a high-entropy random string between 42 and 128 characters (see [RFC 7636]).
`state` | Recommended | We recommend using this parameter to safeguard against CSRF attacks. For this, the application must include a random value in this parameter, store it in the user's HTTP session, and verify it when the Authorization Response message is received from the agent. The random value associates the authorization request with the HTTP session. This safeguards against the application processing an authorization response message not returned in response to an authorization request message specified previously in the user's browser. The application can also include additional information in this parameter, such as the URL to which the browser will be redirected when the OAuth flow finishes. (To include multiple data in the value of this parameter, the application must serialize as seen fit.)
`nonce` | Recommended in OpenID Connect requests | We recommend using this parameter in OpenID Connect authentication requests to safeguard against replay attacks on obtaining the ID token. For this, the application must include a random value in this parameter (taken from a space with sufficient entropy so that an attacker cannot guess it), store it in the HTTP session, and, later on, when it obtains the ID token, check that it matches the `nonce` claim of the ID token. This random value associates the authentication request with the ID token issued, safeguarding against an attacker using an ID token previously captured from another user and resending it to the application.
`redirect_uri` | Conditionally required | Redirection URI to the application. The application waits for the authorization/authentication response message with the authorization code at this URI. It must be one of the Redirect URIs registered for the client application or a redirect URI of the system. This parameter can be omitted if only one redirect URI was registered for the application. In this case, the registered redirect URI is used.
`scope` | Optional | List of values, separated by spaces, that represent the scope of the authorization the application wants to obtain. Ask the TRIDENT administrator for the scopes necessary for accessing the resources and servers. To request an OpenID Connect authentication, the application must include the `openid` value in this parameter. If this parameter is not specified, the scopes defined for the authorization server enabled for Authorization Code Grant flows are assumed by default.
`prompt` | Optional | The values supported are `login` and `none`: The `login` value disables SSO. The `none` value specifies that there can be no interaction with the user (not for authentication or requesting authorization). See [RSE_AUTH_INTEG] for more information.
`acr_values` | Optional | Defines conditions for authenticating the user (minimum levels and/or specific flows) who must authorize the access. See [RSE_AUTH_INTEG]
`view_type` | Optional | This is a nonstandard parameter for requesting a particular display format for the user interfaces displayed to authenticate the user and obtain their consent. See [RSE_AUTH_INTEG].
`ui_locales` | Optional | Specifies a list of languages ordered by preference. TRIDENT uses this list to select the language for displaying the graphical interfaces for authenticating users and obtaining their consent. The value of this parameter is a list of language labels, as per RFC 5646, separated by spaces. The interface is displayed internationalized according to the first label in the list whose base language is supported by the TRIDENT or has been customized. For how to customize a language, including country, dialect, identity provider, and/or `view_type` value variants, see [RSE_AUTH_INTEG]. This parameter is optional. If this parameter is not included (or it is, but it specifies an unsupported language), the language specified by the browser is used. US English is used (en-US) if this language is not supported.
`register_group_labels` | Optional | This parameter must only be used to obtain authorization from the user for creating server signing identities enabled via passwords stored on the HSM. See the Authorization section of the create a signing identity and its associated keys on the server and operations.
`sign_identity_id` | Optional. It can't be present when the `authorization_details` parameter is used. | The number of signatures whose generation the user must authorize. This parameter can only be present if the `sign_identity_id` parameter is also present (otherwise, the TRIDENT will ignore the `num_signatures` parameter). If the user grants the authorization, with the access token obtained later, only `num_signatures signatures` can be generated in a single access. The value entered must be equal to or less than the value configured by the TRIDENT administrator in the Signature Provider. Check with your administrator if you need to know this value.
`num_signatures` | Optional. It can't be present when the `authorization_details` parameter is used. | The number of signatures whose generation the user must authorize. This parameter can only be present if the `sign_identity_id` parameter is also present (otherwise, the TRIDENT will ignore the `num_signatures` parameter). If the user grants authorization, the access token obtained later can only be used to generate `num_signatures signatures` at most, and it can only be used once. The value entered must be equal to or less than the value configured by the TRIDENT administrator in the Signature Provider. Check with your administrator if you need to know this value.
`digests_summary` | Optional. It can't be present when the `authorization_details` parameter is used. | This parameter must only be used to obtain user authorization for generating a digital signature (or a batch of digital signatures) with a server signing identity activated with a password stored on the HSM. Its value must be the base64 encoded cryptographic hash of the concatenation of the data and cryptographic hashes to be used to create the digital signatures. This concatenation must be done in the same order and with the same data and cryptographic hashes as those specified subsequently in the request for generating the signature (see Create a Digital Signature on the Server and Create a Digital Signature Batch on the Server).
`digests_summary_algorithm` | Optional. It can't be present when the `authorization_details` parameter is used. | This parameter must only be used to obtain user authorization for generating a digital signature (or a batch of digital signatures) with a server signing identity activated with a password stored on the HSM. Its value ("`sha256`", "`sha384`" or "`sha512`") must be the algorithm for obtaining the cryptographic hash specified in the `digests_summary` parameter.
`authorization_details[]` | Optional No puede estar presente cuando se utilizan los parámetros `sign_identity_id`,`num_signatures`,`digests_summary` y `digests_summary_algorithm`. Debe contener un solo elemento. | Detailed information regarding the requested authorization (see[RFC 9396]). Currently, details provided can only refer to generating one or more signatures with a given signature key.
`authorization_details[0].type` | Conditionally required. It must be present when the `authorization_details` property is included. | The value is always `"digest_signing"`.
`authorization_details[0].sign_identity` | Conditionally required. It must be present when the `authorization_details` property is included. | Identifier of the signing identity to generate one or more signatures for which authorization is requested. It is mandatory that this signing identity's activation is with an HSM password or through the SAM
`authorization_details[0].num_signatures` | Conditionally required. It must be present when the `authorization_details` property is included. | Number of signatures to generate using the signing identity indicated by the `sign_identity_id` property.
`authorization_details[0].digests[]` | Conditionally required. It must be present when the `authorization_details` property is included. | Hashes of the data to sign. It must have one element at least.
`authorization_details[0].digests[].value` | Conditionally required. It must be present when the `authorization_details` property is included. | The hash of one piece of data to sign.
`authorization_details[0].digests[].algorithm` | Optional (It can only be present when the `authorization_details[0].digests[].value` parameter is also present. | The algorithm used to generate the hash of one piece of data to sign: "`sha256`", "`sha384`" o "`sha512"`.
`login_hint` | Optional | Suggested user identifier that can be used if the user must be authenticated.
`id_token_hint` | Optional | ID Token provided by TRIDENT when it authenticated (using OpenID Connect) the user whose authorization is now wanted. If the TRIDENT has to authenticate the user again (e.g., because the user's session expired), the user identifier obtained as a result of this authentication must match the one that appears in the `sub` claim of the ID Token provided in this parameter.

## Authentication of the Client Application

The application pushing the authorization request must authenticate using the HTTP basic authentication scheme. As credentials, the application must specify the identifier and secret assigned during its registration in the TRIDENT (the Client identifier and Client secret fields of the Client application), encoded as specified by OAuth 2.0.

Specifically, 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` first in UTF-8 and then according to the URL character escape rules.

- Encode `client_secret` first in UTF-8 and then according to 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 defined for the application/x-www-form-urlencoded MIME format in the HTML specification that 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 in 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, keep this in mind, especially when the identifier or secret contains extended symbols or characters.

## Example: Authorization Request

This example illustrates the `demoapp` application pushing an OAuth 2.0 authorization request. The application pushes an authorization request with the `urn:safelayer:eidas:sign:identity:use:server` scope (use of the user's server signing identities). It specifies that it expects the authorization code at the h`ttps://www.demoapp.com/oauth/back``` redirection URI.

`POST /trustedx-authserver/oauth/par HTTP/1.1`
`Content-Type: application/x-www-form-urlencoded`
`Accept: application/json`
`Authorization: Basic ZGVtb2FwcDpvbSUyQjRhXy5DRS1xJUMzJUJDS0MrbUslM0EzJTI2Vg==`
`Host: trustedx.demo.com:8082`
`response_type=code&`
`client_id=demoapp&`
`scope=urn%3Asafelayer%3Aeidas%3Asign%3Aidentity%3Ause%3Aserver&`
`state=IxtdZtOguYVF&`
`redirect_uri=https%3A%2F%2Fwww.demoapp.com%2Foauth%2Fback`

## Example: OpenID Connect Authentication Request

This example illustrates the `demoapp` application directly pushing an OpenID Connect authentication request. The application pushes an authorization request with a scope that includes the `profile`, `email`, and `openid` values (this last value specifies that it is an OpenID Connect request). The application also includes the `prompt=login` parameter to specify that user reauthentication must be forced if the user is already logged in.

`POST /trustedx-authserver/oauth/par HTTP/1.1`
`Content-Type: application/x-www-form-urlencoded`
`Accept: application/json`
`Authorization: Basic ZGVtb2FwcDpvbSUyQjRhXy5DRS1xJUMzJUJDS0MrbUslM0EzJTI2Vg==`
`Host: trustedx.demo.com:8082`
`response_type=code&`
`client_id=demoapp&`
`scope=openid%20profile%20email&`
`state=IxtdZtOguYVF&`
`nonce=XRoZW50aWNhd&`
`redirect_uri=https%3A%2F%2Fwww.demoapp.com%2Foauth%2Fback`

# Response

## Status-Line

If the TRIDENT accepts the authentication request, the HTTP response will contain the following `Status-Line` (see Status of the HTTP Responses for all possible cases).

`HTTP/1.1 201 Created`

## Content-Type Header

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

## Body

JSON object containing the URI of the authentication request sent and its lifetime.

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

## Parameters

Parameter | Description
`request_uri` | URI that the TRIDENT assigned to the authorization request sent.
`expires_in` | 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.