Convalida dei token per aggiungere autenticazione e autorizzazione alle distribuzioni API

È possibile aggiungere funzionalità di autenticazione e autorizzazione a un gateway API facendo in modo che il gateway API stesso 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 un singolo argomento incluso in una richiesta a una funzione del responsabile autorizzazioni distribuita nelle funzioni OCI per la convalida (come descritto in Passaggio dei token alle funzioni del responsabile autorizzazioni per l'aggiunta di 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.

Uso di Console.
Modifica di un file JSON.

Nota

Nelle release precedenti, sono stati creati criteri di richiesta di autenticazione di tipo JWT_AUTHENTICATION per utilizzare 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 codificati 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>] (vedere Aggiunta di variabili di contesto ai criteri e alle 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 in seguito la convalida del token riesce e si seleziona l'opzione Usa cookie per sessione, il gateway API memorizza il token generato come stringa non leggibile dall'utente 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à. Gateway API supporta l'uso di qualsiasi provider di identità conforme a OAuth2, come 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 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 singoli instradamenti per specificare le operazioni che un utente finale è autorizzato a 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 di trasformazione dell'intestazione, vedere Aggiunta di criteri di risposta di trasformazione dell'intestazione.
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 i JWT, è ora consigliabile creare criteri di richiesta di autenticazione di tipo TOKEN_AUTHENTICATION (vedere Utilizzo della console per aggiungere criteri di autenticazione e richiesta di autorizzazione token e Modifica di un file JSON per aggiungere criteri di autenticazione e richiesta di autorizzazione token). Si consiglia inoltre di eseguire la migrazione dei criteri di richiesta JWT_AUTHENTICATION esistenti ai criteri TOKEN_AUTHENTICATION.

Tenere presente che i criteri di richiesta JWT_AUTHENTICATION esistenti sono ancora supportati. Tenere inoltre presente che, sebbene sia possibile creare nuovi criteri di richiesta JWT_AUTHENTICATION (come descritto nelle istruzioni originali nella sezione Utilizzo di un criterio di richiesta di autenticazione JWT_AUTHENTICATION (non più consigliato)), è consigliabile creare invece criteri di richiesta di autenticazione di tipo TOKEN_AUTHENTICATION.

Prerequisiti per l'autenticazione token

Prima di poter abilitare l'autenticazione e l'autorizzazione per le distribuzioni API utilizzando JWT:

Un provider di identità conforme a OAuth2 (ad esempio, IAM OCI con domini di Identity, Oracle Identity Cloud Service (IDCS), Auth0) deve essere già stato impostato per emettere JWT per gli utenti autorizzati ad accedere alla distribuzione API.
Se si desidera utilizzare le richieste personalizzate nei criteri di autorizzazione, è necessario impostare il provider di identità per aggiungere le richieste personalizzate alle richieste JWT che genera.

Per ulteriori informazioni, consulta la documentazione del provider di identità (ad esempio, la documentazione su OCI IAM with Identity Domains, la documentazione su Oracle Identity Cloud Service (IDCS) e la documentazione su Auth0).

Per convalidare un JWT utilizzando una chiave di verifica pubblica corrispondente fornita dal provider di identità emittente:

l'algoritmo di firma utilizzato per generare la firma JWT deve essere uno dei seguenti: RS256, RS384 o RS512
la chiave di verifica pubblica deve avere una lunghezza minima di 2048 bit e non deve superare i 4096 bit

Per convalidare i token utilizzando l'endpoint di introspezione di un server di autorizzazione:

Per ottenere le credenziali client (un ID client e un segreto client), è necessario aver già creato e registrato un'applicazione client con il server di autorizzazione. Per ulteriori informazioni, consultare la documentazione del server di autorizzazione (ad esempio, la documentazione di OCI IAM with Identity Domains, la documentazione di Oracle Identity Cloud Service (IDCS) e la documentazione di Auth0).
È necessario aver già memorizzato il segreto client ottenuto dal server di autorizzazione come segreto in un vault nel servizio Vault (vedere Creazione di un segreto in un vault) e conoscere l'OCID e il numero di versione del segreto.
È necessario aver già impostato un criterio per concedere ai gateway API in un gruppo dinamico l'autorizzazione per accedere al segreto vault contenente il segreto client (vedere Creare un criterio per concedere ai gateway API l'accesso alle credenziali memorizzate come segreti nel servizio vault).

Uso della console per aggiungere criteri di autenticazione token e richiesta di autorizzazione

Per aggiungere criteri di autenticazione e richiesta di autorizzazione a una specifica di distribuzione API utilizzando la console, procedere come segue.

Creare o aggiornare una distribuzione API utilizzando la console, selezionare l'opzione Da zero e immettere i dettagli nella pagina Informazioni di base.

Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.
Fare clic su Avanti per visualizzare la pagina Autenticazione.
Selezionare Autenticazione singola per specificare che si desidera utilizzare un singolo server di autenticazione per tutte le richieste.

Queste istruzioni si basano sul presupposto che si desidera utilizzare un singolo server di autenticazione. In alternativa, se si desidera utilizzare più server di autenticazione, selezionare Autenticazione multipla e seguire le istruzioni in Utilizzo della console per aggiungere più server di autenticazione alla stessa distribuzione API.
Selezionare o deselezionare la casella di controllo Abilita accesso anonimo per specificare se gli utenti finali non autenticati (ovvero anonimi) possono accedere agli instradamenti nella distribuzione dell'API.

Per impostazione predefinita, questa opzione non è selezionata. Se non si desidera che utenti anonimi possano accedere ai percorsi, non selezionare questa opzione. Tenere presente che se si seleziona questa opzione, è inoltre necessario specificare in modo esplicito ogni instradamento per il quale è consentito l'accesso anonimo selezionando Anonimo come Tipo di autorizzazione nel criterio di autorizzazione di ogni instradamento.
Selezionare OAuth 2.0 / OpenID Connect dalla lista di opzioni Tipo di autenticazione e specificare:
- Posizione token: indica se i token sono contenuti in un'intestazione di richiesta o in un parametro di query.
- Dettagli token di autenticazione: a seconda che i token siano contenuti in un'intestazione di richiesta o in un parametro di query, specificare:
  - Nome intestazione token: e Schema di autenticazione: se i token sono contenuti in un'intestazione di richiesta, immettere il nome dell'intestazione (ad esempio Authorization) e lo schema di autenticazione HTTP (al momento è supportato solo Bearer).
  - Nome parametro token: se i token sono contenuti in un parametro di query, immettere il nome del parametro di query.
Specificare come si desidera che il gateway API convalidi i token:
1. Se si desidera che il gateway API convalidi sia i token JWT che i token non JWT con un endpoint di introspezione del server di autorizzazione OAuth 2.0 utilizzando le credenziali client (incluso un segreto client recuperato da un vault nel servizio Vault), selezionare OAuth endpoint di introspezione 2.0 dalla lista Tipo e specificare:
  - ID client: l'ID client da inviare all'endpoint di introspezione. Per ottenere un ID client, creare e registrare un'applicazione client con il server di autorizzazione. Ad esempio, 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1 . Vedere Prerequisiti per l'autenticazione del token.
  - Vault in <compartment-name>: il nome di un vault nel servizio Vault che contiene il segreto client da inviare all'endpoint di introspezione. Per ottenere un segreto client, creare e registrare un'applicazione client con il server di autorizzazione. Vedere Prerequisiti per l'autenticazione del token.
  - Segreto del vault in <compartment name>: il nome di un segreto del vault che contiene il segreto client da inviare all'endpoint di introspezione.
  - Numero versione del segreto vault: la versione del segreto vault contenente il segreto client da inviare all'endpoint di introspezione.
  - URL di ricerca automatica: l'URL noto del server di autorizzazione da cui proviene il gateway API per ottenere gli endpoint dei metadati di autorizzazione. Ad esempio, https://my-idp/oauth2/default/.well-known/openid-configuration.
    Tenere presente che l'URL deve essere instradabile dalla subnet contenente il gateway API su cui viene distribuita l'API.
  - Durata massima della cache in ore: il numero di ore (tra 1 e 24) che il gateway API deve inserire nella cache la risposta dall'endpoint di introspezione.
  - Disallineamento massimo clock in secondi: (facoltativo) la differenza massima di tempo tra i clock di sistema del server di autorizzazione che ha emesso un token e il gateway API. Il valore immesso qui viene preso in considerazione quando il gateway API convalida un JWT per determinare se è ancora valido, utilizzando la richiesta not before (nbf) (se presente) e la richiesta di scadenza (exp) nel JWT. Il valore minimo (e predefinito) è 0, il valore massimo è 120.
  - Disabilita verifica SSL: indica se disabilitare la verifica SSL durante la comunicazione con il server di autorizzazione. Per impostazione predefinita, questa opzione non è selezionata. Oracle consiglia di non selezionare questa opzione perché può compromettere la convalida del token. API Gateway considera attendibili i certificati di più autorità di certificazione emessi per IAM OCI con domini di Identity, Oracle Identity Cloud Service (IDCS), Auth0 e Okta.
