Authorization endpoint¶

Request¶

The Authorization request is initiated by the user that selects the OP for the authentication. The RP redirects the user to the Authorization Endpoint of the selected OP, including in the request the parameter request that is a signed JWT containing the Authorization Request.

For conveying the request, the RP MAY use the methods POST and GET. With the method POST the parameters MUST be sent using the Form Serialization. With the method GET the parameters MUST be sent using the Query String Serialization. For more details see OpenID.Core#Serializations.

Warning

The parameter scope MUST be sent both as a parameter in the HTTP request, and inside the request object. The two values MUST be the same.

The parameters client_id and response_type SHOULD be sent both as parameters in the HTTP request, and inside the request object.

The parameters client_id and response_type MUST be sent both as parameters in the HTTP request, and inside the request object and MUST be the same, in case of mismatching the values inside the request object MUST be considered.

See also

Example of Authorization Request

In the following the mandatory parameters in the HTTP authentication request.

Claim	Description	Supported by
scope	It contains values of scope that are supported by the OP and defined by the parameter scopes_supported in the Metadata OP. At least the value openid MUST be present.
code_challenge	See RFC 7636#section-4.2.
code_challenge_method	As defined by the parameter code_challenge_methods_supported in the Metadata OP.
request	See OpenID.Core#JWTRequests. It MUST be a signed JWT.

In the following, a table that reports the composition of the JWT header.

Jose Header	Description	Supported by
alg	See RFC 7516#section-4.1.1. See Cryptographic algorithms.
kid	See RFC 7638#section_3.

Note

The parameter typ, if omitted, assumes the implicit value JWT.

The JWT payload contains the following mandatory claims:

Claim	Description	Supported by
client_id	See OpenID.Registration. It MUST contain an HTTPS URL that uniquely identifies the RP.
code_challenge	As defined in the Table of the HTTP parameters.
code_challenge_method	As defined in the Table of the HTTP parameters.
nonce	See OpenID.Core#AuthRequest. It MUST be a casual string with at least 32 alphanumeric characters. This value will be returned in the ID Token provided by the Token Endpoint, so that the client can test that it is equals as in the authentication request.
prompt	See OpenID.Core#AuthRequest. The allowed values are: consent: If a Single Sign On session is not yet active, the OP makes an Authentication Request to the user. Then it asks permission to transfer the claims. consent login: The OP forces an authentication request to the user. Then it asks permission to transfer the claims.
redirect_uri	See OpenID.Core#AuthRequest. It MUST be an URL included in the Metadata RP.
response_type	See OpenID.Core#AuthRequest. As defined by the parameter response_types_supported in the Metadata OP.
scope	As defined in the Table of the HTTP parameters.
acr_values	See OpenID.Core#AuthRequest. As defined by the parameter acr_values_supported in the Metadata OP. Reference values of the contest class of the Authentication Request. It MUST be a string with the requested "acr" values, each of them separated by a single space, appearing in order of preference. The OP MAY use an authentication at a higher level than requested. Such a choice MUST NOT cause a negative result of the request.
claims	See OpenID.Core#ClaimsRequestParameter. See Section "Parameters scope and claims".
state	See OpenID.Core#AuthRequest. It must be a casual string with at least 32 alphanumeric characters. Unique session identifier at the RP side. This value will be returned to the client in the response, at the end of the authentication.
exp	UNIX Timestamp with the expiry time of the JWT, coded as NumericDate as indicated in RFC 7519
iat	UNIX Timestamp with the generation time of the JWT, coded as NumericDate as indicated in RFC 7519
iss	It MUST correspond to client_id.
aud	It MUST correspond to the OP identifier (parameter issuer, present in the Metadata OP.)
ui_locales	OPTIONAL. End-User's preferred languages and scripts for the user interface. Represented as a space-separated list of BCP47 [RFC5646].

Note

PKCE is an extension of the protocol OAuth 2.0 also provided in the profile iGov (International Government Assurance Profile for OAuth 2.0) and aimed at avoiding possible attacks from intercepting the authorization code. It consists of the generation of a code (code verifier) and its hash (code challenge). The code challenge is sent to the OP in the authentication request.

When the RP contacts the Token Endpoint at the end of the authentication flow, it sends the code verifier created initially, so that the OP can check if its hash is the same as in the authentication request.

An example of a Python script for generating the requested parameters is shown.

