Aggiunta di criteri di richiesta di autenticazione e autorizzazione per i token di accesso a argomenti singoli e le funzioni del responsabile autorizzazioni

Per aggiungere criteri di richiesta di autenticazione e autorizzazione per i token di accesso a un argomento singolo a una specifica di distribuzione API utilizzando la console, effettuare le operazioni riportate di seguito.

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 Funzione autore dall'elenco di opzioni Tipo di autenticazione.
6. Specificare la funzione del responsabile autorizzazioni a argomento singolo da utilizzare per autenticare il token di accesso a argomento singolo:
   • Applicazione Oracle Functions: il nome dell'applicazione nelle funzioni OCI che contiene la funzione di responsabile autorizzazione. È possibile selezionare un'applicazione da un compartimento diverso.
   • Nome funzione: il nome della funzione del responsabile autorizzazioni nelle funzioni OCI.
7. Selezionare Funzione del responsabile autorizzazioni a argomento singolo per specificare che si desidera passare un token di accesso a argomento singolo in un'intestazione o un parametro di query a una funzione del responsabile autorizzazioni a argomento singolo.
8. Nel pannello Token di accesso, identificare il token di accesso da utilizzare per l'autenticazione.
   • Posizione token: selezionare Intestazione o Parametro query per specificare la posizione del token di accesso nella richiesta.
   • Nome intestazione token o Nome parametro token: a seconda della posizione del token di accesso, immettere il nome del parametro di intestazione o query contenente il token di accesso.

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.

    • Aggiungere un singolo backend o Aggiungere più backend: indica se instradare tutte le richieste allo stesso backend o 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:
      • HTTP: per un backend HTTP, è inoltre necessario specificare un URL, i dettagli relativi al 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, è inoltre necessario specificare l'applicazione e la funzione (vedere Aggiunta di una funzione nelle funzioni OCI come backend API Gateway).
      • Risposta stock: per un back-end di risposta stock, è inoltre necessario specificare il codice di stato HTTP, il contenuto nel corpo della risposta e uno o più campi di intestazione HTTP (vedere Aggiunta di risposte stock come back-end di API Gateway).
      • Logout: per un backend di logout, è inoltre necessario specificare una lista di URL consentiti a cui è possibile reindirizzare una richiesta per revocare i token e, facoltativamente, i dati da passare all'URL di logout (vedere Aggiunta del logout come backend di API Gateway).

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: concedere l'accesso solo agli utenti finali che sono stati autenticati correttamente, a condizione che la funzione del responsabile autorizzazioni abbia restituito anche uno degli ambiti di accesso specificati nel campo Aggiungi 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 dalla funzione del responsabile autorizzazioni. 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 dalla funzione del responsabile autorizzazioni. In questo caso, l'opzione Abilita accesso anonimo del criterio di autenticazione non ha alcun effetto.
    • Aggiungi 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 restituiti dalla funzione del responsabile autorizzazioni. L'accesso verrà concesso solo agli utenti finali che sono stati autenticati correttamente se la funzione del responsabile autorizzazioni restituisce 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 il 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 restituiti dalla funzione del responsabile autorizzazioni
    • 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).

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

1. Utilizzando l'editor JSON preferito, modificare la specifica di distribuzione API esistente a cui 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 dell'API includerà almeno una sezione routes contenente:

   • Un percorso. Ad esempio, /hello
   • Uno o più metodi. Ad esempio, GET
   • Una definizione di back end. Ad esempio, un URL o l'OCID di una funzione in OCI Functions.

   Ad esempio, la seguente specifica di distribuzione API di base definisce una semplice funzione serverless Hello World in OCI Functions come un singolo back end:

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

2. Aggiungere un criterio di richiesta authentication che si applichi a tutti gli instradamenti nella specifica di distribuzione API:

   1. Inserire una sezione requestPolicies prima della sezione routes, se non esiste già. 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": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "functionId": "<function-ocid>",
            <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      dove:

      • <type-value> è il tipo diautenticazione. Per utilizzare una funzione del responsabile autorizzazioni per l'autenticazione, specificare CUSTOM_AUTHENTICATION.
      • "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 agli instradamenti, 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 a cui è consentito l'accesso anonimo impostando la proprietà type su "ANONYMOUS" nel criterio authorization di ciascun instradamento.
      • <function-ocid> è l'OCID della funzione del responsabile autorizzazioni distribuita in OCI Functions.
      • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> indica se si tratta di un'intestazione di richiesta che contiene il token di accesso (e, in tal caso, il nome dell'intestazione) o un parametro di query che contiene il token di accesso (e, in tal caso, 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, il seguente criterio authentication specifica una funzione OCI che convaliderà il token di accesso nell'intestazione della richiesta di autorizzazione:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

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

   1. Inserire una sezione requestPolicies dopo la sezione backend del primo instradamento, se non ne esiste già una. Ad esempio:

      
      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "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 sezione requestPolicies:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "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 all'instradamento:

        • "AUTHENTICATION_ONLY": consente l'accesso solo agli utenti finali autenticati correttamente. In questo caso, la proprietà "isAnonymousAccessAllowed" nel criterio authentication della specifica di distribuzione API non ha alcun effetto.
        • "ANY_OF": consente l'accesso solo agli utenti finali autenticati correttamente, purché la funzione del responsabile autorizzazioni abbia restituito anche 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": concedere 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 restituiti dalla funzione del responsabile autorizzazioni. 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 la funzione del responsabile autorizzazioni restituisce uno qualsiasi degli ambiti specificati.

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

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "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 determinato instradamento, l'accesso viene concesso come se tale criterio esistesse e la proprietà type è 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 restituiti dalla funzione del responsabile autorizzazioni
   • gli utenti finali anonimi non possono accedere all'instradamento
4. Salvare il file JSON contenente la specifica di distribuzione API.

5. 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'API di distribuzione 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.

6. (Facoltativo) Confermare che l'interfaccia API è stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita su un gateway API).