2. Se si desidera che il gateway API convalidi i JWT recuperando le chiavi di verifica pubbliche dal provider di identità in runtime, selezionare JWKS remoti dalla lista Tipo e specificare:
  - URI JWKS: l'URI da cui recuperare il set di chiavi Web JSON (JWKS) da utilizzare per verificare la firma nei JWT. Ad esempio, https://www.somejwksprovider.com/oauth2/v3/certs. Per ulteriori informazioni sull'URI da specificare, vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
    
    Nota:
    - L'URI deve essere instradabile dalla subnet contenente il gateway API su cui viene distribuita l'API.
    - Se il gateway API non riesce a recuperare JWKS, tutte le richieste alla distribuzione API restituiranno un codice di risposta HTTP 500. Per ulteriori informazioni sull'errore, fare riferimento al log di esecuzione del gateway API (vedere Aggiunta di log alle distribuzioni API).
    - Alcuni parametri chiave devono essere presenti in JWKS per verificare la firma del JWT (vedere Parametri chiave necessari per verificare le firme JWT).
    - JWKS può contenere fino a dieci chiavi.
  - Durata massima della cache in ore: il numero di ore (tra 1 e 24) in cui il gateway API inserisce il JWKS nella cache dopo averlo recuperato.
  - Disabilita verifica SSL: indica se disabilitare la verifica SSL durante la comunicazione con il provider di identità. Per impostazione predefinita, questa opzione non è selezionata. Oracle consiglia di non selezionare questa opzione perché può compromettere la convalida JWT. API Gateway considera attendibili i certificati di più autorità di certificazione emessi per IAM OCI con domini di Identity, Oracle Identity Cloud Service (IDCS), Auth0 e Okta.
3. Se si desidera che il gateway API convalidi i JWT con chiavi di verifica pubbliche già emesse da un provider di identità (abilitando il gateway API per verificare i JWT in locale senza dover contattare il provider di identità), selezionare Chiavi statiche dalla lista Tipo e specificare fino a dieci chiavi statiche:
  - ID chiave: l'identificativo della chiave statica utilizzata per firmare il JWT. Il valore deve corrispondere alla richiesta kid nell'intestazione JWT. Ad esempio, master_key.
  - Formato chiave: il formato della chiave statica, come chiave Web JSON o chiave pubblica con codifica PEM.
    - Chiave Web JSON: se la chiave statica è una chiave Web JSON, incollare la chiave in questo campo.
      
      Ad esempio:
```
{
  "kty": "RSA",
  "n": "0vx7agoebGc...KnqDKgw",
  "e": "AQAB",
  "alg": "RS256",
  "use": "sig"
}
```
      Tenere presente che alcuni parametri devono essere presenti nella chiave statica per verificare la firma del JWT (vedere Parametri chiave necessari per verificare le firme JWT). Inoltre, si noti che RSA è attualmente l'unico tipo di chiave supportato (kty).
    - Chiave pubblica con codifica PEM: se la chiave statica è una chiave pubblica con codifica PEM, incollare la chiave in questo campo. Ad esempio:
```
-----BEGIN PUBLIC KEY-----
XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH
-----END PUBLIC KEY-----
```
      Si noti che gli indicatori -----BEGIN PUBLIC KEY----- e -----END PUBLIC KEY----- sono obbligatori.
  - Un'altra chiave: fare clic per aggiungere altre chiavi (fino a un massimo di dieci).
(Facoltativo) Specificare ulteriori dettagli per la convalida del token JWT:
1. Nella sezione Problemi specificare i valori consentiti nella richiesta dell'autorità emittente (iss) di un JWT utilizzato per accedere alla distribuzione dell'API:
  - Emittenti consentiti: specificare l'URL (o una stringa di testo) per un provider di identità consentito nella richiesta di emittente (iss) di un JWT da utilizzare per accedere alla distribuzione API. Ad esempio, per abilitare un JWT emesso da IAM OCI con i domini di Identity da utilizzare per accedere alla distribuzione API, immettere https://identity.oraclecloud.com/ . Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - Un altro emittente: fare clic per aggiungere altri provider di identità (fino a un massimo di cinque).
2. Nella sezione Audience specificare i valori consentiti nella richiesta dell'audience (aud) di un JWT utilizzato per accedere alla distribuzione dell'API:
  - Audience consentite: specificare un valore consentito nella richiesta di audience (aud) di un JWT per identificare il destinatario previsto del token. Ad esempio, l'audience potrebbe essere, ma non deve essere, il nome host del gateway API. Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - Un'altra audience: fare clic per aggiungere altre audience (fino a un massimo di cinque).
3. Convalida delle richieste di risarcimento: (facoltativo) oltre ai valori per le richieste di risarcimento dell'audience aud e dell'emittente iss già specificate, è possibile specificare nomi e valori per una o più richieste di risarcimento aggiuntive da convalidare in un JWT. Tenere presente che i nomi e i valori delle chiavi immessi vengono gestiti semplicemente come stringhe e devono corrispondere esattamente ai nomi e ai valori nel JWT. La corrispondenza dei pattern e altri tipi di dati non sono supportati.
  - Richiesta obbligatoria: specificare se la richiesta nel campo Chiave richiesta deve essere inclusa nel JWT.
  - Chiave richiesta: (facoltativo) specificare il nome di una richiesta che può essere o deve essere inclusa in un JWT. Se il sinistro deve essere incluso nel JWT, selezionare Obbligatorio. Il nome della richiesta specificato può essere un nome di richiesta riservato, ad esempio la richiesta oggetto (sub) o un nome di richiesta personalizzato emesso da un determinato provider di identità.
  - Valori sinistro: (facoltativo) specificare un valore accettabile per il sinistro nel campo Chiave sinistro. Fare clic sul segno più (+) per immettere un altro valore accettabile. Se si specificano uno o più valori accettabili per la richiesta, il gateway API verifica che la richiesta contenga uno dei valori specificati.
  Si noti che è possibile specificare un sinistro in un JWT senza specificarne un valore. A tale scopo, immettere il nome della richiesta nel campo Chiave richiesta, lasciare vuoto il campo Valori richiesta e impostare La richiesta è obbligatoria in base alle esigenze.