import hashlib
import base64
import re
import os
import random
def get_pkce(code_challenge_method: str = "S256", code_challenge_length: int = 64):
    hashers = {"S256": hashlib.sha256}
    code_verifier_length = random.randint(43, 128)
    code_verifier = base64.urlsafe_b64encode(os.urandom(code_verifier_length)).decode("utf-8")
    code_verifier = re.sub("[^a-zA-Z0-9]+", "", code_verifier)

    code_challenge = hashers.get(code_challenge_method)(
        code_verifier.encode("utf-8")
    ).digest()
    code_challenge = base64.urlsafe_b64encode(code_challenge).decode("utf-8")
    code_challenge = code_challenge.replace("=", "")

    return {
        "code_verifier": code_verifier,
        "code_challenge": code_challenge,
        "code_challenge_method": code_challenge_method,
    }

Parameters scope and claims¶

The attributes of the user MAY be requested by the RP using the claims parameter in the Authorization Request.

SPID doesn't allow the user attributes in ID Token, they are only available at the "userinfo" endpoint.

The user attributes MAY be requested by the RP using the scope or claims parameters in the Authorization Request.

When the scope parameter is used, the following values are supported:

profile: requests the user attributes equivalent to the eIDAS Minimum Dataset:
- family_name,
- given_name,
- birthdate,
- https://attributes.eid.gov.it/fiscal_number (National Unique Identifier).
email: requests the following attributes:
- email;
- email_verified.

The parameter scope MAY contain one or more values, with single spaces as separators. For example, using both profile and email in the scope parameter returns the Minimum eIDAS Dataset and the email. In case of requests of single user-attributes or specific combinations of them, the RP SHOULD use the parameter claims.

The attributes requested by the parameter scope are available both in the ID Token and in the userinfo endpoint response.

Warning

If in the scope parameter there was only the openid value and the claims parameter was not present or valued, the response of the userinfo endpoint would not have any user attributes but only the claim sub.

For the definition of the parameter claims and its usage modes for requesting the user attributes, please refer to OpenID.Core#ClaimsParameter.

Response¶

An Authentication response is returned by the authorization endpoint of the OpenID Provider (OP) at the end of the authentication flow. The OP redirects the user to the URL contained in the parameter redirect_uri specified in the authorization request, adding the response parameters.

Error Management¶

In the event of an error, the OP or RP represent the anomaly message as described in the related tables defined by the Linee Guida UX SPID.

Claim	Description	Supported by
error	See Error codes
error_description	Error description.
state	It MUST be equal to the status value included in the Authentication Request. The RP MUST verify that it matches the one sent in the Authentication Request.

Error Codes¶

Error Code	Description	HTTP Code
access_denied	The OP denied access due to invalid or unsuitable credentials for the required SPID level (RFC 6749#section-4.1.2.1).	302 Found
unauthorized_client	The client is not authorized to request an authorization code (RFC 6749#section-4.1.2.1).	302 Found
invalid_request	The request is not valid due to the lack or incorrectness of one or more parameters (RFC 6749#section-4.1.2.1).	302 Found
invalid_scope	Invalid scopes in the Authorization request (RFC 6749#section-4.1.2.1).	302 Found
server_error	The OP encountered an internal problem (RFC 6749#section-4.1.2.1).	302 Found
temporarily_unavailable	The OP encountered a temporary internal problem (RFC 6749#section-4.1.2.1).	302 Found
unsupported_response_type	The OP does not support the requested response_type. (RFC 6749#section-4.1.2.1).	302 Found
login_required	The OP requires End-User authentication (OpenID.Core#AuthError).	302 Found
consent_required	The OP requires End-User consent (OpenID.Core#AuthError).	302 Found
request_uri_not_supported	The OP does not support use of the request_uri parameter (OpenID.Core#AuthError).	302 Found
registration_not_supported	The OP does not support use of the registration parameter (OpenID.Core#AuthError).	302 Found
invalid_request_object	The request parameter contains an invalid Request Object (OpenID.Core#AuthError).	302 Found

Warning

In case of invalid, mismatching, or missing redirection URI, the OP will return 400 Bad Request as the HTTP code.

Docs Italia beta

Public documents, made digital.

Authorization endpoint¶

Request¶

Parameters scope and claims¶

Response¶

Error Management¶

Error Codes¶

Claim	Description	Supported by
code	Unique Authorization Code that the client can pass to the Token Endpoint for obtaining an ID Token and an Access Token. This has the advantage of not exposing any token to the User Agent or to malware that could be controlling it.
state	State value included in the Authentication Request. The client is supposed to check its correspondence. It must have the same value indicated by the client in the Authorization Request.
iss	Unique Identifier of the OP that has created the Authentication Response. The RP MUST validate this parameter and MUST NOT allow more OPs to use the same identifier.