Autorizzazione per Scope

La verifica di un access token, se opaco tramite il servizio di Introspection (descritto nella sezione Validazione tramite Introspection), altrimenti tramite la validazione JWT (sezione Validazione JWT), permette a GovWay di conoscere i claims associati al token ed in particolare quali sono gli scope autorizzati dall’utente.

Gli scope permettono di definire delle «funzioni applicative» il cui utilizzo da parte di un’applicazione deve essere autorizzato da un utente.

Per simulare lo scenario utilizzeremo sempre il servizio Playground e l”Authorization Server di Google descritto nella precedente sezione Validazione tramite Introspection dove però verranno richiesti altri scope rispetto a quello utilizzato nel precedente scenario. Simuleremo di aver bisogno di accedere alle API Calendar di Google e quindi dovremo richiedere tali scope che devono essere autorizzati una volta che ci siamo autenticati su Google.

Su GovWay è possibile registrare gli scope disponibili su di un Authorization Server ed utilizzarli per definire politiche di autorizzazione rispetto agli scope presenti nell’access token. Lo scenario descritto in questa sezione mostra un esempio di registrazione degli scope “API Calendar” di Google dove si configura a titolo esemplificativo che tali scope sono necessari per poter invocare il servizio PetStore.

../../_images/oauth_scenario_scope.png — Fig. 1016 Scenario OAuth con autorizzazione per Scope

Acquisizione Access Token con scope API Calendar

Per simulare l’acquisizione di un token è possibile utilizzare l’applicazione Playground, disponibile all’indirizzo ` <https://developers.google.com/oauthplayground/>`__, che consente di richiedere un access token all”Authorization Server di Google.

L’applicazione Playground consente agevolmente di ottenere l”access token con gli scope richiesti dall’esempio:
1. Selezione scope
  
  Devono essere selezionati gli scope:
  Cliccando infine sul pulsante “Authorize APIs” si verrà rediretti alla pagina di autenticazione in google dove si dovrà procedere ad autenticarsi.
  
  Fig. 1017 Ottenimento Token: Playground Google, scelta scope API Calendar
2. Autorizzazione scope API Calendar
  
  Effettuata l’autenticazione in Google si viene rediretti ad una pagina dove è richiesto all’utente di autorizzare l’applicazione Playground all’utilizzo degli scope API Calendar.
  
  Fig. 1018 Ottenimento Token: Playground Google, autorizzazione scope API Calendar
3. Access Token
  
  Autorizzati gli scope si viene rediretti alla seconda fase prevista dall’applicazione Playground denominata “Exchange authorization code for tokens”. Cliccando sul pulsante “Exchange authorization code for tokens” si ottiene infine un access token da estrarre nella risposta http visualizzata sulla destra dell’applicazione.
  
  Fig. 1019 Ottenimento Token: Playground Google, Step 3

Registrazione degli scope su GovWay

Accedere alla sezione “Scope” della govwayConsole per registrare gli scope relativi ad API Calendar. Per registrare un nuovo scope cliccare sul pulsante “Aggiungi“. Effettuare la registrazione degli scopes richiesti precedentemente tramite Playground ed anche un ulteriore scope (API Google Driver), non richiesto durante l’acquisizione del token, che verrà utilizzato nei test descritti in questa sezione.

Tabella 33 Registrazione Scope
Nome	Identificativo Esterno	Contesto
google.calendar.events.readonly	https://www.googleapis.com/auth/calendar.events.readonly	Qualsiasi
google.calendar.readonly	https://www.googleapis.com/auth/calendar.readonly	Qualsiasi
google.calendar.settings.readonly	https://www.googleapis.com/auth/calendar.settings.readonly	Qualsiasi
google.drive	https://www.googleapis.com/auth/drive	Qualsiasi

../../_images/oauthScopeRegistrazioneConfig.png — Fig. 1020 Configurazione OAuth2 - Registrazione Scope

Terminata la registrazione gli scope è possibile specificarli all’interno del Controllo degli Accessi di una API.

../../_images/oauthScopeRegistrazioneConfigList.png — Fig. 1021 Configurazione OAuth2 - Lista degli Scope registrati

Configurazione Controllo degli Accessi

Accedere alla sezione “Erogazioni” e selezionare l’API precedentemente registrata “PetStore v1”. Dopodichè accedere, dal dettaglio dell’erogazione, alla sezione “Configurazione” dove vengono visualizzate le funzionalità attive. Cliccare sulla voce presente nella colonna “Controllo Accessi” e procedere con la seguente configurazione all’interno della sezione “Gestione Token”:
- Stato: abilitato
- Policy: Google
- Validazione JWT: disabilitato
- Introspection: abilitato
- User Info: disabilitato
- Token Forward: abilitato
Procedere inoltre con la seguente configurazione all’interno della sezione “Autorizzazione”:
- Autorizzazione - Stato: abilitato
- Autorizzazione per Scope - Stato: abilitato
- Autorizzazione per Scope - Scope Richiesti: tutti
Effettuata la configurazione salvarla cliccando sul pulsante “Salva”.