Specificare come si desidera che il gateway API gestisca una risposta di autenticazione non riuscita (restituita dopo un tentativo non riuscito di convalidare un token mancante o non valido) impostando un criterio di errore di convalida:
1. Se si desidera che il gateway API invii un codice di stato HTTP 401 e l'intestazione WWW-Authenticate nella risposta (la risposta predefinita a un token mancante o non valido), selezionare Predefinito (HTTP 401 non autorizzato).
2. Se si desidera che il gateway API utilizzi un flusso di autorizzazione OpenID Connect per ottenere un nuovo token di accesso JWT, selezionare OAuth 2.0. Questa opzione è disponibile solo se è stato selezionato OAuth 2.0 endpoint di introspezione dalla lista Tipo di convalida in precedenza. Specificare:
  - Scope: uno o più ambiti di accesso da includere in una richiesta scope inviata al server di autorizzazione. Per utilizzare il flusso di autorizzazione OpenID Connect, è necessario includere openid come uno degli ambiti. Ad esempio, openid, email:read, profile.
  - Tipo di risposta: il tipo di risposta richiesto dal flusso di autorizzazione. Immettere code come tipo di risposta.
  - Percorso di reindirizzamento del fallback: (facoltativo) un percorso relativo nella distribuzione API corrente a cui reindirizzare i client API se la richiesta originale era una richiesta PUT o una richiesta POST. Ad esempio, /home
    Se la richiesta originale era una richiesta GET, l'elaborazione della richiesta riprende con un nuovo token di accesso JWT, quindi non viene utilizzato un percorso di fallback.
  - Percorso di logout: (facoltativo) percorso relativo di un backend di logout nella distribuzione API corrente. Il percorso specificato deve corrispondere al percorso di instradamento definito per il back-end di logout. Ad esempio, /revoke
    Un client API può richiamare il back-end di logout per revocare i token. Una chiamata al back-end di logout può includere un URL successivo al logout come parametro di query denominato postLogoutUrl. Vedere Aggiunta del logout come backend del gateway API.
  - Scadenza risposta in ore: (facoltativo) il periodo di tempo necessario per inserire nella cache il token JWT generato dal flusso di autorizzazione. Il valore predefinito è 1 ora.
  - Utilizzare le credenziali client dell'endpoint di introspezione OAuth2: specificare se utilizzare gli stessi dettagli client specificati in precedenza per l'endpoint di introspezione OAuth 2.0 per ottenere un nuovo token di accesso JWT (in genere il caso). Se non si desidera utilizzare i dettagli specificati in precedenza, immettere dettagli client diversi da utilizzare per ottenere un nuovo token di accesso JWT dal server di autorizzazione, come indicato di seguito.
    - ID client: l'ID client da inviare all'endpoint di introspezione. Ad esempio, 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
    - Vault in <compartment-name>: il nome di un vault nel servizio Vault che contiene il segreto client da inviare all'endpoint di introspezione.
    - Segreto del vault in <compartment name>: il nome del segreto del vault che contiene il segreto client da inviare all'endpoint di introspezione.
    - Numero versione del segreto vault: la versione del segreto vault contenente il segreto client da inviare all'endpoint di introspezione.
  Facoltativamente, è possibile scegliere di memorizzare nei cookie i token e i valori ottenuti durante i flussi di autorizzazione OpenID selezionando Mostra opzioni avanzate e selezionando:
  - Utilizza i cookie per la sessione: (facoltativo) specificare come memorizzare i token JWT appena generati come stringhe non leggibili dall'utente alla fine di un flusso di autorizzazione OpenID Connect.
    - Selezionare questa opzione 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 richieste successive al gateway API (a parte 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.
    - Non selezionare questa opzione 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.
    Vedere Note sulla protezione CSRF (Cross-Site Request Forgery)
  - Utilizzare i cookie per i passi intermedi: (facoltativo) specificare come memorizzare i valori dei passi intermedi del flusso di autorizzazione (ad esempio, i parametri della richiesta). Selezionare questa opzione per memorizzare i valori nei cookie del browser. Deselezionare questa opzione per memorizzare i valori con il gateway API.
  - Usa PKCE: (facoltativo) specificare se utilizzare PKCE (chiave di prova per lo scambio di codice) per una sicurezza aggiuntiva. PKCE è un'estensione di sicurezza OAuth 2.0 per prevenire attacchi CSRF (Cross-Site Request Forgery) e code injection di autorizzazione. Il PKCE non sostituisce un segreto client e il PKCE è raccomandato anche se viene utilizzato un segreto client. Per ulteriori informazioni sul PKCE, consultare la documentazione OAuth 2.0.
3. Se si desidera personalizzare la risposta a un tentativo non riuscito di convalidare un token mancante o non valido, selezionare Risposta personalizzata e specificare un codice di stato (e un corpo del messaggio facoltativo) per tornare al client API:
  - Codice stato HTTP: immettere un codice di stato HTTP alternativo. Ad esempio, 500.
  - Corpo del messaggio: immettere un corpo per il messaggio. Ad esempio, Unfortunately, authentication failed.Il corpo del messaggio può includere qualsiasi variabile di contesto (ad eccezione di request.body).
  - Facoltativamente, modificare le intestazioni della risposta restituita dal gateway API al client API specificando un criterio di risposta di trasformazione dell'intestazione. Per ulteriori informazioni sui criteri di trasformazione dell'intestazione, vedere Aggiunta di criteri di risposta di trasformazione dell'intestazione.
Fare clic su Avanti per immettere i dettagli relativi ai singoli instradamenti nella distribuzione API nella pagina Instradamenti.
Nella sezione Route 1 specificare il primo instradamento nella distribuzione API che esegue il mapping di un percorso e di uno o più metodi a un servizio backend:
- Percorso: un percorso per le chiamate API che utilizzano i metodi elencati per il servizio backend. Tenere presente che il percorso di instradamento specificato è il seguente:
  - è relativo al prefisso del percorso di distribuzione
  - deve essere preceduta da una barra ( / ) e può essere solo la singola barra
  - può contenere più barre in avanti (a condizione che non siano adiacenti) e può terminare con una barra in avanti
  - può includere caratteri alfanumerici maiuscoli e minuscoli
  - può includere i caratteri speciali $ - _ . + ! * ' ( ) , % ; : @ & =
  - può includere parametri e caratteri jolly (vedere Aggiunta di parametri di percorso e caratteri jolly ai percorsi di instradamento)
- Metodi: uno o più metodi accettati dal servizio backend, separati da virgole. Ad esempio, GET, PUT.
- Aggiungere un backend singolo o Aggiungere più backend: indica se instradare tutte le richieste allo stesso backend o instradare le richieste a backend diversi in base alla variabile di contesto e alle regole immesse.
  
  Queste istruzioni presuppongono di voler utilizzare un singolo backend, quindi selezionare Aggiungi un backend singolo. In alternativa, se si desidera utilizzare backend diversi, selezionare Aggiungi più backend e seguire le istruzioni in Utilizzo della console per aggiungere la selezione backend dinamica a una specifica di distribuzione API.
- Tipo backend: il tipo di servizio backend, ovvero uno dei seguenti:
  - HTTP: per un backend HTTP, è inoltre necessario specificare un URL, i dettagli del timeout e se disabilitare la verifica SSL (vedere Aggiunta di un URL HTTP o HTTPS come backend del gateway API).
  - Oracle Functions: per un backend OCI Functions, è necessario specificare anche l'applicazione e la funzione (vedere Aggiunta di una funzione nelle funzioni OCI come backend del gateway API).
  - Risposta scorte: per un back-end di risposta scorte, è necessario specificare anche il codice di stato HTTP, il contenuto nel corpo della risposta e uno o più campi di intestazione HTTP (vedere Aggiunta di risposte scorte come backend del gateway API).
  - Logout: per un backend di logout, è inoltre necessario specificare una lista di URL consentiti ai quali è possibile reindirizzare una richiesta per revocare i token e, facoltativamente, i dati da passare all'URL di logout (vedere Aggiunta del logout come backend del gateway API).
Per specificare un criterio di autorizzazione applicabile a un singolo instradamento, fare clic su Mostra criteri richiesta di instradamento, fare clic sul pulsante Aggiungi accanto a Autorizzazione e specificare:
- Tipo di autorizzazione: procedura per concedere l'accesso all'instradamento. Specificare:
  - Qualsiasi: concedere l'accesso solo agli utenti finali che sono stati autenticati correttamente, a condizione che il JWT disponga di una richiesta scope che includa almeno uno degli ambiti di accesso specificati nel campo Ambito consentito. In questo caso, l'opzione Abilita accesso anonimo del criterio di autenticazione non ha alcun effetto.
  - Anonimo: concede l'accesso a tutti gli utenti finali, anche se l'autenticazione con JWT non è riuscita. In questo caso, è necessario aver selezionato l'opzione Abilita accesso anonimo del criterio di autenticazione.
  - Solo autenticazione: concede l'accesso solo agli utenti finali che sono stati autenticati correttamente utilizzando il JWT. In questo caso, l'opzione Abilita accesso anonimo del criterio di autenticazione non ha alcun effetto.
- Ambito consentito: se si seleziona Qualsiasi come Tipo di autorizzazione, immettere una lista delimitata da virgole di una o più stringhe che corrispondono agli ambiti di accesso nel JWT. L'accesso verrà concesso solo agli utenti finali che sono stati autenticati correttamente se il JWT dispone di una richiesta scope che include uno degli ambiti di accesso specificati. Ad esempio read:hello
Nota

Se non si include un criterio di autorizzazione per un instradamento particolare, viene concesso l'accesso come se tale criterio esistesse e l'opzione Tipo di autorizzazione fosse impostata su Solo autenticazione. In altre parole, indipendentemente dall'impostazione dell'opzione Abilita accesso anonimo del criterio di autenticazione:
- solo gli utenti finali autenticati possono accedere al percorso
- tutti gli utenti finali autenticati possono accedere all'instradamento indipendentemente dagli ambiti di accesso nella richiesta scope di JWT
- gli utenti finali anonimi non possono accedere al percorso
Fare clic su Applica modifiche, quindi su Avanti per esaminare i dettagli immessi per la distribuzione dell'API.
Fare clic su Crea o su Salva modifiche per creare o aggiornare la distribuzione API.
(Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Modifica di un file JSON per aggiungere criteri di autenticazione token e richiesta di autorizzazione

Per aggiungere criteri di autenticazione e richiesta di autorizzazione a una specifica di distribuzione API in un file JSON, effettuare le operazioni riportate di seguito.

Utilizzando l'editor JSON preferito, modificare la specifica di distribuzione API esistente alla quale si desidera aggiungere la funzionalità di autenticazione e autorizzazione oppure creare una nuova specifica di distribuzione API (vedere Creazione di una specifica di distribuzione API).

La specifica di distribuzione API includerà almeno una sezione routes contenente:
- Un percorso. Ad esempio /hello
- Uno o più metodi. Ad esempio, GET
- Definizione di un back end. Ad esempio, un URL o l'OCID di una funzione in Funzioni OCI.
Ad esempio, la seguente specifica di distribuzione API di base definisce una semplice funzione serverless Hello World in Funzioni OCI come un singolo backend:
```
{
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

Inserire una sezione requestPolicies prima della sezione routes (se non esiste già) per creare un criterio di richiesta authentication che si applica a tutti gli instradamenti nella specifica di distribuzione API. Ad esempio:


{
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}

Aggiungere il criterio di richiesta authentication come indicato di seguito.
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">,
      "tokenAuthScheme": "<authentication-scheme>",
      "isAnonymousAccessAllowed": <true|false>,
      "maxClockSkewInSeconds": <seconds-difference>,
      "validationPolicy": {<validation-policy-config>},
    }
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
dove:
- "authentication": {"type": "TOKEN_AUTHENTICATION"... specifica che si desidera utilizzare i token per l'autenticazione.
- <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> indica se si tratta di un'intestazione di richiesta che contiene il token (e, in caso affermativo, il nome dell'intestazione) o un parametro di query che contiene il token (e, in caso affermativo, il nome del parametro di query). Si noti che è possibile specificare "tokenHeader": "<token-header-name>" o "tokenQueryParam": "<token-query-param-name>">, ma non entrambi. Ad esempio, "tokenHeader": "Authorization"
- <tokenAuthScheme> è il nome dello schema di autenticazione da utilizzare se il token è contenuto nell'intestazione di una richiesta. Ad esempio, "Bearer".
- "isAnonymousAccessAllowed": <true|false> indica facoltativamente se gli utenti finali non autenticati (ovvero anonimi) possono accedere agli instradamenti nella specifica di distribuzione API. Se non si desidera che gli utenti finali anonimi possano accedere ai percorsi, impostare questa proprietà su false. Se non si include questa proprietà nel criterio authentication, viene utilizzato il valore predefinito false. Tenere presente che se si include questa proprietà e la si imposta su true, è inoltre necessario specificare in modo esplicito ogni instradamento per il quale è consentito l'accesso anonimo impostando la proprietà type su "ANONYMOUS" nel criterio authorization di ogni instradamento.
- maxClockSkewInSeconds: <seconds-difference> specifica facoltativamente la differenza di tempo massima tra i clock di sistema del provider di identità che ha emesso un JWT e il gateway API. Il valore specificato viene preso in considerazione quando il gateway API convalida il JWT per determinare se è ancora valido, utilizzando la richiesta not before (nbf) (se presente) e la richiesta di scadenza (exp) nel JWT. Il valore minimo (e predefinito) è 0, il valore massimo è 120.
- "validationPolicy": {<validation-policy-config>} specifica un criterio di convalida per la convalida dei token, come descritto nella procedura riportata di seguito.
Se si desidera che il gateway API convalidi sia i token JWT che i token non JWT con un endpoint di introspezione del server di autorizzazione OAuth 2.0 utilizzando le credenziali client (incluso un segreto client recuperato da un vault nel servizio Vault), aggiungere il seguente criterio di convalida alla sezione validationPolicy vuota:
```
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",          
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "<client-id>",
          "clientSecretId": "<secret-ocid>",
          "clientSecretVersionNumber": <secret-version-number>
        },          
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "<well-known-uri>"
        },
        "isSslVerifyDisabled": <true|false>,
        "maxCacheDurationInHours": <cache-time>,
        "additionalValidationPolicy": {
          "issuers": ["<issuer-url>", "<issuer-url>"],
          "audiences": ["<intended-audience>"],
          "verifyClaims": [{
            "key": "<claim-name>",
            "values": ["<acceptable-value>", "<acceptable-value>"],
            "isRequired": <true|false>
          }]
        }
      }
