Passa al contenuto principale

5. Emissione di un token di accesso (Issuing an Access Token)

Se la richiesta di token di accesso è valida e autorizzata, il server di autorizzazione (Authorization Server) emette un token di accesso (Access Token) e un token di aggiornamento (Refresh Token) facoltativo come descritto nella sezione 5.1. Se la richiesta ha fallito l'autenticazione del client o non è valida, il server di autorizzazione restituisce una risposta di errore come descritto nella sezione 5.2.

5.1. Risposta riuscita (Successful Response)​

Il server di autorizzazione emette un token di accesso (Access Token) e un token di aggiornamento (Refresh Token) facoltativo, e costruisce la risposta aggiungendo i seguenti parametri al corpo dell'entità della risposta HTTP con un codice di stato 200 (OK).

access_token
Richiesto (REQUIRED). Il token di accesso emesso dal server di autorizzazione.

token_type
Richiesto (REQUIRED). Il tipo del token emesso come descritto nella sezione 7.1. Il valore è case-insensitive.

expires_in
Raccomandato (RECOMMENDED). La durata in secondi del token di accesso. Ad esempio, il valore « 3600 » indica che il token di accesso scadrà un'ora dopo la generazione della risposta. Se omesso, il server di autorizzazione dovrebbe (SHOULD) fornire il tempo di scadenza tramite altri mezzi o documentare il valore predefinito.

refresh_token
Facoltativo (OPTIONAL). Il token di aggiornamento (Refresh Token), che può essere utilizzato per ottenere nuovi token di accesso utilizzando la stessa autorizzazione (Authorization Grant) come descritto nella sezione 6.

scope
Facoltativo (OPTIONAL), se identico all'ambito richiesto dal client; altrimenti, richiesto (REQUIRED). L'ambito del token di accesso come descritto nella sezione 3.3.

I parametri sono inclusi nel corpo dell'entità della risposta HTTP utilizzando il tipo di media application/json come definito da [RFC4627]. I parametri sono serializzati in una struttura JavaScript Object Notation (JSON) aggiungendo ciascun parametro al livello di struttura più alto. I nomi dei parametri e i valori stringa sono inclusi come stringhe JSON. I valori numerici sono inclusi come numeri JSON. L'ordine dei parametri non è importante e può variare.

Il server di autorizzazione deve (MUST) includere il campo di intestazione di risposta HTTP « Cache-Control » [RFC2616] con un valore di « no-store » in qualsiasi risposta contenente token, credenziali o altre informazioni sensibili, così come il campo di intestazione di risposta « Pragma » [RFC2616] con un valore di « no-cache ».

Ad esempio:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

Il client deve (MUST) ignorare i nomi di valore non riconosciuti nella risposta. Le dimensioni dei token e altri valori ricevuti dal server di autorizzazione non sono definite. Il client dovrebbe (SHOULD) evitare di fare supposizioni sulle dimensioni dei valori. Il server di autorizzazione dovrebbe (SHOULD) documentare la dimensione di qualsiasi valore che emette.

5.2. Risposta di errore (Error Response)​

Il server di autorizzazione risponde con un codice di stato HTTP 400 (Bad Request) (salvo diversa indicazione) e include i seguenti parametri con la risposta.

error
Richiesto (REQUIRED). Un singolo codice di errore ASCII [USASCII]. Uno dei seguenti:

  • invalid_request - La richiesta manca di un parametro richiesto, include un valore di parametro non supportato (diverso dal tipo di autorizzazione), ripete un parametro, include più credenziali, utilizza più di un meccanismo per autenticare il client o è altrimenti malformata.

  • invalid_client - L'autenticazione del client è fallita (ad esempio, client sconosciuto, nessuna autenticazione del client inclusa o metodo di autenticazione non supportato). Il server di autorizzazione può (MAY) restituire un codice di stato HTTP 401 (Unauthorized) per indicare gli schemi di autenticazione HTTP supportati dal client. Se il client ha tentato di autenticarsi tramite lo schema di autenticazione HTTP Basic, il server di autorizzazione non deve (MUST NOT) restituire un codice di stato HTTP 401 (Unauthorized).

  • invalid_grant - L'autorizzazione (Authorization Grant) fornita (ad esempio, codice di autorizzazione (Authorization Code), credenziali del proprietario della risorsa (Resource Owner Credentials)) o il token di aggiornamento (Refresh Token) non è valido, scaduto, revocato, non corrisponde all'URI di reindirizzamento utilizzato nella richiesta di autorizzazione o è stato emesso per un altro client.

  • unauthorized_client - Il client autenticato non è autorizzato a utilizzare questo tipo di autorizzazione (Authorization Grant Type).

  • unsupported_grant_type - Il tipo di autorizzazione non è supportato dal server di autorizzazione.

  • invalid_scope - L'ambito richiesto non è valido, sconosciuto, malformato o supera l'ambito concesso dal proprietario della risorsa.

I valori dei parametri non devono (MUST NOT) includere caratteri al di fuori del set %x20-21 / %x23-5B / %x5D-7E.

error_description
Facoltativo (OPTIONAL). Testo ASCII [USASCII] leggibile dall'uomo che fornisce informazioni aggiuntive. Utilizzato per aiutare lo sviluppatore del client a comprendere l'errore. I valori dei parametri non devono (MUST NOT) includere caratteri al di fuori del set %x20-21 / %x23-5B / %x5D-7E.

error_uri
Facoltativo (OPTIONAL). Un URI che identifica una pagina Web leggibile dall'uomo con informazioni sull'errore. Utilizzato per fornire allo sviluppatore del client informazioni aggiuntive sull'errore. I valori dei parametri devono (MUST) essere conformi alla sintassi del riferimento URI definita in [RFC3986] sezione 2 e non devono (MUST NOT) includere caratteri al di fuori del set %x21 / %x23-5B / %x5D-7E.

I parametri sono inclusi nel corpo dell'entità della risposta HTTP utilizzando il tipo di media application/json come definito da [RFC4627]. I parametri sono serializzati in una struttura JavaScript Object Notation (JSON) aggiungendo ciascun parametro al livello di struttura più alto. I nomi dei parametri e i valori stringa sono inclusi come stringhe JSON. I valori numerici sono inclusi come numeri JSON. L'ordine dei parametri non è importante e può variare.

Ad esempio:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"invalid_request"
}
Ultimo aggiornamento il