Fig. 1022 Configurazione OAuth2 - Autorizzazione

Salvata la configurazione si deve nuovamente accedere al “Controllo Accessi” dove nella sezione “Autorizzazione” è adesso disponibile un link “Scope (0)” che permette di registrare gli scope che un token deve possedere quando invoca l’api PetStore.

Fig. 1023 Configurazione OAuth2 - Autorizzazione - Scope

Tramite il pulsante “Aggiungi” aggiungere tutti e 4 gli scope precedentemente registrati su GovWay.

Fig. 1024 Configurazione OAuth2 - Autorizzazione - Elenco Scope

Invocazione API

Nota

Reset Cache delle Configurazioni prima di un nuovo test
Le configurazioni accedute da GovWay vengono mantenute in una cache dopo il primo accesso per 2 ore, è quindi necessario forzare un reset della cache. Per farlo accedere alla sezione “Strumenti” - “Runtime” e selezionare la voce “ResetAllCaches”.

Per effettuare il test utilizzare il token, contenente gli scope API Calendar, precedentemente ottenuto.

curl -v -X PUT "http://127.0.0.1:8080/govway/Ente/PetStore/v2/pet?access_token=ACCESS_TOKEN" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
        "id": 3,
        "category": { "id": 22, "name": "dog" },
        "name": "doggie",
        "photoUrls": [ "http://image/dog.jpg" ],
        "tags": [ { "id": 23, "name": "white" } ],
        "status": "available"
}'

L’esito dell’aggiornamento termina con un codice di errore http 403 e una risposta problem+json che riporta la motivazione:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="Google", error="insufficient_scope", error_description="The request requires higher privileges than provided by the access token", scope="https://www.googleapis.com/auth/calendar.events.readonly,https://www.googleapis.com/auth/calendar.readonly,https://www.googleapis.com/auth/calendar.settings.readonly,https://www.googleapis.com/auth/drive"
Content-Type: application/problem+json
Transfer-Encoding: chunked
Server: GovWay
GovWay-Transaction-ID: 6c13b9ac-3d60-45a6-9130-297a4d832824

{
    "type":"https://httpstatuses.com/403",
    "title":"Forbidden",
    "status":403,
    "detail":"La richiesta presenta un token non sufficiente per fruire del servizio richiesto",
    "govway_status":"protocol:GOVWAY-1368"
}

Consultazione Tracce in errore

Attraverso la console govwayMonitor è possibile consultare lo storico delle transazioni che sono transitate nel gateway. Dalla Fig. 1025 si può vedere come le transazioni generate dopo la configurazione sopra indicata sono terminate con errore con esito Autorizzazione Negata.

Fig. 1025 Tracce delle invocazioni terminate con errore “Autorizzazione Negata”

Accedendo al dettaglio di una transazione terminata in errore, e visualizzandone i diagnostici è possibile comprendere l’errore che come atteso risulta essere la mancanza dello scope https://www.googleapis.com/auth/drive richiesto poichè nella sezione “Autorizzazione” è stato indicato che gli scope registrati devono essere tutti presente nell’access token.

Fig. 1026 Diagnostici di una invocazione terminata con errore

Cliccando sul link “Visualizza” della voce “Token Info” è possibile vedere tutti i claims presenti nel token, dove si possono vedere gli scope richiesti tramite Playground.

Fig. 1027 Scope presenti nel Token
Modifica controllo degli scope (Almeno uno) in Configurazione Controllo degli Accessi

Tramite la govwayConsole accedere nuovamente alla maschera di configurazione “Controllo Accessi“ dell’API “PetStore v1”; all’interno della sezione “Autorizzare” modificare il tipo di controllo “Scope Richiesti“ dal valore “tutti” al valore “almeno uno”.

Fig. 1028 Configurazione OAuth2 - Autorizzazione degli scope con opzione “Almeno uno”

Nuova invocazione API

Nota

Reset Cache delle Configurazioni prima di un nuovo test
Effettuare il reset della cache accedendo alla sezione “Strumenti” - “Runtime” e selezionare la voce “ResetAllCaches”.

Effettuare una nuova invocazione del test.

curl -v -X PUT "http://127.0.0.1:8080/govway/Ente/PetStore/v2/pet?access_token=ACCESS_TOKEN" \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
        "id": 3,
        "category": { "id": 22, "name": "dog" },
        "name": "doggie",
        "photoUrls": [ "http://image/dog.jpg" ],
        "tags": [ { "id": 23, "name": "white" } ],
        "status": "available"
}'

L’esito dell’aggiornamento termina stavolta con successo con un codice http 200 e una risposta json equivalente alla richiesta.