```
dove:
- "validationPolicy": {"type": "REMOTE_DISCOVERY"...} specifica che si desidera convalidare i token con un endpoint di introspezione del server di autorizzazione OAuth 2.0 utilizzando le credenziali client (incluso un segreto client recuperato da un vault nel servizio Vault).
- clientDetails": {"type": "CUSTOM"...} specifica i dettagli del segreto client da recuperare da un vault nel servizio Vault:
  - "clientId": "<client-id>" specifica l'ID client da inviare all'endpoint di introspezione. Per ottenere un ID client, creare e registrare un'applicazione client con il server di autorizzazione. Ad esempio, 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1 . Vedere Prerequisiti per l'autenticazione del token.
  - "clientSecretId": "<secret-ocid>" specifica l'OCID del segreto vault contenente il segreto client da inviare all'endpoint di introspezione. Ad esempio, ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
  - "clientSecretVersionNumber": <secret-version-number> specifica la versione del segreto vault che contiene il segreto client da inviare all'endpoint di introspezione. ad esempio 1
- "uri": "<well-known-uri>" specifica l'URL noto di un server di autorizzazione da cui il gateway API deve ottenere gli endpoint dei metadati di autorizzazione. Ad esempio, https://my-idp/oauth2/default/.well-known/openid-configuration. Tenere presente che l'URL deve essere instradabile dalla subnet contenente il gateway API su cui viene distribuita l'API.
- "isSslVerifyDisabled": <true|false> indica se disabilitare la verifica SSL durante la comunicazione con il server di autorizzazione. Oracle consiglia di non impostare questa opzione su true perché può compromettere la convalida JWT. API Gateway considera attendibili i certificati di più autorità di certificazione emessi per IAM OCI con domini di Identity, Oracle Identity Cloud Service (IDCS), Auth0 e Okta.
- "maxCacheDurationInHours": <cache-time> specifica il numero di ore (tra 1 e 24) in cui il gateway API deve inserire nella cache la risposta dall'endpoint di introspezione.
- "additionalValidationPolicy": {"issuers": ...} specifica dettagli aggiuntivi per la convalida del token:
  - <issuer-url> è l'URL (o una stringa di testo) per un server di autorizzazione consentito nella richiesta emittente (iss) di un JWT da utilizzare per accedere alla distribuzione API. Ad esempio, per abilitare un JWT emesso da IAM OCI con i domini di Identity da utilizzare per accedere alla distribuzione API, specificare https://identity.oraclecloud.com/ . È possibile specificare uno o più server di autorizzazione (fino a un massimo di cinque). Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - <intended-audience> è un valore consentito nella richiesta di audience (aud) di un JWT per identificare il destinatario previsto del token. Ad esempio, l'audience potrebbe essere, ma non deve essere, il nome host del gateway API. È possibile specificare una o più audience (fino a un massimo di cinque). Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - "verifyClaims": {...} specifica facoltativamente nomi e valori aggiuntivi per una o più richieste aggiuntive da convalidare in un JWT (fino a un massimo di dieci):
    - "key": "<claim-name>" è il nome di una richiesta che può essere o deve essere inclusa in un JWT. Il nome della richiesta specificato può essere un nome di richiesta riservato, ad esempio la richiesta oggetto (sub) o un nome di richiesta personalizzato emesso da un determinato server di autorizzazione.
    - "values": ["<acceptable-value>", "<acceptable-value>"] (facoltativamente) indica uno o più valori accettabili per la richiesta.
    - "isRequired": <true|false> indica se il sinistro deve essere incluso nel JWT.
    Tenere presente che i nomi e i valori delle chiavi immessi vengono gestiti semplicemente come stringhe e devono corrispondere esattamente ai nomi e ai valori nel JWT. Corrispondenza pattern e altri tipi di dati non supportati
Ad esempio, il seguente criterio authentication configura il gateway API per convalidare un token nell'intestazione della richiesta di autorizzazione utilizzando le credenziali client (incluso un segreto client recuperato da un vault nel servizio Vault) passato a un endpoint di introspezione OAuth 2.0):
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "maxClockSkewInSeconds": 10,
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        "clientDetails": {
          "type": "CUSTOM",
          "clientId": "5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1",
          "clientSecretId": "ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q",
          "clientSecretVersionNumber": 1
        },          
        "sourceUriDetails": {
          "type": "DISCOVERY_URI",
          "uri": "https://my-idp/oauth2/default/.well-known/openid-configuration"
        },
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
Se si desidera che il gateway API convalidi i JWT recuperando le chiavi di verifica pubbliche dal provider di identità in fase di esecuzione, aggiungere il seguente criterio di convalida alla sezione validationPolicy vuota:
```
      "validationPolicy": {
        "type": "REMOTE_JWKS",
        "uri": "<uri-for-jwks>",
        "isSslVerifyDisabled": <true|false>,
        "maxCacheDurationInHours": <cache-time>,
        "additionalValidationPolicy": {
          "issuers": ["<issuer-url>", "<issuer-url>"],
          "audiences": ["<intended-audience>"],
          "verifyClaims": [{
            "key": "<claim-name>",
            "values": ["<acceptable-value>", "<acceptable-value>"],
            "isRequired": <true|false>
          }]
        }
      }
```
dove:
- "validationPolicy": {"type": "REMOTE_JWKS"... specifica che si desidera configurare il gateway API per recuperare fino a dieci chiavi di verifica pubbliche dal provider di identità in runtime.
- "uri": "<uri-for-jwks>" specifica l'URI da cui recuperare il set di chiavi Web JSON (JWKS) da utilizzare per verificare la firma sui JWT. Per ulteriori informazioni sull'URI da specificare, vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS. Nota:
  - L'URI deve essere instradabile dalla subnet contenente il gateway API su cui viene distribuita l'API.
  - Se il gateway API non riesce a recuperare JWKS, tutte le richieste alla distribuzione API restituiranno un codice di risposta HTTP 500. Per ulteriori informazioni sull'errore, fare riferimento al log di esecuzione del gateway API (vedere Aggiunta di log alle distribuzioni API).
  - Alcuni parametri chiave devono essere presenti in JWKS per verificare la firma del JWT (vedere Parametri chiave necessari per verificare le firme JWT).
  - JWKS può contenere fino a dieci chiavi.
- "isSslVerifyDisabled": <true|false> indica se disabilitare la verifica SSL durante la comunicazione con il provider di identità. Oracle consiglia di non impostare questa opzione su true perché può compromettere la convalida JWT. API Gateway considera attendibili i certificati di più autorità di certificazione emessi per IAM OCI con domini di Identity, Oracle Identity Cloud Service (IDCS), Auth0 e Okta.
- "maxCacheDurationInHours": <cache-time> specifica il numero di ore (tra 1 e 24) in cui il gateway API deve inserire il JWKS nella cache dopo averlo recuperato.
- "additionalValidationPolicy": {"issuers": ...} specifica dettagli aggiuntivi per la convalida del token:
  - <issuer-url> è l'URL (o una stringa di testo) per un provider di identità consentito nella richiesta emittente (iss) di un JWT da utilizzare per accedere alla distribuzione API. Ad esempio, per abilitare un JWT emesso da IAM OCI con i domini di Identity da utilizzare per accedere alla distribuzione API, immettere https://identity.oraclecloud.com/ . È possibile specificare uno o più provider di identità (fino a un massimo di cinque). Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - <intended-audience> è un valore consentito nella richiesta di audience (aud) di un JWT per identificare il destinatario previsto del token. Ad esempio, l'audience potrebbe essere, ma non deve essere, il nome host del gateway API. È possibile specificare una o più audience (fino a un massimo di cinque). Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - verifyClaims specifica facoltativamente nomi e valori aggiuntivi per una o più richieste aggiuntive da convalidare in un JWT (fino a un massimo di dieci).
    - "key": "<claim-name>" è il nome di una richiesta che può essere o deve essere inclusa in un JWT. Il nome della richiesta specificato può essere un nome di richiesta riservato, ad esempio la richiesta oggetto (sub) o un nome di richiesta personalizzato emesso da un determinato provider di identità.
    - "values": ["<acceptable-value>", "<acceptable-value>"] (facoltativamente) indica uno o più valori accettabili per la richiesta.
    - "isRequired": <true|false> indica se il sinistro deve essere incluso nel JWT.
    Tenere presente che i nomi e i valori delle chiavi immessi vengono gestiti semplicemente come stringhe e devono corrispondere esattamente ai nomi e ai valori nel JWT. Corrispondenza pattern e altri tipi di dati non supportati
Ad esempio, il seguente criterio authentication configura il gateway API per convalidare il gateway JWT nell'intestazione della richiesta di autorizzazione recuperando le chiavi di verifica pubbliche dal provider di identità in runtime:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "REMOTE_JWKS",
        "uri": "https://my-tenant-id.identity.oraclecloud.com/admin/v1/SigningCert/jwk",
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
Se si desidera che il gateway API convalidi i JWT con chiavi di verifica pubbliche già emesse da un provider di identità (che abilita il gateway API per verificare i JWT localmente senza dover contattare il provider di identità), aggiungere il seguente criterio di convalida alla sezione vuota validationPolicy:
```
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [{<key-config>}],
        "isSslVerifyDisabled": <true|false>,
        "maxCacheDurationInHours": <cache-time>,
        "additionalValidationPolicy": {
          "issuers": ["<issuer-url>", "<issuer-url>"],
          "audiences": ["<intended-audience>"],
          "verifyClaims": [{
            "key": "<claim-name>",
            "values": ["<acceptable-value>", "<acceptable-value>"],
            "isRequired": <true|false>
          }]
        }
      }
