Authorization endpoint (Authentication)¶
Request¶
Per avviare il processo di autenticazione, il RP reindirizza l'utente all'Authorization Endpoint dell'OP selezionato, inviando una richiesta HTTP contenente il parametro request in formato JWT firmato e contenente l'Authorization Request firmata dal RP.
Per veicolare la richiesta, il RP PUÒ utilizzare i metodi POST e GET. Mediante il metodo POST i parametri DEVONO essere trasmessi utilizzando la Form Serialization. Mediante il metodo GET i parametri DEVONO essere trasmessi utilizzando la Query String Serialization. Per maggiori dettagli vedi OpenID.Core#Serializations.
Avvertimento
Il parametro scope DEVE essere trasmesso sia come parametro nella chiamata HTTP sia all'interno dell'oggetto request e i loro valori DEVONO corrispondere.
I parametri client_id e response_type DOVREBBERO essere trasmessi sia come parametri sulla chiamata HTTP sia all'interno dell'oggetto request.
I parametri client_id e response_type DEVONO essere trasmessi sia come parametri sulla chiamata HTTP sia all'interno dell'oggetto request e i loro valori DEVONO corrispondere, in caso contrario solo i parametri all’interno dell’oggetto request DEVONO essere considerati.
Vedi anche
Di seguito i parametri obbligatori nella richiesta di autenticazione HTTP.
Parametro |
Descrizione |
Supportato da |
|---|---|---|
scope |
Riporta di valori di scope supportati dall'OP e definiti dal parametro scopes_supported nel Metadata OP. DEVE essere presente almeno il valore openid. |
|
code_challenge |
Vedi RFC 7636#section-4.2. |
|
code_challenge_method |
Come definito dal parametro code_challenge_methods_supported nel Metadata OP. |
|
request |
Vedi OpenID.Core#JWTRequests. DEVE essere un JWT firmato. |
|
Di seguito una tabella che riporta la composizione dell'header del JWT.
Jose Header |
Descrizione |
Supportato da |
|---|---|---|
alg |
Vedi RFC 7516#section-4.1.1. Vedi Algoritmi crittografici.. |
|
kid |
Vedi RFC 7638#section_3. |
|
Nota
Il parametro typ se omesso assume il valore implicito di JWT.
Il payload del JWT contiene i seguenti parametri obbligatori.
Claim |
Descrizione |
Supportato da |
|---|---|---|
client_id |
Vedi OpenID.Registration. DEVE essere valorizzato con un HTTPS URL che identifica univocamente il RP. |
|
code_challenge |
Come definito nella Tabella dei parametri HTTP. |
|
code_challenge_method |
Come definito nella Tabella dei parametri HTTP. |
|
nonce |
Vedi OpenID.Core#AuthRequest. DEVE essere una stringa casuale di almeno 32 caratteri alfanumerici. Questo valore sarà restituito nell'ID Token fornito dal Token Endpoint, in modo da consentire al client di verificare che sia uguale a quello inviato nella richiesta di autenticazione. |
|
prompt |
Vedi OpenID.Core#AuthRequest. I valori consentiti sono: consent: Se non è già attiva una sessione di Single Sign-On, l'OP fa una richiesta di autenticazione all'utente. Quindi chiede il consenso al trasferimento degli attributi. consent login: l'OP forza una richiesta di autenticazione all'utente. Quindi chiede il consenso al trasferimento degli attributi. |
|
redirect_uri |
Vedi OpenID.Core#AuthRequest. DEVE essere una URL indicata nel Metadata RP. |
|
response_type |
Vedi OpenID.Core#AuthRequest. Come definito dal parametro response_types_supported nel Metadata OP. |
|
scope |
Come definito nella Tabella dei parametri HTTP. |
|
acr_values |
Vedi OpenID.Core#AuthRequest. Come definito dal parametro acr_values_supported nel Metadata OP. Valori di riferimento della classe di contesto dell'Authentication Request. DEVE essere una stringa separata da uno spazio, che specifica i valori "acr" richiesti in ordine di preferenza. L'OP PUÒ utilizzare un'autenticazione ad un livello più alto di quanto richiesto. Tale scelta non DEVE comportare un esito negativo della richiesta. |
|
claims |
Vedi OpenID.Core#ClaimsRequestParameter. Vedi Sezione "Parametri scope e claims". |
|
state |
Vedi OpenID.Core#AuthRequest. DEVE essere una stringa casuale di almeno 32 caratteri alfanumerici. Identificativo univoco della sessione lato RP. Questo valore verrà restituito al client nella risposta al termine dell'autenticazione. |
|
exp |
UNIX Timestamp con l'istante di scadenza del JWT, codificato come NumericDate come indicato in RFC 7519 |
|
iat |
UNIX Timestamp con l'istante di generazione del JWT, codificato come NumericDate come indicato in RFC 7519 |
|
iss |
DEVE corrispondere al client_id. |
|
aud |
DEVE corrispondere all'identificativo del OP (parametro issuer presente nel Metadata OP.) |
|
ui_locales |
Lingue preferibili per visualizzare le pagine dell’OP. L’OP può ignorare questo parametro se non dispone di nessuna delle lingue indicate. Lista di codici RFC5646 separati da spazi. |
|
Nota
PKCE è un'estensione del protocollo OAuth 2.0 prevista anche nel profilo iGov (International Government Assurance Profile for OAuth 2.0) e finalizzata ad evitare un potenziale attacco attuato con l'intercettazione dell'authorization code. Consiste nella generazione di un codice (code verifier) e del suo hash (code challenge). Il code challenge viene inviato all'OP nella richiesta di autenticazione.
Quando il RP contatta il Token Endpoint al termine del flusso di autenticazione, invia il code verifier originariamente creato, in modo che l'OP possa confrontare che il suo hash corrisponda con quello acquisito nella richiesta di autenticazione.
Di seguito un script Python di esempio per generare i parametri richiesti.
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,
}
Parametri scope e claims¶
Gli attributi dell'utente POSSONO essere richiesti dal RP nell'Authorization Request usando il parametro claims.
Non è possibile richiedere attributi SPID nell' ID Token. Gli attributi dell'utente sono disponibili all'interno della response dello UserInfo endpoint.
Gli attributi dell'utente POSSONO essere richiesti dal RP nell'Authorization Request usando i parametri scope o claims.
Nel caso di utilizzo del parametro scope i seguenti valori sono supportati:
profile: usando questo valore è possibile ottenere il profilo utente di default che corrisponde al Minimum Dataset eIDAS:
family_name,
given_name,
birthdate,
https://attributes.eid.gov.it/fiscal_number (National Unique Identifier).
email: questo valore permette di ottenere, se resi disponibili dall'utente, i seguenti attributi:
email,
email_verified.
Il parametro scope PUÒ contenere uno o più valori separati da uno spazio. Ad esempio l'utilizzo congiunto di profile e email permette di ottenere l'unione degli insiemi degli attributi (Minimum Dataset eIDAS e l'email). Nel caso di richiesta di singoli attributi dell'utente o specifiche combinazioni di essi, Il RP DOVREBBE usare il parametro claims.
Gli attributi richiesti tramite il parametro scope sono disponibili sia nell'ID Token e sia nella risposta allo userinfo endpoint.
Avvertimento
Quando il parametro scope contiene solo il valore openid e il parametro claims non è presente oppure non è valorizzato, la response dello userinfo endpoint NON DEVE contenere nessun attributo utente ma soltanto il claim sub.
Per la definizione del parametro claims e la modalità di utilizzo per la richiesta degli attributi dell'utente si può fare riferimento a OpenID.Core#ClaimsParameter.
Response¶
Un'Authentication response è un messaggio di risposta di autorizzazione OAuth 2.0 restituito dall'authorization endpoint dell'OpenID Provider (OP) al termine del flusso di autenticazione. L'OP reindirizzerà l'utente all'url contenuto nel parametro redirect_uri specificato nella richiesta di autorizzazione, aggiungendo i parametri della risposta.
Vedi anche
Se l'autenticazione è avvenuta con successo, l'OpenID Provider (OP), reindirizza l'utente aggiungendo i seguenti parametri obbligatori come query parameters al redirect_uri (come definito in OpenID.Core#AuthResponse):
Claim |
Descrizione |
Supportato da |
|---|---|---|
code |
Codice univoco di autorizzazione (Authorization Code) che il client può passare al Token Endpoint per ottenere un ID Token e un Access Token. Questo ha il vantaggio di non esporre alcun token allo User Agent o a malware che controllano questo. |
|
state |
Valore state incluso nell'Authentication Request. Il client è tenuto a verificarne la corrispondenza. Deve essere lo stesso valore indicato dal client nella Authorization Request. |
|
iss |
Identificatore univoco dell'OP che ha creato l'Authentication Response. Il RP DEVE validare questo parametro e NON DEVE permettere a più OP di usare lo stesso identificatore. |
|
Esempio di Authorization Response dell'OP:
http://rp-test.it/oidc/rp/callback/?code=a032faf23d986353019ff8eda96cadce2ea1c368f04bf4c5e1759d559dda1c08056c7c4d4e8058cb002a0c8fa9a920272350aa102548523a8aff4ccdb44cb3fa&state=2Ujz3tbBHWQEL4XPFSJ5ANSjkhd7IlfC&iss=http%3A%2F%2Fop-test%2Foidc%2Fop%2F
Gestione degli errori¶
In caso di errore, l'OP o il RP rappresentano i messaggi di anomalia relativi agli scambi OpenID Connect, come descritti nelle relative tabelle definite dalle Linee Guida UX SPID.
Claim |
Descrizione |
Supportato da |
|---|---|---|
Errore |
Vedi Codici di errori |
|
Descrizione dell'errore |
Descrizione più dettagliata dell'errore, finalizzata ad aiutare lo sviluppatore per eventuale debugging. Questo messaggio non è destinato ad essere visualizzato all'utente (a tal fine si faccia riferimento alle Linee Guida UX SPID) |
|
state |
Parametro obbligatorio solo nel caso di risposta di errore alla Authentication Request e DEVE essere uguale al valore state incluso nella Authentication Request. Il RP DEVE verificare che corrisponda a quello inviato nella Authentication Request. |
|
Codici di errore¶
Errore |
Descrizione |
Codice HTTP |
Supportato da |
|---|---|---|---|
access_denied |
L’OP ha negato l’accesso a causa di credenziali non valide o non adeguate al livello SPID richiesto (RFC 6749#section-4.1.2.1). |
302 Found |
|
unauthorized_client |
Il client non è autorizzato a richiedere un authorization code (RFC 6749#section-4.1.2.1). |
302 Found |
|
invalid_request |
La richiesta non è valida a causa della mancanza o della non correttezza di uno o più parametri (RFC 6749#section-4.1.2.1). |
302 Found |
|
invalid_scope |
Sono stati richiesti degli scope non validi (RFC 6749#section-4.1.2.1). |
302 Found |
|
server_error |
L’OP ha riscontrato un problema interno (RFC 6749#section-4.1.2.1). |
302 Found |
|
temporarily_unavailable |
L’OP ha riscontrato un problema interno temporaneo (RFC 6749#section-4.1.2.1). |
302 Found |
|
unsupported_response_type |
Il response_type richiesto non è supportato (RFC 6749#section-4.1.2.1). |
302 Found |
|
login_required |
L'OP richiede l'autenticazione da parte dell'utente (OpenID.Core#AuthError). |
302 Found |
|
consent_required |
L'OP richiede il consenso esplicito da parte dell'utente (OpenID.Core#AuthError). |
302 Found |
|
request_uri_not_supported |
L'OP non supporta l'uso del parametro request_uri (OpenID.Core#AuthError). |
302 Found |
|
registration_not_supported |
L'OP non supporta l'uso del parametro registration (OpenID.Core#AuthError). |
302 Found |
|
invalid_request_object |
Il parametro request contiene un Request Object non valido (OpenID.Core#AuthError). |
302 Found |
|
Avvertimento
In caso di URI di reindirizzamento non valido, non corrispondente o mancante, l'OP restituisce 400 Bad Request come codice HTTP.