Convalida dei token per aggiungere autenticazione e autorizzazione alle distribuzioni API

È possibile aggiungere la funzionalità di autenticazione e autorizzazione a un gateway API facendo in modo che lo stesso gateway API convalidi i token inclusi in una richiesta (come descritto in questo argomento). In alternativa, è possibile fare in modo che il gateway API passi un token di accesso a più argomenti o a singolo argomento incluso in una richiesta a una funzione del responsabile autorizzazioni distribuita nelle funzioni OCI per la convalida (come descritto nella sezione Passaggio di token alle funzioni del responsabile autorizzazioni per aggiungere autenticazione e autorizzazione alle distribuzioni API).

Per consentire al gateway API stesso di convalidare il token incluso in una richiesta, è necessario creare un criterio di richiesta di autenticazione di tipo TOKEN_AUTHENTICATION. I token utilizzati per controllare l'accesso alle API sono spesso, ma non sempre, token Web JSON (JWT).

Quando si utilizza un criterio TOKEN_AUTHENTICATION, è possibile abilitare una distribuzione API per utilizzare i token per l'autenticazione e l'autorizzazione includendo due diversi tipi di criteri di richiesta nella specifica di distribuzione API:

Criterio di richiesta di autenticazione per l'intera distribuzione API che specifica l'uso dei token, incluse le modalità di convalida e se gli utenti finali non autenticati possono accedere agli instradamenti nella distribuzione API.
Criterio di richiesta di autorizzazione per ogni instradamento che specifica le operazioni che un utente finale può eseguire, facoltativamente in base ai valori specificati per la richiesta scope di un JWT.

È possibile aggiungere criteri di autenticazione e richiesta di autorizzazione a una specifica di distribuzione API effettuando le operazioni riportate di seguito.

Nota

Nelle release precedenti, sono stati creati criteri di richiesta di autenticazione di tipo JWT_AUTHENTICATION per utilizzare i JWT per l'autenticazione. I criteri di richiesta di autenticazione JWT_AUTHENTICATION esistenti sono ancora supportati (vedere Note sull'uso dei criteri di richiesta JWT_AUTHENTICATION). Tuttavia, se si stanno creando nuovi criteri di richiesta di autenticazione per autenticare i JWT, si consiglia di creare criteri di richiesta di autenticazione come criteri TOKEN_AUTHENTICATION. L'uso dei criteri TOKEN_AUTHENTICATION consente di:

Convalidare sia i token JWT che i token non JWT.
Convalidare i token utilizzando un provider di identità per ottenere un endpoint di introspezione.
Specificare i criteri di errore di convalida, inclusa la generazione di un nuovo token JWT in caso di token JWT non valido o mancante nella richiesta originale.

Che cosa accade durante l'autenticazione del token?

Quando un gateway API riceve una richiesta da un client API ed è stato specificato un criterio di autenticazione token, il gateway API individua un token (ad esempio, in un'intestazione token) e lo utilizza.

È possibile specificare il modo in cui il gateway API convalida il token ottenuto definendo il criterio di convalida del criterio di autenticazione token come uno dei seguenti tipi:

Endpoint di introspezione OAuth 2.0: specificare questo tipo di criterio di convalida se si desidera che il gateway API convalidi un token JWT o non JWT con l'endpoint di introspezione di un provider di identità. Per ottenere l'endpoint di introspezione, è necessario specificare l'URL di ricerca automatica del provider di identità. In questo caso, il gateway API passa le credenziali client (l'ID client, insieme al segreto client recuperato dal servizio Vault) al provider di identità per convalidare il token. Il token viene convalidato senza l'uso di chiavi pubbliche. Per velocizzare la convalida futura, è possibile specificare che si desidera che il gateway API inserisca nella cache la risposta dall'endpoint di introspezione, per un periodo compreso tra 1 ora (impostazione predefinita) e 24 ore. Se si sta definendo la specifica di distribuzione API in un file JSON e si desidera questo funzionamento, includere un criterio di convalida di tipo REMOTE_DISCOVERY.
JWKS remoti: specificare questo tipo di criterio di convalida se si desidera che il gateway API utilizzi chiavi di verifica pubbliche recuperate da un provider di identità in fase di esecuzione per verificare un JWT. In questo caso, il gateway API contatta il provider di identità per verificare il JWT. Il provider di identità funge da server di autorizzazione. Se si sta definendo la specifica di distribuzione API in un file JSON e si desidera questo funzionamento, includere un criterio di convalida di tipo REMOTE_JWKS.
Chiavi statiche: specificare questo tipo di criterio di convalida se si desidera che il gateway API utilizzi chiavi di verifica pubbliche già emesse da un provider di identità (definite 'chiavi statiche') per verificare un JWT. In questo caso, il gateway API può verificare il JWT localmente in runtime senza dover contattare il provider di identità. Il risultato è una convalida del token più rapida. Se si sta definendo la specifica di distribuzione API in un file JSON e si desidera questo funzionamento, includere un criterio di convalida di tipo STATIC_KEYS