```
dove:
- "validationPolicy": {"type": "STATIC_KEYS"... specifica che si desidera configurare il gateway API con un massimo di dieci chiavi di verifica pubbliche già emesse da un provider di identità (abilitando il gateway API per verificare i JWT a livello locale senza dover contattare il provider di identità).
- "keys": [{<key-config>}] specifica l'identificativo della chiave statica utilizzata per firmare il JWT. I dettagli da fornire dipendono dal formato della chiave già emessa dal provider di identità (indipendentemente dal formato, è possibile specificare fino a dieci chiavi):
  - Se la chiave statica è una chiave Web JSON, specificare "format": "JSON_WEB_KEY", specificare l'identificativo della chiave statica utilizzata per firmare il JWT come valore del parametro "kid" e fornire i valori per altri parametri per verificare la firma del JWT.
    
    Ad esempio:
```
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
```
    Tenere presente che alcuni parametri devono essere presenti nella chiave statica per verificare la firma del JWT (vedere Parametri chiave necessari per verificare le firme JWT). Inoltre, si noti che RSA è attualmente l'unico tipo di chiave supportato (kty).
  - Se la chiave statica è una chiave pubblica con codifica PEM, specificare "format": "PEM", specificare l'identificativo della chiave statica utilizzata per firmare il JWT come valore di "kid" e fornire la chiave come valore di "key".
    
    Ad esempio:
```
        "keys": [
          {
            "format": "PEM",
            "kid": "master_key"
            "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY-----
          }
        ]
