4. Ottenimento dell'autorizzazione (Obtaining Authorization)

Per richiedere un token di accesso (Access Token), il client ottiene l'autorizzazione dal proprietario della risorsa (Resource Owner). L'autorizzazione è espressa sotto forma di un'autorizzazione (Authorization Grant), che il client utilizza per richiedere il token di accesso. OAuth definisce quattro tipi di autorizzazione: codice di autorizzazione (Authorization Code), implicito (Implicit), credenziali password del proprietario della risorsa (Resource Owner Password Credentials) e credenziali del client (Client Credentials). Fornisce anche un meccanismo di estensione per definire tipi di autorizzazione aggiuntivi.

4.1. Autorizzazione tramite codice (Authorization Code Grant)

Il tipo di autorizzazione tramite codice di autorizzazione (Authorization Code Grant Type) viene utilizzato per ottenere sia token di accesso che token di aggiornamento (Refresh Token) ed è ottimizzato per i client confidenziali (Confidential Client). Poiché si tratta di un flusso basato sul reindirizzamento, il client deve (MUST) essere in grado di interagire con l'user agent del proprietario della risorsa (in genere un browser web) e capace di ricevere richieste in entrata (tramite reindirizzamento) dal server di autorizzazione.

     +----------+
     | Resource |
     |   Owner  |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier      +---------------+
     |         -+----(A)-- & Redirection URI ---->|               |
     |  User-   |                                 | Authorization |
     |  Agent  -+----(B)-- User authenticates --->|     Server    |
     |          |                                 |               |
     |         -+----(C)-- Authorization Code ---&lt;|               |
     +-|----|---+                                 +---------------+
       |    |                                         ^      v
      (A)  (C)                                        |      |
       |    |                                         |      |
       ^    v                                         |      |
     +---------+                                      |      |
     |         |>---(D)-- Authorization Code ---------'      |
     |  Client |          & Redirection URI                  |
     |         |                                             |
     |         |&lt;---(E)----- Access Token -------------------'
     +---------+       (w/ Optional Refresh Token)

Figura 3: Flusso del codice di autorizzazione (Authorization Code Flow)

Il flusso illustrato nella figura 3 comprende i seguenti passaggi.

(A) Il client avvia il flusso dirigendo l'user agent del proprietario della risorsa verso l'endpoint di autorizzazione (Authorization Endpoint). Il client include il proprio identificatore client (Client Identifier), l'ambito richiesto (Scope), lo stato locale (Local State) e un URI di reindirizzamento (Redirection URI) a cui il server di autorizzazione reindirizzerà l'user agent una volta concesso o negato l'accesso.