Se la convalida riesce, il gateway API instrada la richiesta all'endpoint API appropriato.

Se la convalida non riesce a causa di un token non valido o mancante nella richiesta originale, è necessario specificare il funzionamento del gateway API definendo il criterio di errore di convalida del criterio di autenticazione token come uno dei seguenti tipi:

Predefinito (HTTP 401 non autorizzato): specificare questo tipo di criterio di errore di convalida se si desidera che il gateway API restituisca una risposta HTTP-401 al client API. Questa è la risposta predefinita. Se si sta definendo la specifica di distribuzione API in un file JSON e si desidera questo funzionamento, è sufficiente non includere un criterio di errore di convalida.
Risposta personalizzata: specificare questo tipo di criterio di errore di convalida se si desidera che il gateway API restituisca una risposta alternativa (una risposta modificata) al client API, anziché una risposta HTTP-401. Se si sta definendo la specifica di distribuzione API in un file JSON e si desidera questo funzionamento, includere un criterio di errore di convalida di tipo MODIFY_RESPONSE.
OAuth 2.0: specificare questo tipo di criterio di errore di convalida se si desidera che il gateway API ottenga un token JWT nuovo e valido dal provider di identità per le richieste GET (avendo prima memorizzato in modo sicuro i parametri di query della richiesta originale). Per le richieste PUT e POST, è possibile specificare un percorso relativo nella distribuzione API corrente a cui reindirizzare i client API. Utilizzando questo tipo di criterio di errore di convalida, è inoltre possibile definire un back-end di logout per rimuovere eventuali cookie di sessione associati, revocare i token richiamando l'endpoint della sessione finale del provider di identità e reindirizzare a un URL post-logout consentito. Se si sta definendo la specifica di distribuzione API in un file JSON e si desidera questo funzionamento, includere un criterio di errore di convalida di tipo OAUTH2.
Tenere presente che i criteri di errore di convalida di tipo OAuth 2.0 attualmente supportano solo il flusso di autorizzazione OpenID Connect e solo la generazione di token JWT (vedere Note su OAuth 2.0 e OpenID Connect). Nel caso del flusso di autorizzazione OpenID Connect, vengono restituiti due token denominati id_token (sempre codificato in JWT) e access_token (può essere codificato in JWT). Il gateway API salva i valori del token nelle variabili di contesto request.auth[id_token] e request.auth[access_token], insieme alle richieste personalizzate nelle variabili di contesto request.auth[id_token_claims][<claim-name>] e request.auth[access_token_claims][<claim-name>] rispettivamente (vedere Aggiunta di variabili di contesto ai criteri e definizioni backend HTTP). Alla ricezione del nuovo token JWT id_token, il gateway API recupera i dettagli della richiesta e riprende l'elaborazione della richiesta utilizzando il token.

La posizione da cui il gateway API ottiene un token dipende sia dal tipo di criterio di convalida (uno degli endpoint di introspezione OAuth 2.0, JWKS remoto o Chiavi statiche) che dal tipo di criterio di errore di convalida (uno dei seguenti: Predefinito (HTTP 401 non autorizzato), Risposta personalizzata o OAuth 2.0).

Se si specificano sia un criterio di convalida di tipo OAuth 2.0 endpoint di introspezione che un criterio di errore di convalida di tipo OAuth 2.0, il gateway API tenta inizialmente di ottenere il token da uno o dall'altro dei seguenti elementi:
- Se è stata selezionata l'opzione Usa cookie per sessione nel criterio di errore di convalida, da un cookie di sessione.
- In caso contrario, dall'intestazione X-APIGW-TOKEN nella richiesta.
Se il gateway API non è in grado di ottenere un token dalla posizione iniziale, il gateway API ottiene il token dall'intestazione della richiesta o dal parametro di query specificato nel criterio di autenticazione del token.