```
    Si noti che gli indicatori -----BEGIN PUBLIC KEY----- e -----END PUBLIC KEY----- sono obbligatori.
- "isSslVerifyDisabled": <true|false> indica se disabilitare la verifica SSL durante la comunicazione con il provider di identità. Oracle consiglia di non impostare questa opzione su true perché può compromettere la convalida JWT. API Gateway considera attendibili i certificati di più autorità di certificazione emessi per IAM OCI con domini di Identity, Oracle Identity Cloud Service (IDCS), Auth0 e Okta.
- "maxCacheDurationInHours": <cache-time> specifica il numero di ore (tra 1 e 24) in cui il gateway API deve inserire il JWKS nella cache dopo averlo recuperato.
- "additionalValidationPolicy": {"issuers": ...} specifica dettagli aggiuntivi per la convalida del token:
  - <issuer-url> è l'URL (o una stringa di testo) per un provider di identità consentito nella richiesta emittente (iss) di un JWT da utilizzare per accedere alla distribuzione API. Ad esempio, per abilitare un JWT emesso da IAM OCI con i domini di Identity da utilizzare per accedere alla distribuzione API, immettere https://identity.oraclecloud.com/ . È possibile specificare uno o più provider di identità (fino a un massimo di cinque). Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - <intended-audience> è un valore consentito nella richiesta di audience (aud) di un JWT per identificare il destinatario previsto del token. Ad esempio, l'audience potrebbe essere, ma non deve essere, il nome host del gateway API. È possibile specificare una o più audience (fino a un massimo di cinque). Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - verifyClaims specifica facoltativamente nomi e valori aggiuntivi per una o più richieste aggiuntive da convalidare in un JWT (fino a un massimo di dieci).
    - "key": "<claim-name>" è il nome di una richiesta che può essere o deve essere inclusa in un JWT. Il nome della richiesta specificato può essere un nome di richiesta riservato, ad esempio la richiesta oggetto (sub) o un nome di richiesta personalizzato emesso da un determinato provider di identità.
    - "values": ["<acceptable-value>", "<acceptable-value>"] (facoltativamente) indica uno o più valori accettabili per la richiesta.
    - "isRequired": <true|false> indica se il sinistro deve essere incluso nel JWT.
    Tenere presente che i nomi e i valori delle chiavi immessi vengono gestiti semplicemente come stringhe e devono corrispondere esattamente ai nomi e ai valori nel JWT. Corrispondenza pattern e altri tipi di dati non supportati
Ad esempio, il seguente criterio authentication configura il gateway API con una chiave di verifica pubblica già emessa da un provider di identità per convalidare il JWT nell'intestazione della richiesta di autorizzazione:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
(Facoltativo) È possibile specificare come si desidera che il gateway API gestisca una risposta di autenticazione non riuscita (restituita dopo un tentativo non riuscito di convalidare un token mancante o non valido) impostando un criterio di errore di convalida:
1. Se si desidera che il gateway API invii un codice di stato HTTP 401 e l'intestazione WWW-Authenticate nella risposta (la risposta predefinita a un token mancante o non valido), non definire un criterio di errore di convalida.
2. Se si desidera che il gateway API utilizzi un flusso di autorizzazione OpenID Connect per ottenere un nuovo token di accesso JWT, definire un criterio di errore di convalida di tipo OAUTH2. Si noti che questa opzione è disponibile solo se è stato specificato un valore validationPolicy di tipo REMOTE_DISCOVERY in precedenza. Specificare:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        ...
      },
      "validationFailurePolicy": {
        "type": "OAUTH2",
        "scopes": ["<scope>", "<scope"],
        "clientDetails": {
          "type": "<VALIDATION_BLOCK|CUSTOM>",
          "clientId": "<client-id>",
          "clientSecretId": "<secret-ocid>",
          "clientSecretVersionNumber": <secret-version-number>
          },
        "sourceUriDetails": {
          "type": "VALIDATION_BLOCK"
          },
        "maxExpiryDurationInHours": <number-of-hours>,
        "useCookiesForSession": <true|false>,
        "useCookiesForIntermediateSteps": <true|false>,
        "usePkce": <true|false>,
        "responseType": "code",
        "fallbackRedirectPath": "<redirect-path>",
        "logoutPath": "<logout-path>"
      }
    }
  },
  "routes": [
    ...
  ]
}
```
  dove:
  - "scopes": ["<scope>", "<scope"] specifica uno o più ambiti di accesso da includere in una richiesta scope inviata al server di autorizzazione. Per utilizzare il flusso di autorizzazione OpenID Connect, è necessario includere openid come uno degli ambiti. Ad esempio, "scopes": ["openid", "email:read", "profile"]
  - clientDetails": {...} specifica i dettagli del client da utilizzare per ottenere un nuovo token di accesso JWT dal server di autorizzazione, come indicato di seguito.
    - "type": "<VALIDATION_BLOCK|CUSTOM>" specifica se utilizzare gli stessi dettagli client o diversi rispetto a quelli specificati nel precedente file validationPolicy. Se si desidera utilizzare gli stessi dettagli del client di prima (che in genere si verifica), specificare "type": "VALIDATION_BLOCK" e non fornire dettagli aggiuntivi. Se si desidera utilizzare dettagli client diversi, specificare "type": "CUSTOM" e impostare i valori per "clientId", "clientSecretId" e "clientSecretVersionNumber".
    - "clientId": "<client-id>" specifica l'ID client da inviare all'endpoint di introspezione. Utilizzato solo se "type": "CUSTOM". Ad esempio, 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
    - "clientSecretId": "<secret-ocid>" specifica l'OCID del segreto vault contenente il segreto client da inviare all'endpoint di introspezione. Utilizzato solo se "type": "CUSTOM". Ad esempio, ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
    - "clientSecretVersionNumber": <secret-version-number> specifica la versione del segreto vault che contiene il segreto client da inviare all'endpoint di introspezione. Utilizzato solo se "type": "CUSTOM". ad esempio 1
  - "sourceUriDetails": {"type": "VALIDATION_BLOCK"} specifica che si desidera utilizzare lo stesso URL specificato nel precedente validationPolicy e l'URL noto di un server di autorizzazione da cui il gateway API deve ottenere gli endpoint dei metadati di autorizzazione.
  - "maxExpiryDurationInHours": <number-of-hours> specifica il periodo di tempo in cui inserire nella cache il token JWT generato dal flusso di autorizzazione. Il valore predefinito è 1.
  - "useCookiesForSession": <true|false> specifica come memorizzare i token JWT appena generati come stringhe non leggibili dall'utente alla fine di un flusso di autorizzazione OpenID Connect:
    - Impostare questa opzione su true 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 richieste successive (a parte 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.
    - Impostare questa opzione su false 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.
    Vedere Note sulla protezione CSRF (Cross-Site Request Forgery)
  - "useCookiesForIntermediateSteps": <true|false> specifica come memorizzare i valori dei passi intermedi del flusso di autorizzazione (ad esempio, i parametri di richiesta). Impostare questa opzione su true per memorizzare i valori nei cookie del browser. Impostare questa opzione su false per memorizzare i valori con il gateway API.
  - "usePkce": <true|false> specifica se utilizzare la chiave di prova PKCE (Proof Key for Code Exchange) per aumentare la sicurezza. PKCE è un'estensione di sicurezza OAuth 2.0 per prevenire attacchi CSRF (Cross-Site Request Forgery) e code injection di autorizzazione. Il PKCE non sostituisce un segreto client e il PKCE è raccomandato anche se viene utilizzato un segreto client. Per ulteriori informazioni sul PKCE, consultare la documentazione OAuth 2.0.
  - "responseType": "code" specifica il tipo di risposta richiesto dal flusso di autorizzazione. Specificare code come tipo di risposta.
  - "fallbackRedirectPath": "/home" specifica facoltativamente un percorso relativo nella distribuzione API corrente a cui reindirizzare i client API se la richiesta originale era una richiesta PUT o una richiesta POST. Ad esempio, /home.
    Se la richiesta originale era una richiesta GET, l'elaborazione della richiesta riprende con un nuovo token di accesso JWT, quindi non viene utilizzato un percorso di fallback.
  - "logoutPath": "<revoke-path>"Specifica facoltativamente un percorso relativo a un backend di logout nella distribuzione API corrente. Il percorso specificato deve corrispondere al percorso di instradamento definito per il back-end di logout. Ad esempio, "logoutPath": "/revoke".
    Un client API può richiamare il back-end di logout per revocare i token. Una chiamata al back-end di logout può includere un URL successivo al logout come parametro di query denominato postLogoutUrl. Vedere Aggiunta del logout come backend del gateway API.
  Ad esempio:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        "type": "REMOTE_DISCOVERY",
        ...
      },
      "validationFailurePolicy": {
        "type": "OAUTH2",
        "scopes": ["openid", "email:read", "profile"],
        "clientDetails": {
          "type": "VALIDATION_BLOCK"
          },
        "sourceUriDetails": {
          "type": "VALIDATION_BLOCK"
        },
        "maxExpiryDurationInHours": 2,
        "useCookiesForSession": true,
        "useCookiesForIntermediateSteps": true,
        "usePkce": true,
        "responseType": "code",
        "fallbackRedirectPath": "/home",
        "logoutPath": "/revoke"
      }
    }
  },
  "routes": [
    ...
  ]
}
```
3. Se si desidera personalizzare la risposta a un tentativo non riuscito di convalidare un token mancante o non valido, definire un criterio di errore di convalida di tipo MODIFY_RESPONSE e specificare un codice di stato (e un corpo del messaggio facoltativo) per tornare al client API, come indicato di seguito.
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        ...
      },
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "<alternative-response-code>",
        "responseMessage": "<custom-message-body>",
        "responseTransformations": {
          "headerTransformations": {
            <valid-header-transformation-response-policy>
          }
        }
      }
    }
  },
  "routes": [
    ...
  ]
}
```
  dove:
  - responseCode: specifica un codice di stato HTTP alternativo. Ad esempio, 500.
  - responseMessage: (facoltativamente) specifica un corpo del messaggio. Ad esempio, Unfortunately, authentication failed. Il corpo del messaggio può includere qualsiasi variabile di contesto (ad eccezione di request.body).
  - responseTransformations: (facoltativamente) modifica le intestazioni della risposta restituita dal gateway API al client API specificando un criterio di risposta di trasformazione dell'intestazione. Per ulteriori informazioni sui criteri di trasformazione dell'intestazione, vedere Aggiunta di criteri di risposta di trasformazione dell'intestazione.
  Ad esempio:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        ...
      },
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "500",
        "responseMessage": "Unfortunately, authentication failed.",
      }
    }
  },
  "routes": [
    ...
  ]
}
```
Aggiungere un criterio di richiesta authorization per ogni instradamento nella specifica di distribuzione API:
1. Inserire una sezione requestPolicies dopo la sezione backend della prima route, se non esiste già. Ad esempio:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}
```
2. Aggiungere il seguente criterio authorization alla nuova sezione requestPolicies:
```
      "requestPolicies": {
        "authorization": {
          "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
          "allowedScope": [ "<scope>" ]
        }
      }
```
  dove:
  - "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS"> indica come concedere l'accesso al percorso:
    - "AUTHENTICATION_ONLY": concede l'accesso solo agli utenti finali che sono stati autenticati correttamente. In questo caso, la proprietà "isAnonymousAccessAllowed" nel criterio authentication della specifica di distribuzione API non ha alcun effetto.
    - "ANY_OF": concede l'accesso solo agli utenti finali che sono stati autenticati correttamente, purché la richiesta scope di JWT includa uno degli ambiti di accesso specificati nella proprietà allowedScope. In questo caso, la proprietà "isAnonymousAccessAllowed" nel criterio authentication della specifica di distribuzione API non ha alcun effetto.
    - "ANONYMOUS": concede l'accesso a tutti gli utenti finali, anche se non sono stati autenticati correttamente. In questo caso, è necessario impostare in modo esplicito la proprietà "isAnonymousAccessAllowed" su true nel criterio authentication della specifica di distribuzione API.
  - "allowedScope": [ "<scope>" ] è una lista delimitata da virgole di una o più stringhe che corrispondono agli ambiti di accesso inclusi nella richiesta scope di JWT. In questo caso, è necessario impostare la proprietà type su "ANY_OF" (la proprietà "allowedScope" viene ignorata se la proprietà type è impostata su "AUTHENTICATION_ONLY" o "ANONYMOUS"). Si noti inoltre che se si specificano più ambiti, l'accesso all'instradamento viene concesso se uno qualsiasi degli ambiti specificati è incluso nella richiesta scope di JWT.
  Ad esempio, il seguente criterio di richiesta definisce un instradamento /hello che consente solo agli utenti finali autenticati con l'ambito read:hello di accedervi:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "isAnonymousAccessAllowed": false,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "isSslVerifyDisabled": false,
        "maxCacheDurationInHours": 2,
        "additionalValidationPolicy": {
          "issuers": ["https://identity.oraclecloud.com/"],
          "audiences": ["api.dev.io"],
          "verifyClaims": [{
            "key": "is_admin",
            "values": ["service:app", "read:hello"],
            "isRequired": true
          }]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [ "read:hello" ]
        }
      }
    }
  ]
}
```
3. Aggiungere un criterio di richiesta authorization per tutti gli instradamenti rimanenti nella specifica di distribuzione API.
Nota

Se non si include un criterio authorization per un instradamento particolare, viene concesso l'accesso come se tale criterio esistesse e la proprietà type fosse impostata su "AUTHENTICATION_ONLY". In altre parole, indipendentemente dall'impostazione della proprietà isAnonymousAccessAllowed nel criterio authentication della specifica di distribuzione API:
- solo gli utenti finali autenticati possono accedere al percorso
- tutti gli utenti finali autenticati possono accedere all'instradamento indipendentemente dagli ambiti di accesso nella richiesta scope di JWT
- gli utenti finali anonimi non possono accedere al percorso
Salvare il file JSON contenente la specifica di distribuzione API.
Utilizzare la specifica di distribuzione API quando si crea o si aggiorna una distribuzione API nei modi riportati di seguito.
- specificando il file JSON nella console quando si seleziona l'opzione Carica un'interfaccia API esistente
- specificando il file JSON in una richiesta all'API REST del gateway API
Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.
(Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS

Il provider di identità che ha emesso il JWT determina i valori consentiti da specificare per le richieste dell'emittente (iss) e dell'audience (aud) nel JWT. Quale provider di identità ha emesso il JWT determina anche l'URI da cui recuperare il set di chiavi Web JSON (JWKS) per verificare la firma sul JWT.

Tenere presente che, indipendentemente dal provider di identità, un JWKS può contenere al massimo dieci chiavi.

Utilizzare la tabella riportata di seguito per scoprire cosa specificare per i JWT emessi dai provider di identità IAM OCI con domini di Identity, Oracle Identity Cloud Service (IDCS), Okta e Auth0.


Provider di identità	Richiesta emittente (`iss`)	Richiesta destinatari (`aud`)	Formato dell'URI dal quale recuperare JWKS
IAM OCI con i domini di identità	https://identity.oraclecloud.com	Specifiche del cliente. Fare riferimento alla sezione Gestione delle applicazioni nella documentazione di OCI IAM with Identity Domains.	https://<tenant-base-url>/admin/v1/SigningCert/jwk
IDCS	https://identity.oraclecloud.com/	Specifiche del cliente. Vedere la sezione relativa alla convalida dei token di accesso nella documentazione di Oracle Identity Cloud Service.	https://<tenant-base-url>/admin/v1/SigningCert/jwk Per ottenere JWKS senza eseguire il login a Oracle Identity Cloud Service, vedere Modifica impostazioni predefinite nella documentazione di Oracle Identity Cloud Service.
Okta	https://<your-okta-tenant-name>.com	Specifiche del cliente. L'audience configurata per il server di autorizzazione in Okta Developer Console. Vedere Convalida aggiuntiva per i token di accesso nella documentazione di Okta.	https://<your-okta-tenant-name>.com/oauth2/<auth-server-id> /v1/keys Consultare la documentazione di Okta.
Auth0	https://<nome-account-utente>.auth0.com/	Specifiche del cliente. Vedere Destinatari nella documentazione Auth0.	https://<nome-account-utente>.auth0.com/.well-known/jwks.json

Parametri chiave necessari per verificare le firme JWT

Per verificare la firma in un JWT, i gateway API richiedono la presenza dei seguenti parametri chiave nei JWKS restituiti da un URI o dalla chiave Web JSON statica specificata.


Parametro chiave	Note
`kid`	L'identificativo della chiave utilizzata per firmare il JWT. Il valore deve corrispondere alla richiesta `kid` nell'intestazione JWT. Ad esempio, `master_key`.
`kty`	Il tipo di chiave utilizzata per firmare il JWT. Si noti che RSA è attualmente l'unico tipo di chiave supportato.
`use` o `key_ops`	Se è presente il parametro `use`, è necessario impostarlo su `sig`. Se è presente il parametro `key-ops`, `verify` deve essere uno dei valori validi.
`n`	Il modulo della chiave pubblica.
`e`	L'esponente della chiave pubblica.
`alg`	L'algoritmo di firma (se presente) deve essere impostato su uno dei valori RS256, RS384 o RS512.

Uso di un criterio di richiesta di autenticazione JWT_AUTHENTICATION (non più consigliato)

Nota

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

Tenere presente che i criteri di richiesta JWT_AUTHENTICATION esistenti sono ancora supportati. Si noti inoltre che, sebbene sia possibile creare nuovi criteri di richiesta JWT_AUTHENTICATION definendo la specifica di distribuzione API in un file JSON (come descritto nelle istruzioni originali in questa sezione), si consiglia di creare invece criteri di richiesta di autenticazione di tipo TOKEN_AUTHENTICATION.

Quando si utilizza un criterio di richiesta di autenticazione di tipo JWT_AUTHENTICATION, prima che un utente finale possa accedere a una distribuzione API che utilizza JWT per l'autenticazione e l'autorizzazione, deve ottenere un JWT da un provider di identità.

Quando si richiama un'API distribuita in un gateway API, il client API fornisce il token JWT come parametro di query o nell'intestazione della richiesta. Il gateway API convalida il gateway JWT utilizzando una chiave di verifica pubblica corrispondente fornita dal provider di identità emittente. Utilizzando il criterio di richiesta di autenticazione JWT_AUTHENTICATION della distribuzione API, è possibile configurare la modalità di convalida dei JWT da parte del gateway API:

È possibile configurare il gateway API per recuperare le chiavi di verifica pubbliche dal provider di identità in runtime. In questo caso, il provider di identità funge da server di autorizzazione.
Puoi configurare il gateway API in anticipo con chiavi di verifica pubbliche già emesse da un provider di identità (definite 'chiavi statiche'), consentendo al gateway API di verificare i JWT a livello locale in fase di esecuzione senza dover contattare il provider di identità. Il risultato è una convalida del token più rapida.

Per aggiungere un nuovo criterio di richiesta di autenticazione e autorizzazione JWT_AUTHENTICATION a una specifica di distribuzione API in un file JSON, effettuare le operazioni riportate di seguito.

Aggiungere un criterio di richiesta authentication che si applica a tutti gli instradamenti nella specifica di distribuzione API:
1. Se non esiste già, inserire una sezione requestPolicies prima della sezione routes. Ad esempio:
```
{
  "requestPolicies": {},
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
2. Aggiungere il seguente criterio authentication alla nuova sezione requestPolicies.
```
{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": <true|false>,
      "issuers": ["<issuer-url>", "<issuer-url>"],
      <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">,
      "tokenAuthScheme": "<authentication-scheme>",
      "audiences": ["<intended-audience>"],
      "publicKeys": {
        "type": <"REMOTE_JWKS"|"STATIC_KEYS">,
        <public-key-config>
      },
      "verifyClaims": [
        {"key": "<claim-name>",
         "values": ["<acceptable-value>", "<acceptable-value>"],
         "isRequired": <true|false>
        }
      ],
      "maxClockSkewInSeconds": <seconds-difference>
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```
  dove:
  - "isAnonymousAccessAllowed": <true|false> indica facoltativamente se gli utenti finali non autenticati (ovvero anonimi) possono accedere agli instradamenti nella specifica di distribuzione API. Se non si desidera che gli utenti finali anonimi possano accedere ai percorsi, impostare questa proprietà su false. Se non si include questa proprietà nel criterio authentication, viene utilizzato il valore predefinito false. Tenere presente che se si include questa proprietà e la si imposta su true, è inoltre necessario specificare in modo esplicito ogni instradamento per il quale è consentito l'accesso anonimo impostando la proprietà type su "ANONYMOUS" nel criterio authorization di ogni instradamento.
  - <issuer-url> è l'URL (o una stringa di testo) per un provider di identità consentito nella richiesta emittente (iss) di un JWT da utilizzare per accedere alla distribuzione API. Ad esempio, per abilitare un JWT emesso da IAM OCI con i domini di Identity da utilizzare per accedere alla distribuzione API, immettere https://identity.oraclecloud.com/ . È possibile specificare uno o più provider di identità (fino a un massimo di cinque). Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> indica se si tratta di un'intestazione di richiesta che contiene il JWT (e, in caso affermativo, il nome dell'intestazione) o di un parametro di query che contiene il JWT (e, in caso affermativo, il nome del parametro di query). Si noti che è possibile specificare "tokenHeader": "<token-header-name>" o "tokenQueryParam": "<token-query-param-name>">, ma non entrambi.
  - <tokenAuthScheme> è il nome dello schema di autenticazione da utilizzare se il JWT è contenuto nell'intestazione di una richiesta. Ad esempio, "Bearer".
  - <intended-audience> è un valore consentito nella richiesta di audience (aud) di un JWT per identificare il destinatario previsto del token. Ad esempio, l'audience potrebbe essere, ma non deve essere, il nome host del gateway API. È possibile specificare una o più audience (fino a un massimo di cinque). Vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS.
  - "type": <"REMOTE_JWKS"|"STATIC_KEYS"> indica la modalità con cui si desidera che il gateway API convalidi JWT utilizzando chiavi di verifica pubbliche. Specificare REMOTE_JWKS per configurare il gateway API per recuperare fino a dieci chiavi di verifica pubbliche dal provider di identità in runtime. Specificare STATIC_KEYS per configurare il gateway API con un massimo di dieci chiavi di verifica pubbliche già emesse da un provider di identità (abilitando il gateway API per verificare i gateway API localmente senza dover contattare il provider di identità).
  - <public-key-config> fornisce i dettagli della convalida JWT, in base al fatto che sia stato specificato "REMOTE_JWKS" o "STATIC_KEYS" come valore di "type": come indicato di seguito.
    - Se è stato specificato "type": "REMOTE_JWKS" per configurare il gateway API per convalidare i JWT recuperando le chiavi di verifica pubbliche dal provider di identità in runtime, fornire i dettagli come indicato di seguito.
      "publicKeys": { "type": "REMOTE_JWKS", "uri": "<uri-for-jwks>", "maxCacheDurationInHours": <cache-time>, "isSslVerifyDisabled": <true|false> }
      dove:
      - "uri": "<uri-for-jwks>" specifica l'URI da cui recuperare il set di chiavi Web JSON (JWKS) da utilizzare per verificare la firma sui JWT. Per ulteriori informazioni sull'URI da specificare, vedere Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS. Nota:
        
        L'URI deve essere instradabile dalla subnet contenente il gateway API su cui viene distribuita l'API.
        
        Se il gateway API non riesce a recuperare JWKS, tutte le richieste alla distribuzione API restituiranno un codice di risposta HTTP 500. Per ulteriori informazioni sull'errore, fare riferimento al log di esecuzione del gateway API (vedere Aggiunta di log alle distribuzioni API).
        
        Alcuni parametri chiave devono essere presenti in JWKS per verificare la firma del JWT (vedere Parametri chiave necessari per verificare le firme JWT).
        
        JWKS può contenere fino a dieci chiavi.
      - "maxCacheDurationInHours": <cache-time> specifica il numero di ore (tra 1 e 24) in cui il gateway API deve inserire il JWKS nella cache dopo averlo recuperato.
      - "isSslVerifyDisabled": <true|false> indica se disabilitare la verifica SSL durante la comunicazione con il provider di identità. Oracle consiglia di non impostare questa opzione su true perché può compromettere la convalida JWT. API Gateway considera attendibili i certificati di più autorità di certificazione emessi per IAM OCI con domini di Identity, Oracle Identity Cloud Service (IDCS), Auth0 e Okta.
      Ad esempio:
      "publicKeys": { "type": "REMOTE_JWKS", "uri": "https://www.somejwksprovider.com/oauth2/v3/certs", "maxCacheDurationInHours": 3, "isSslVerifyDisabled": false }
    - Se è stata specificata la funzione "type": "STATIC_KEYS", i dettagli da fornire dipendono dal formato della chiave già emessa dal provider di identità (indipendentemente dal formato, è possibile specificare fino a dieci chiavi):
      - Se la chiave statica è una chiave Web JSON, specificare "format": "JSON_WEB_KEY", specificare l'identificativo della chiave statica utilizzata per firmare il JWT come valore del parametro "kid" e fornire i valori per altri parametri per verificare la firma del JWT.
        
        Ad esempio:
        
        "publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "JSON_WEB_KEY", "kid": "master_key", "kty": "RSA", "n": "0vx7agoebGc...KnqDKgw", "e": "AQAB", "alg": "RS256", "use": "sig" } ]
        
        Tenere presente che alcuni parametri devono essere presenti nella chiave statica per verificare la firma del JWT (vedere Parametri chiave necessari per verificare le firme JWT). Inoltre, si noti che RSA è attualmente l'unico tipo di chiave supportato (kty).
      - Se la chiave statica è una chiave pubblica con codifica PEM, specificare "format": "PEM", specificare l'identificativo della chiave statica utilizzata per firmare il JWT come valore di "kid" e fornire la chiave come valore di "key".
        
        Ad esempio:
        
        "publicKeys": { "type": "STATIC_KEYS", "keys": [ { "format": "PEM", "kid": "master_key" "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY----- } ]
        
        Si noti che gli indicatori -----BEGIN PUBLIC KEY----- e -----END PUBLIC KEY----- sono obbligatori.
  - verifyClaims specifica facoltativamente nomi e valori aggiuntivi per una o più richieste aggiuntive da convalidare in un JWT (fino a un massimo di dieci).
    - "key": "<claim-name>" è il nome di una richiesta che può essere o deve essere inclusa in un JWT. Il nome della richiesta specificato può essere un nome di richiesta riservato, ad esempio la richiesta oggetto (sub) o un nome di richiesta personalizzato emesso da un determinato provider di identità.
    - "values": ["<acceptable-value>", "<acceptable-value>"] (facoltativamente) indica uno o più valori accettabili per la richiesta.
    - "isRequired": <true|false> indica se il sinistro deve essere incluso nel JWT.
    Tenere presente che i nomi e i valori delle chiavi immessi vengono gestiti semplicemente come stringhe e devono corrispondere esattamente ai nomi e ai valori nel JWT. Corrispondenza pattern e altri tipi di dati non supportati
  - maxClockSkewInSeconds: <seconds-difference> specifica facoltativamente la differenza di tempo massima tra i clock di sistema del provider di identità che ha emesso un JWT e il gateway API. Il valore specificato viene preso in considerazione quando il gateway API convalida il JWT per determinare se è ancora valido, utilizzando la richiesta not before (nbf) (se presente) e la richiesta di scadenza (exp) nel JWT. Il valore minimo (e predefinito) è 0, il valore massimo è 120.
  Ad esempio, il seguente criterio authentication configura il gateway API con una chiave di verifica pubblica già emessa da un provider di identità per convalidare il JWT nell'intestazione della richiesta di autorizzazione:
```
{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    }
  ]
}
```

Aggiungere un criterio di richiesta authorization per ogni instradamento nella specifica di distribuzione API:

Inserire una sezione requestPolicies dopo la sezione backend della prima route, se non esiste già. Ad esempio:

{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
         "type": "ORACLE_FUNCTIONS_BACKEND",
         "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {}
    }
  ]
}

Aggiungere il seguente criterio authorization alla sezione requestPolicies:

{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
          "allowedScope": [ "<scope>" ]
        }
      }
    }
  ]
}

