Documentazione dell'infrastruttura Oracle Cloud

Utilizzo della console per aggiungere i criteri di richiesta di autenticazione e autorizzazione del token

Aggiungere criteri di richiesta di autenticazione e autorizzazione a una specifica di distribuzione API utilizzando la console.

  1. Creare o aggiornare una distribuzione API utilizzando la console, selezionare l'opzione Crea distribuzione 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.

  2. Selezionare Successivo per visualizzare la pagina Autenticazione.

  3. Selezionare Autenticazione singola per specificare che si desidera utilizzare un unico server di autenticazione per tutte le richieste.

    Queste istruzioni presuppongono l'utilizzo di un singolo server di autenticazione. In alternativa, se si desidera utilizzare più server di autenticazione, selezionare Multi-Authentication e seguire le istruzioni riportate in Uso della console per aggiungere più server di autenticazione alla stessa distribuzione API.

  4. Selezionare o deselezionare 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 gli utenti anonimi possano accedere agli instradamenti, non selezionare questa opzione. Tenere presente che se si seleziona questa opzione, è inoltre necessario specificare in modo esplicito ogni instradamento a cui è consentito l'accesso anonimo selezionando Anonimo come Tipo di autorizzazione nel criterio di autorizzazione di ciascun instradamento.

  5. Selezionare Autenticazione token dall'elenco 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 (attualmente è supportato solo Bearer).
      • Nome parametro token: se i token sono contenuti in un parametro di query, immettere il nome del parametro di query.
  6. Specificare le modalità con cui 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 Endpoint di introspezione OAuth 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 dei token.
      • Vault: il nome di un vault nel servizio Vault che contiene il segreto client da inviare all'endpoint di introspezione, dalla lista di vault nel compartimento specificato. Per ottenere un segreto client, creare e registrare un'applicazione client con il server di autorizzazione. Vedere Prerequisiti per l'autenticazione dei token.
      • Segreto del vault in <nome compartimento>: il nome di un segreto vault che contiene il segreto client da inviare all'endpoint di introspezione, dalla lista di segreti vault nel compartimento specificato.
      • Numero di versione del segreto vault: la versione del segreto vault che contiene il segreto client da inviare all'endpoint di introspezione.
      • URL di ricerca automatica: l'URL noto del 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.

      • Durata massima della cache in ore: il numero di ore (tra 1 e 24) in cui il gateway API memorizza nella cache la risposta dall'endpoint di introspezione.
      • Skew clock massimo in secondi: (facoltativo) la differenza di tempo massima 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 non prima (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. Il gateway API considera sicuri i certificati di più autorità di certificazione emesse 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 remoto dalla lista Tipo e specificare:

      • URI JWKS: URI da cui recuperare il set di chiavi Web JSON (JWKS) da utilizzare per verificare la firma sui 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.

        Tenere presente quanto riportato di seguito.

        • 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 di JWT (vedere Parametri chiave necessari per verificare le firme JWT).
        • Il 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 deve inserire nella cache JWKS dopo averlo recuperato.
      • Skew clock massimo in secondi: (facoltativo) la differenza di tempo massima 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 non prima (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 provider di identità. Per impostazione predefinita, questa opzione non è selezionata. Oracle consiglia di non selezionare questa opzione perché può compromettere la convalida JWT. Il gateway API considera sicuri i certificati di più autorità di certificazione emesse 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 protocollo JWT. Il valore deve corrispondere alla richiesta kid nell'intestazione JWT. Ad esempio, master_key.

      • Formato chiave: il formato della chiave statica, ovvero una chiave Web JSON o una chiave pubblica con codifica PEM.

        • Tasto 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"
}

          Si noti che alcuni parametri devono essere presenti nella chiave statica per verificare la firma di JWT (vedere Parametri chiave necessari per verificare le firme JWT). Si noti inoltre 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.

      • Altra chiave: selezionare questa opzione per aggiungere ulteriori chiavi (fino a un massimo di dieci).
  7. (Facoltativo) Specificare ulteriori dettagli per la convalida del token JWT:

    1. Nella sezione Problemi specificare i valori consentiti nella richiesta dell'istituto di emissione (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à che è consentito nella richiesta dell'emittente (iss) di un JWT da utilizzare per accedere alla distribuzione dell'API. Ad esempio, per abilitare un JWT emesso da IAM OCI con 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.
      • Altro emittente: selezionare questa opzione per aggiungere altri provider di identità (fino a un massimo di cinque).

    2. Nella sezione Audience specificare i valori consentiti nella dichiarazione dell'audience (aud) di un JWT utilizzato per accedere alla distribuzione dell'API.

    3. Convalida delle richieste: (facoltativo) oltre ai valori per le richieste di audience aud e iss dell'emittente già specificate, è possibile specificare i nomi e i valori per una o più richieste di risarcimento aggiuntive da convalidare in un JWT. Si noti che i nomi e i valori delle chiavi immessi vengono semplicemente gestiti 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: specificare se la richiesta nel campo Chiave richiesta deve essere inclusa nella dichiarazione JWT.
      • Chiave di richiesta: (facoltativo) specificare il nome di una richiesta che può essere o deve essere inclusa in una richiesta JWT. Se la richiesta deve essere inclusa nella transazione JWT, selezionare Obbligatorio. Il nome di richiesta specificato può essere un nome di richiesta riservato, ad esempio l'oggetto (sub) o un nome di richiesta personalizzato emesso da un determinato provider di identità.
      • Valori richiesta: (facoltativo) specificare un valore accettabile per la richiesta nel campo Chiave richiesta. Selezionare il 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 una richiesta in un JWT senza specificarne un valore. A tale scopo, immettere il nome del risarcimento nel campo Chiave di sinistro, lasciare vuoto il campo Valori di sinistro e impostare Richiesta di risarcimento obbligatoria a seconda dei casi.

  8. Specificare il modo in cui 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. Si noti che questa opzione è disponibile solo se è stato selezionato Endpoint di introspezione OAuth 2.0 dalla lista Tipo di convalida in precedenza. Specificare:

      • Scopi: 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 ambito. Ad esempio, openid, email:read, profile.
      • Tipo di risposta: il tipo di risposta richiesto dal flusso di autorizzazione. Inserire code come tipo di risposta.
      • Percorso di reindirizzamento di fallback: (facoltativo) un percorso relativo nella distribuzione API corrente al quale 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) un percorso relativo a un backend di logout nella distribuzione API corrente. Il percorso specificato deve corrispondere al percorso di instradamento definito per il backend di logout. Ad esempio, /revoke

        Un client API può richiamare il backend di logout per revocare i token. Una chiamata al backend di logout può includere un URL di post-logout come parametro di query denominato postLogoutUrl. Vedere Aggiunta del logout come backend di API Gateway.

      • 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: il nome di un vault nel servizio Vault che contiene il segreto client da inviare all'endpoint di introspezione, dalla lista di vault nel compartimento specificato.
        • Segreto del vault: il nome del segreto del vault che contiene il segreto client da inviare all'endpoint di introspezione, dalla lista dei segreti del vault nel compartimento specificato.
        • Numero di versione del segreto vault: la versione del segreto vault che contiene 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 Opzioni avanzate e selezionando:

      • Usa PKCE: (facoltativo) specificare se utilizzare PKCE (Chiave di prova per lo scambio di codice) per una maggiore sicurezza. PKCE è un'estensione di sicurezza OAuth 2.0 per prevenire gli attacchi CSRF (Cross-Site Request Forgery) e il codice di autorizzazione. PKCE non sostituisce un segreto client e PKCE è consigliato anche se viene utilizzato un segreto client. Per ulteriori informazioni su PKCE, consultare la documentazione di OAuth 2.0.
      • Usa 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 (ad eccezione delle richieste GET) devono includere il TOKEN CSRF in un'intestazione di richiesta X-CSRF-TOKEN, oltre al TOKEN JWT nel cookie di sessione che viene incluso automaticamente.
        • Non selezionare questa opzione se non si desidera memorizzare il nuovo token JWT in un cookie di sessione. Il gateway API restituisce invece 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.

        Vedi 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 di richiesta). Selezionare questa opzione per memorizzare i valori nei cookie del browser. Deselezionare questa opzione per memorizzare i valori con il gateway API.
    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) da restituire al client API:
      • Codice di stato HTTP: immettere un codice di stato HTTP alternativo. Ad esempio, 500.
      • Corpo del messaggio: immettere un corpo del 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 che il gateway API restituisce al client API specificando un criterio di risposta per la trasformazione dell'intestazione. Per ulteriori informazioni sui criteri di trasformazione delle intestazioni, vedere Aggiunta di criteri di risposta per la trasformazione delle intestazioni.

  9. Selezionare Successivo per immettere i dettagli dei singoli instradamenti nella distribuzione API nella pagina Cicli.

  10. Selezionare Aggiungi instradamento e specificare il primo instradamento nella distribuzione API che mappa un percorso e uno o più metodi a un servizio backend:

    • Percorso: percorso per le chiamate API che utilizzano i metodi elencati per il servizio backend. Tenere presente che il percorso di instradamento specificato:

      • è relativo al prefisso del percorso di distribuzione
      • deve essere preceduta da una barra ( / ), e può essere solo quella singola barra
      • può contenere più barre (a condizione che non siano adiacenti) e può terminare con una barra
      • 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.

    • Aggiungi un singolo backend o Aggiungi più backend: consente di instradare tutte le richieste allo stesso backend o di instradarle a backend diversi in base alla variabile di contesto e alle regole immesse.

      Queste istruzioni presuppongono l'utilizzo di un singolo backend, pertanto selezionare Aggiungi un singolo backend. In alternativa, se si desidera utilizzare backend diversi, selezionare Aggiungi backend multipli e seguire le istruzioni riportate in Utilizzo della console per aggiungere la selezione backend dinamico a una specifica di distribuzione API.

    • Tipo di backend: il tipo del servizio backend, come uno dei seguenti:

  11. Per specificare un criterio di autorizzazione che si applica a un singolo instradamento, selezionare Mostra criteri richiesta instradamento, selezionare il pulsante Aggiungi accanto a Autorizzazione e specificare quanto segue.

    • Tipo di autorizzazione: modalità di concessione dell'accesso all'instradamento. Specificare:

      • Qualsiasi: concede l'accesso solo agli utenti finali che sono stati autenticati correttamente, a condizione che 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: concedere l'accesso a tutti gli utenti finali, anche se non sono stati autenticati correttamente utilizzando JWT. In questo caso, è necessario aver selezionato l'opzione Abilita accesso anonimo del criterio di autenticazione.
      • Solo autenticazione: consente l'accesso solo agli utenti finali che sono stati autenticati correttamente utilizzando 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 JWT dispone di una richiesta di rimborso 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 specifico, l'accesso viene concesso come se tale criterio esistesse e Tipo di autorizzazione è impostato 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 all'instradamento
  12. Selezionare Crea, quindi Successivo per esaminare i dettagli immessi per la distribuzione API.
  13. Selezionare Crea o Aggiorna per creare o aggiornare la distribuzione API.
  14. (Facoltativo) Confermare che l'interfaccia API è stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita su un gateway API).