Se la convalida del token ha esito positivo e si seleziona l'opzione Usa cookie per la sessione, il gateway API memorizza il token generato come stringa non leggibile dall'uomo in un cookie di sessione. Se il client API effettua una richiesta successiva, il token viene ottenuto dal cookie di sessione. Per evitare attacchi CSRF, quando il TOKEN generato viene memorizzato in un cookie di sessione, il gateway API restituisce anche un TOKEN CSRF in un'intestazione di risposta X-CSRF-TOKEN (vedere Note sulla protezione CSRF (Cross-Site Request Forgery)).
Se non si specificano sia un criterio di convalida di tipo OAuth 2.0 endpoint di introspezione che un criterio di errore di convalida di tipo OAuth 2.0, il gateway API ottiene il token dall'intestazione della richiesta o dal parametro di query specificato nel criterio di autenticazione del token.

Note sui token Web JSON (JWT)

I token utilizzati per controllare l'accesso alle API sono in genere token Web JSON (JWT). Un JWT è un token di accesso basato su JSON inviato in una richiesta HTTP da un client API a una risorsa. I JWT vengono emessi dai provider di identità. Il gateway API supporta l'uso di qualsiasi provider di identità conforme a OAuth2, ad esempio IAM OCI con domini di Identity, Oracle Identity Cloud Service (IDCS), Auth0 e Okta. Se è necessario un JWT per accedere a una risorsa, la risorsa convalida il JWT con un server di autorizzazione utilizzando una chiave di verifica pubblica corrispondente, richiamando un endpoint di convalida sul server di autorizzazione o utilizzando una chiave di verifica locale fornita dal server di autorizzazione.

Un JWT comprende:

Un'intestazione che identifica il tipo di token e l'algoritmo crittografico utilizzato per generare la firma.
Un payload contenente le richieste di risarcimento relative all'identità dell'utente finale e le proprietà del JWT stesso. Una richiesta è una coppia di valori chiave, in cui la chiave è il nome della richiesta. Si consiglia di utilizzare un payload (anche se non necessario) per contenere determinate richieste riservate con nomi specifici, ad esempio l'ora di scadenza (exp), l'audience (aud), l'emittente (iss) e non prima (nbf). Un payload può anche contenere richieste personalizzate con nomi definiti dall'utente.
Una firma, per convalidare l'autenticità del JWT (derivata da base64 che codifica l'intestazione e il payload).

Quando si utilizzano i JWT per controllare l'accesso alle API, è possibile specificare che le richieste riservate nel payload del JWT devono avere valori specifici prima che il gateway API consideri valido il JWT. Per impostazione predefinita, i gateway API convalidano i JWT utilizzando le richieste di scadenza (exp), audience (aud) ed emittente (iss), insieme alla richiesta non precedente (nbf), se presente. È inoltre possibile specificare valori accettabili per le richieste di rimborso personalizzate. Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.

Quando un JWT è stato convalidato, il gateway API estrae le richieste dal payload del JWT come coppie di valori chiave e le salva come record nella tabella di contesto request.auth per l'uso da parte della distribuzione API. Ad esempio, come variabili di contesto da utilizzare in una definizione backend HTTP (vedere Aggiunta di variabili di contesto a criteri e definizioni backend HTTP). Se il payload del JWT contiene la richiesta scope, è possibile utilizzare i valori della richiesta nei criteri di richiesta di autorizzazione per i singoli instradamenti per specificare le operazioni che un utente finale può eseguire.

Note su OAuth 2.0 e OpenID Connect

Il protocollo OAuth 2.0 consente il recupero sicuro delle risorse sicure mentre si proteggono le credenziali del client. OAuth 2.0 è un protocollo flessibile e sicuro che si basa su SSL (Secure Sockets Layer) per garantire che i dati tra server Web e browser rimangano privati. Sebbene OAuth 2.0 sia diverso da JWT e utilizzato per scopi diversi, OAuth 2.0 e JWT sono compatibili. Poiché il protocollo OAuth2 non specifica il formato dei token, i JWT possono essere incorporati nell'uso di OAuth2. Per ulteriori informazioni su OAuth 2.0, consultare la documentazione di OAuth 2.0.

OpenID Connect è un livello di identità semplice al di sopra del protocollo OAuth 2.0. L'utilizzo di OpenID Connect consente ai gateway API di verificare l'identità di un client API in base all'autenticazione eseguita da un server di autorizzazione. OpenID Connect consente inoltre ai gateway API di ottenere informazioni di profilo di base sul client API. Per ulteriori informazioni su OpenID Connect, consulta la documentazione di OpenID Connect.

Note sulla protezione CSRF (Cross-Site Request Forgery)

Un utente malintenzionato può attivare un attacco CSRF sfruttando l'esistenza di un cookie del browser per indurre un utente a inviare un comando non intenzionale a un'applicazione Web, ad esempio un gateway API. Se l'applicazione determina che l'utente è già stato autenticato correttamente a causa dell'esistenza del cookie del browser, l'applicazione esegue il comando con conseguenze potenzialmente dannose.

Quando si definisce un criterio di convalida di tipo OAuth 2.0 endpoint di introspezione e un criterio di errore di convalida di tipo OAuth 2.0, è possibile specificare il modo in cui un gateway API memorizza un nuovo token JWT ottenuto utilizzando il flusso di autorizzazione OpenID Connect.

Selezionare l'opzione Usa cookie per sessione se si desidera memorizzare il nuovo token JWT in un cookie di sessione. Per evitare potenziali attacchi CSRF, quando il gateway API memorizza il TOKEN in un cookie di sessione, restituisce anche un TOKEN CSRF in un'intestazione di risposta X-CSRF-TOKEN. Le successive richieste di mutazione al gateway API (come le richieste POST, PUT e DELETE, ma non le richieste GET) devono includere il TOKEN CSRF in un'intestazione di richiesta X-CSRF-TOKEN, oltre al TOKEN JWT nel cookie di sessione incluso automaticamente.
Tenere presente che il gateway API memorizza anche il token CSRF nella variabile di contesto request.auth[apigw_csrf_token]. Se per qualche motivo il client API non è in grado di leggere l'intestazione di risposta X-CSRF-TOKEN iniziale, è possibile includere la variabile di contesto request.auth[apigw_csrf_token] in un criterio di risposta di trasformazione dell'intestazione per aggiungere un'intestazione di risposta contenente il token CSRF a ogni risposta restituita al client API. Questo approccio garantisce che il client API possa estrarre correttamente il token CSRF dall'intestazione della risposta per l'inclusione nelle successive intestazioni della richiesta di mutazione X-CSRF-TOKEN che invia al gateway API. Di seguito è riportato un esempio di criterio di risposta di trasformazione dell'intestazione appropriato.
```
"responsePolicies": {
        "headerTransformations": {
          "setHeaders": {
            "items": [
              {
                "name": "MY-CSRF-TOKEN",
                "values": ["${request.auth[apigw_csrf_token]}"],
                "ifExists": "OVERWRITE"              }
            ]
          }
        }
      }
```
Per ulteriori informazioni sui criteri di risposta per la trasformazione delle intestazioni, vedere Aggiunta di criteri di risposta per la trasformazione delle intestazioni.
Non selezionare l'opzione Usa cookie per sessione se non si desidera memorizzare il nuovo token JWT in un cookie di sessione. Invece, il gateway API restituisce un TOKEN non leggibile dall'utente in un'intestazione di risposta X-APIGW-TOKEN. Le richieste successive al gateway API devono includere lo stesso TOKEN in un'intestazione di richiesta X-APIGW-TOKEN.

Per ulteriori informazioni su CSRF, cercare in linea.

Note sull'uso dei criteri di richiesta JWT_AUTHENTICATION

Nelle release precedenti, potrebbe essere stato creato un criterio di richiesta di autenticazione di tipo JWT_AUTHENTICATION per utilizzare JWT per l'autenticazione.

Se si stanno creando nuovi criteri di richiesta di autenticazione per utilizzare JWT, ora si consiglia di creare criteri di richiesta di autenticazione di tipo TOKEN_AUTHENTICATION (vedere Uso della console per aggiungere criteri di richiesta di autenticazione e autorizzazione token e Modifica di un file JSON per aggiungere criteri di richiesta di autenticazione e autorizzazione token). Si consiglia inoltre di eseguire la migrazione dei criteri di richiesta JWT_AUTHENTICATION esistenti ai criteri TOKEN_AUTHENTICATION.