dove:

"type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS"> indica come concedere l'accesso al percorso:
- "AUTHENTICATION_ONLY": concede l'accesso solo agli utenti finali che sono stati autenticati correttamente. In questo caso, la proprietà "isAnonymousAccessAllowed" nel criterio authentication della specifica di distribuzione API non ha alcun effetto.
- "ANY_OF": concede l'accesso solo agli utenti finali che sono stati autenticati correttamente, purché la richiesta scope di JWT includa uno degli ambiti di accesso specificati nella proprietà allowedScope. In questo caso, la proprietà "isAnonymousAccessAllowed" nel criterio authentication della specifica di distribuzione API non ha alcun effetto.
- "ANONYMOUS": concede l'accesso a tutti gli utenti finali, anche se non sono stati autenticati correttamente. In questo caso, è necessario impostare in modo esplicito la proprietà "isAnonymousAccessAllowed" su true nel criterio authentication della specifica di distribuzione API.
"allowedScope": [ "<scope>" ] è una lista delimitata da virgole di una o più stringhe che corrispondono agli ambiti di accesso inclusi nella richiesta scope di JWT. In questo caso, è necessario impostare la proprietà type su "ANY_OF" (la proprietà "allowedScope" viene ignorata se la proprietà type è impostata su "AUTHENTICATION_ONLY" o "ANONYMOUS"). Si noti inoltre che se si specificano più ambiti, l'accesso all'instradamento viene concesso se uno qualsiasi degli ambiti specificati è incluso nella richiesta scope di JWT.

