Documentazione dell'infrastruttura Oracle Cloud

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

Aggiungere criteri di richiesta di autenticazione e autorizzazione a una specifica di distribuzione API in un file JSON.

  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. Inserire una sezione requestPolicies prima della sezione routes (se non esiste già) per creare un criterio di richiesta authentication che si applichi 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"
      }
    }
  ]
}

  3. 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 tal caso, il nome dell'intestazione) o un parametro di query che contiene il token (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, "tokenHeader": "Authorization"
    • <tokenAuthScheme> è il nome dello schema di autenticazione da utilizzare se il token è contenuto in un'intestazione di 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 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.
    • 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 il claim non prima (nbf) (se presente) e il claim 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 convalidare i token, come descritto nei passi riportati di seguito.
  4. 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 criterio di convalida seguente 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 l'endpoint di introspezione di un 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 dei token.
      • "clientSecretId": "<secret-ocid>" specifica l'OCID del segreto del vault che contiene 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 contenente 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 quando si comunica con il server di autorizzazione. Oracle consiglia di non impostare questa opzione su true 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.
    • "maxCacheDurationInHours": <cache-time> specifica il numero di ore (tra 1 e 24) in cui il gateway API deve memorizzare 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 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, 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 dell'audience (aud) di un JWT per identificare il destinatario previsto del token. Ad esempio, il pubblico potrebbe essere, ma non necessariamente, il nome host del gateway API. È possibile specificare uno 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 di risarcimento aggiuntive da convalidare in un JWT (fino a un massimo di dieci):
        • "key": "<claim-name>" è il nome di una richiesta che può essere inclusa o deve essere inclusa in una dichiarazione congiunta. 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 server di autorizzazione.
        • "values": ["<acceptable-value>", "<acceptable-value>"] (facoltativo) indica uno o più valori accettabili per la richiesta.
        • "isRequired": <true|false> indica se la richiesta deve essere inclusa nel 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. Corrispondenza pattern e altri tipi di dati non supportati

    Ad esempio, il criterio authentication riportato di seguito 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) passate 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"
      }
    }
  ]
}

  5. Se si desidera che il gateway API convalidi i JWT recuperando le chiavi di verifica pubbliche dal provider di identità in runtime, aggiungere il criterio di convalida seguente 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. 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.
    • "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. 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.
    • "maxCacheDurationInHours": <cache-time> specifica il numero di ore (tra 1 e 24) in cui il gateway API deve inserire nella cache JWKS dopo il recupero.
    • "additionalValidationPolicy": {"issuers": ...} specifica dettagli aggiuntivi per la convalida del token:
      • <issuer-url> è 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/ . È 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 dell'audience (aud) di un JWT per identificare il destinatario previsto del token. Ad esempio, il pubblico potrebbe essere, ma non necessariamente, il nome host del gateway API. È possibile specificare uno 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 di risarcimento aggiuntive da convalidare in un JWT (fino a un massimo di dieci).
        • "key": "<claim-name>" è il nome di una richiesta che può essere inclusa o deve essere inclusa in una dichiarazione congiunta. 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à.
        • "values": ["<acceptable-value>", "<acceptable-value>"] (facoltativo) indica uno o più valori accettabili per la richiesta.
        • "isRequired": <true|false> indica se la richiesta deve essere inclusa nel 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. Corrispondenza pattern e altri tipi di dati non supportati

    Ad esempio, il seguente criterio authentication configura il gateway API per convalidare il 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"
      }
    }
  ]
}

  6. 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à), aggiungere il seguente criterio di convalida alla sezione validationPolicy vuota:

          "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 in locale senza dover contattare il provider di identità).
    • "keys": [{<key-config>}] specifica l'identificativo della chiave statica utilizzata per firmare la 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"
          }
        ]

        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).

      • Se la chiave statica è una chiave pubblica con codifica PEM, specificare "format": "PEM", specificare l'identificativo della chiave statica utilizzata per firmare JWT come valore "kid" e fornire la chiave come valore "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. 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.
    • "maxCacheDurationInHours": <cache-time> specifica il numero di ore (tra 1 e 24) in cui il gateway API deve inserire nella cache JWKS dopo il recupero.
    • "additionalValidationPolicy": {"issuers": ...} specifica dettagli aggiuntivi per la convalida del token:
      • <issuer-url> è 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/ . È 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 dell'audience (aud) di un JWT per identificare il destinatario previsto del token. Ad esempio, il pubblico potrebbe essere, ma non necessariamente, il nome host del gateway API. È possibile specificare uno 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 di risarcimento aggiuntive da convalidare in un JWT (fino a un massimo di dieci).
        • "key": "<claim-name>" è il nome di una richiesta che può essere inclusa o deve essere inclusa in una dichiarazione congiunta. 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à.
        • "values": ["<acceptable-value>", "<acceptable-value>"] (facoltativo) indica uno o più valori accettabili per la richiesta.
        • "isRequired": <true|false> indica se la richiesta deve essere inclusa nel 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. 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"
      }
    }
  ]
}
  7. (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 in precedenza è stato specificato un valore validationPolicy di tipo REMOTE_DISCOVERY. 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 ambito. Ad esempio, "scopes": ["openid", "email:read", "profile"]
      • clientDetails": {...} specifica i dettagli 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 i dettagli client uguali o diversi da quelli specificati nel file validationPolicy precedente. Se si desidera utilizzare gli stessi dettagli del client di prima (che in genere è il caso), specificare "type": "VALIDATION_BLOCK" e non fornire ulteriori dettagli. 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 del vault che contiene 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 contenente 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 dal quale il gateway API deve ottenere gli endpoint dei metadati di autorizzazione.
      • "maxExpiryDurationInHours": <number-of-hours> specifica il periodo di tempo necessario per inserire nella cache il token JWT generato dal flusso di autorizzazione. L'impostazione predefinita è 1.
      • "useCookiesForSession": <true|false> specifica come memorizzare i token JWT appena generati come stringhe non leggibili dall'uomo 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 (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.
        • Impostare questa opzione su false 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)

      • "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 PKCE (Proof Key for Code Exchange) 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.
      • "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>"opzionalmente specifica 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, "logoutPath": "/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.

      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 di messaggio facoltativo) da restituire 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: (facoltativo) 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: (facoltativo) modifica le intestazioni della risposta che il gateway API restituisce al client API specificando un criterio di risposta di trasformazione dell'intestazione. Per ulteriori informazioni sui criteri di trasformazione delle intestazioni, vedere Aggiunta di criteri di risposta per la trasformazione delle intestazioni.

      Ad esempio:

      {
  "requestPolicies": {
    "authentication": {
      "type": "TOKEN_AUTHENTICATION",
      ...
      "validationPolicy": {
        ...
      },
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "500",
        "responseMessage": "Unfortunately, authentication failed.",
      }
    }
  },
  "routes": [
    ...
  ]
}

  8. 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": "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 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, a condizione che 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": 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 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 l'accesso solo agli utenti finali autenticati con ambito read:hello:

      {
  "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 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 nella richiesta scope di JWT
    • gli utenti finali anonimi non possono accedere all'instradamento
  9. Salvare il file JSON contenente la specifica di distribuzione API.

  10. 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.

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