(B) Il server di autorizzazione autentica il proprietario della risorsa (tramite l'user agent) e stabilisce se il proprietario della risorsa concede o nega la richiesta di accesso del client.

(C) Supponendo che il proprietario della risorsa conceda l'accesso, il server di autorizzazione reindirizza l'user agent al client utilizzando l'URI di reindirizzamento fornito in precedenza (nella richiesta o durante la registrazione del client). L'URI di reindirizzamento include il codice di autorizzazione (Authorization Code) e qualsiasi stato locale fornito in precedenza dal client.

(D) Il client richiede un token di accesso dall'endpoint del token (Token Endpoint) del server di autorizzazione includendo il codice di autorizzazione ricevuto nel passaggio precedente. Durante la richiesta, il client si autentica presso il server di autorizzazione. Il client include l'URI di reindirizzamento utilizzato per ottenere il codice di autorizzazione a scopo di verifica.

(E) Il server di autorizzazione autentica il client, convalida il codice di autorizzazione e si assicura che l'URI di reindirizzamento ricevuto corrisponda all'URI utilizzato per reindirizzare il client nel passaggio (C). Se valido, il server di autorizzazione risponde con un token di accesso e opzionalmente un token di aggiornamento.

4.1.1. Richiesta di autorizzazione (Authorization Request)

Il client costruisce l'URI di richiesta aggiungendo i seguenti parametri al componente query dell'URI dell'endpoint di autorizzazione utilizzando il formato application/x-www-form-urlencoded.

response_type
Richiesto (REQUIRED). Il valore deve (MUST) essere impostato su « code ».

client_id
Richiesto (REQUIRED). L'identificatore del client come descritto nella sezione 2.2.

redirect_uri
Facoltativo (OPTIONAL). Come descritto nella sezione 3.1.2.

scope
Facoltativo (OPTIONAL). L'ambito della richiesta di accesso come descritto nella sezione 3.3.

state
Raccomandato (RECOMMENDED). Un valore opaco utilizzato dal client per mantenere lo stato tra la richiesta e il callback. Il server di autorizzazione include questo valore quando reindirizza l'user agent al client. Il parametro dovrebbe (SHOULD) essere utilizzato per prevenire la falsificazione di richieste intersito (Cross-Site Request Forgery) (vedere sezione 10.12).

Il client dirige il proprietario della risorsa all'URI costruito utilizzando una risposta di reindirizzamento HTTP o altri mezzi disponibili tramite l'user agent del proprietario della risorsa.

4.1.2. Risposta di autorizzazione (Authorization Response)

Se il proprietario della risorsa concede la richiesta di accesso, il server di autorizzazione emette un codice di autorizzazione (Authorization Code) e lo consegna al client aggiungendo i seguenti parametri al componente query dell'URI di reindirizzamento utilizzando il formato application/x-www-form-urlencoded.

code
Richiesto (REQUIRED). Il codice di autorizzazione generato dal server di autorizzazione. Il codice di autorizzazione deve (MUST) scadere poco dopo la sua emissione per mitigare il rischio di perdite. Una durata massima raccomandata del codice di autorizzazione è di 10 minuti. Il client non deve (MUST NOT) utilizzare il codice di autorizzazione più di una volta. Se un codice di autorizzazione viene utilizzato più di una volta, il server di autorizzazione deve (MUST) rifiutare la richiesta e dovrebbe (SHOULD), se possibile, revocare tutti i token precedentemente emessi sulla base di tale codice di autorizzazione. Il codice di autorizzazione è legato all'identificatore del client e all'URI di reindirizzamento.

state
Richiesto (REQUIRED) se il parametro « state » era presente nella richiesta di autorizzazione del client. Il valore esatto ricevuto dal client.

4.1.2.1. Risposta di errore (Error Response)

Se la richiesta fallisce (il proprietario della risorsa nega l'accesso o la richiesta fallisce), il server di autorizzazione ne informa il client aggiungendo i seguenti parametri al componente query dell'URI di reindirizzamento utilizzando il formato application/x-www-form-urlencoded.

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 valido, include un parametro più di una volta o è altrimenti malformata.
unauthorized_client - Il client non è autorizzato a richiedere un codice di autorizzazione utilizzando questo metodo.
access_denied - Il proprietario della risorsa o il server di autorizzazione ha negato la richiesta.
unsupported_response_type - Il server di autorizzazione non supporta l'ottenimento di un codice di autorizzazione utilizzando questo metodo.
invalid_scope - L'ambito richiesto è non valido, sconosciuto o malformato.
server_error - Il server di autorizzazione ha incontrato una condizione imprevista che gli ha impedito di soddisfare la richiesta.
temporarily_unavailable - Il server di autorizzazione è attualmente incapace di gestire la richiesta a causa di un sovraccarico temporaneo o di manutenzione del server.

4.1.3. Richiesta di token di accesso (Access Token Request)

Il client effettua una richiesta all'endpoint del token (Token Endpoint) utilizzando i seguenti parametri nel corpo dell'entità della richiesta HTTP utilizzando il formato application/x-www-form-urlencoded.

grant_type
Richiesto (REQUIRED). Il valore deve (MUST) essere impostato su « authorization_code ».

code
Richiesto (REQUIRED). Il codice di autorizzazione ricevuto dal server di autorizzazione.

redirect_uri
Richiesto (REQUIRED) se il parametro « redirect_uri » è stato incluso nella richiesta di autorizzazione della sezione 4.1.1, e i loro valori devono (MUST) essere identici.

client_id
Richiesto (REQUIRED) se il client non è autenticato presso il server di autorizzazione.

4.1.4. Risposta del token di accesso (Access Token Response)

Se la richiesta di autorizzazione è valida e autorizzata, il server di autorizzazione emette un token di accesso (Access Token) e un token di aggiornamento (Refresh Token) facoltativo come descritto nella sezione 5.1. Se la richiesta è fallita o non è valida, il server di autorizzazione restituisce una risposta di errore come descritto nella sezione 5.2.

4.2. Autorizzazione implicita (Implicit Grant)

Il tipo di autorizzazione implicita (Implicit Grant Type) è un flusso di codice di autorizzazione semplificato ottimizzato per i client implementati in un browser utilizzando un linguaggio di script come JavaScript. Nel flusso implicito, invece di emettere un codice di autorizzazione al client, il client riceve direttamente un token di accesso (Access Token) (come risultato dell'autorizzazione del proprietario della risorsa). Il tipo di autorizzazione è implicito perché non vengono emesse credenziali intermedie come un codice di autorizzazione (che verrebbe utilizzato successivamente per ottenere un token di accesso), ed è emesso direttamente al client.

     +----------+
     | Resource |
     |  Owner   |
     |          |
     +----------+
          ^
          |
         (B)
     +----|-----+          Client Identifier     +---------------+
     |         -+----(A)-- & Redirection URI --->|               |
     |  User-   |                                | Authorization |
     |  Agent  -|----(B)-- User authenticates -->|     Server    |
     |          |                                |               |
     |          |&lt;---(C)--- Redirection URI ----&lt;|               |
     |          |          with Access Token     +---------------+
     |          |            in Fragment
     |          |                                +---------------+
     |          |----(D)--- Redirection URI ---->|   Web-Hosted  |
     |          |          without Fragment      |     Client    |
     |          |                                |    Resource   |
     |     (F)  |&lt;---(E)------- Script ---------&lt;|               |
     |          |                                +---------------+
     +-|--------+
       |    |
      (A)  (G) Access Token
       |    |
       ^    v
     +---------+
     |         |
     |  Client |
     |         |
     +---------+

Figura 4: Flusso di autorizzazione implicita (Implicit Grant Flow)

4.2.1. Richiesta di autorizzazione (Authorization Request)

Il client costruisce l'URI di richiesta aggiungendo i seguenti parametri al componente query dell'URI dell'endpoint di autorizzazione.

response_type
Richiesto (REQUIRED). Il valore deve (MUST) essere impostato su « token ».

client_id
Richiesto (REQUIRED). L'identificatore del client come descritto nella sezione 2.2.

redirect_uri
Facoltativo (OPTIONAL). Come descritto nella sezione 3.1.2.

scope
Facoltativo (OPTIONAL). L'ambito della richiesta di accesso come descritto nella sezione 3.3.

state
Raccomandato (RECOMMENDED). Un valore opaco utilizzato dal client per mantenere lo stato tra la richiesta e il callback.

4.2.2. Risposta del token di accesso (Access Token Response)

Se il proprietario della risorsa concede la richiesta di accesso, il server di autorizzazione emette un token di accesso (Access Token) e lo consegna al client aggiungendo i seguenti parametri al componente frammento dell'URI di reindirizzamento.

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

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

expires_in
Raccomandato (RECOMMENDED). La durata del token di accesso in secondi.

scope
Facoltativo (OPTIONAL) se identico all'ambito richiesto dal client; altrimenti, richiesto (REQUIRED).

state
Richiesto (REQUIRED) se il parametro « state » era presente nella richiesta di autorizzazione del client.

4.3. Credenziali password del proprietario della risorsa (Resource Owner Password Credentials Grant)

Il tipo di autorizzazione tramite credenziali password del proprietario della risorsa (Resource Owner Password Credentials Grant Type) dovrebbe (SHOULD) essere utilizzato solo quando il proprietario della risorsa ha una relazione di fiducia con il client, come il sistema operativo del dispositivo o un'applicazione altamente privilegiata. Il server di autorizzazione dovrebbe (SHOULD) prestare particolare attenzione quando abilita questo tipo di autorizzazione quando altri tipi di autorizzazione non sono disponibili.

     +----------+
     | Resource |
     |  Owner   |
     |          |
     +----------+
          v
          |    Resource Owner
         (A) Password Credentials
          |
          v
     +---------+                                  +---------------+
     |         |>--(B)---- Resource Owner ------->|               |
     |         |         Password Credentials     | Authorization |
     | Client  |                                  |     Server    |
     |         |&lt;--(C)---- Access Token ---------&lt;|               |
     |         |    (w/ Optional Refresh Token)   |               |
     +---------+                                  +---------------+

Figura 5: Flusso delle credenziali password del proprietario della risorsa

4.3.2. Richiesta di token di accesso (Access Token Request)

grant_type
Richiesto (REQUIRED). Il valore deve (MUST) essere impostato su « password ».

username
Richiesto (REQUIRED). Il nome utente del proprietario della risorsa.

password
Richiesto (REQUIRED). La password del proprietario della risorsa.

scope
Facoltativo (OPTIONAL). L'ambito della richiesta di accesso come descritto nella sezione 3.3.

4.4. Credenziali del client (Client Credentials Grant)

Il client può (MAY) richiedere un token di accesso (Access Token) utilizzando solo le proprie credenziali del client (Client Credentials) (o altri mezzi di autenticazione supportati). Il tipo di autorizzazione tramite credenziali del client deve (MUST) essere utilizzato solo quando il client è il proprietario della risorsa o quando il client richiede l'accesso alle risorse protette sulla base di un'autorizzazione precedentemente concordata con il server di autorizzazione.

     +---------+                                  +---------------+
     |         |                                  |               |
     |         |>--(A)- Client Authentication --->| Authorization |
     | Client  |                                  |     Server    |
     |         |&lt;--(B)---- Access Token ---------&lt;|               |
     |         |                                  |               |
     +---------+                                  +---------------+

Figura 6: Flusso delle credenziali del client (Client Credentials Flow)

4.4.2. Richiesta di token di accesso (Access Token Request)

grant_type
Richiesto (REQUIRED). Il valore deve (MUST) essere impostato su « client_credentials ».

scope
Facoltativo (OPTIONAL). L'ambito della richiesta di accesso come descritto nella sezione 3.3.

4.5. Autorizzazioni di estensione (Extension Grants)

Il client può (MAY) utilizzare un tipo di autorizzazione di estensione (Extension Grant Type) per richiedere un token di accesso (Access Token) aggiungendo i seguenti parametri al corpo dell'entità della richiesta HTTP utilizzando il formato application/x-www-form-urlencoded.

grant_type
Richiesto (REQUIRED). Il valore deve (MUST) essere un URI assoluto.

4.1. Autorizzazione tramite codice (Authorization Code Grant)​

4.1.1. Richiesta di autorizzazione (Authorization Request)​

4.1.2. Risposta di autorizzazione (Authorization Response)​

4.1.2.1. Risposta di errore (Error Response)​

4.1.3. Richiesta di token di accesso (Access Token Request)​

4.1.4. Risposta del token di accesso (Access Token Response)​

4.2. Autorizzazione implicita (Implicit Grant)​

4.2.1. Richiesta di autorizzazione (Authorization Request)​

4.2.2. Risposta del token di accesso (Access Token Response)​

4.3. Credenziali password del proprietario della risorsa (Resource Owner Password Credentials Grant)​

4.3.2. Richiesta di token di accesso (Access Token Request)​

4.4. Credenziali del client (Client Credentials Grant)​

4.4.2. Richiesta di token di accesso (Access Token Request)​

4.5. Autorizzazioni di estensione (Extension Grants)​

4.1. Autorizzazione tramite codice (Authorization Code Grant)

4.1.1. Richiesta di autorizzazione (Authorization Request)

4.1.2. Risposta di autorizzazione (Authorization Response)

4.1.2.1. Risposta di errore (Error Response)

4.1.3. Richiesta di token di accesso (Access Token Request)

4.1.4. Risposta del token di accesso (Access Token Response)

4.2. Autorizzazione implicita (Implicit Grant)

4.2.1. Richiesta di autorizzazione (Authorization Request)

4.2.2. Risposta del token di accesso (Access Token Response)

4.3. Credenziali password del proprietario della risorsa (Resource Owner Password Credentials Grant)

4.3.2. Richiesta di token di accesso (Access Token Request)

4.4. Credenziali del client (Client Credentials Grant)

4.4.2. Richiesta di token di accesso (Access Token Request)

4.5. Autorizzazioni di estensione (Extension Grants)