Ad esempio, il seguente criterio di richiesta definisce un instradamento /hello che consente solo agli utenti finali autenticati con l'ambito read:hello di accedervi:

{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [ "read:hello" ]
        }
      }
    }
  ]
}

Aggiungere un criterio di richiesta authorization per tutti gli instradamenti rimanenti nella specifica di distribuzione API.

Nota

Se non si include un criterio authorization per un instradamento particolare, viene concesso l'accesso come se tale criterio esistesse e la proprietà type fosse impostata su "AUTHENTICATION_ONLY". In altre parole, indipendentemente dall'impostazione della proprietà isAnonymousAccessAllowed nel criterio authentication della specifica di distribuzione API:

solo gli utenti finali autenticati possono accedere al percorso
tutti gli utenti finali autenticati possono accedere all'instradamento indipendentemente dagli ambiti di accesso nella richiesta scope di JWT
gli utenti finali anonimi non possono accedere al percorso

Salvare il file JSON contenente la specifica di distribuzione API.
Utilizzare la specifica di distribuzione API quando si crea o si aggiorna una distribuzione API nei modi riportati di seguito.
- specificando il file JSON nella console quando si seleziona l'opzione Carica un'interfaccia API esistente
- specificando il file JSON in una richiesta all'API REST del gateway API
Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.
(Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Esempio: migrazione di un criterio di richiesta JWT_AUTHENTICATION a un criterio di richiesta TOKEN_AUTHENTICATION

Questa sezione mostra un esempio di criterio di richiesta JWT_AUTHENTICATION esistente migrato a un criterio TOKEN_AUTHENTICATION.

Un modo per avvicinarsi alla migrazione consiste nel creare un criterio di richiesta TOKEN_AUTHENTICATION vuoto, quindi popolarlo con i valori del criterio di richiesta JWT_AUTHENTICATION

Prima della migrazione:

Il criterio di richiesta JWT_AUTHENTICATION originale, prima della migrazione:

{
  "requestPolicies": {
    "authentication": {
      "type": "JWT_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "issuers": ["https://identity.oraclecloud.com/"],
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "audiences": ["api.dev.io"],
      "publicKeys": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]
      },
      "verifyClaims": [
        {
          "key": "is_admin",
          "values": ["service:app", "read:hello"],
          "isRequired": true
        }
      ],
      "maxClockSkewInSeconds": 10
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [ "read:hello" ]
        }
      }
    }
  ]
}

Dopo la migrazione:

Il nuovo criterio di richiesta TOKEN_AUTHENTICATION popolato con i valori del criterio di richiesta JWT_AUTHENTICATION originale:

{
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      "isAnonymousAccessAllowed": false,
      "tokenHeader": "Authorization",
      "tokenAuthScheme": "Bearer",
      "maxClockSkewInSeconds": 10,
      "validationPolicy": {
        "type": "STATIC_KEYS",
        "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ],
        "additionalValidationPolicy": {
          "audiences": [
            "api.dev.io"
          ],
          "verifyClaims": [
            {
              "key": "is_admin",
              "values": [
                "service:app",
                "read:hello"
              ],
              "isRequired": true
            }
          ],
          "issuers": [
            "https://identity.oraclecloud.com/"
          ]
        }
      }
    }
  },
  "routes": [
    {
      "path": "/hello",
      "methods": [
        "GET"
      ],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANY_OF",
          "allowedScope": [
            "read:hello"
          ]
        }
      }
    }
  ]
}

Documentazione di Oracle Cloud Infrastructure

Convalida dei token per aggiungere autenticazione e autorizzazione alle distribuzioni API

Che cosa accade durante l'autenticazione del token?

Note sui token Web JSON (JWT)

Note su OAuth 2.0 e OpenID Connect

Note sulla protezione CSRF (Cross-Site Request Forgery)

Note sull'uso dei criteri di richiesta JWT_AUTHENTICATION

Prerequisiti per l'autenticazione token

Uso della console per aggiungere criteri di autenticazione token e richiesta di autorizzazione

Modifica di un file JSON per aggiungere criteri di autenticazione token e richiesta di autorizzazione

Dettagli provider di identità da utilizzare per l'emissione e l'audit delle richieste e per l'URI JWKS

Parametri chiave necessari per verificare le firme JWT

Uso di un criterio di richiesta di autenticazione JWT_AUTHENTICATION (non più consigliato)

Esempio: migrazione di un criterio di richiesta JWT_AUTHENTICATION a un criterio di richiesta TOKEN_AUTHENTICATION

Prima della migrazione:

Dopo la migrazione: