Oracle Cloud Infrastructure - Dokumentation

JSON-Datei zum Hinzufügen der Tokenauthentifizierungs- und Autorisierungsanforderungs-Policys bearbeiten

Authentifizierungsanforderungs-Policys und Autorisierungsanforderungs-Policys zu einer API-Deployment-Spezifikation in einer JSON-Datei hinzufügen.

  1. Bearbeiten Sie mit Ihrem bevorzugten JSON-Editor die vorhandene API-Deployment-Spezifikation, der Sie eine Authentifizierungs- und Autorisierungsfunktionalität hinzufügen möchten, oder erstellen Sie eine neue API-Deployment-Spezifikation (siehe API-Deployment-Spezifikation erstellen).

    Die API-Deployment-Spezifikation beinhaltet zumindest einen routes-Abschnitt, der Folgendes enthält:

    • Einen Pfad. Beispiel: /hello
    • Mindestens eine Methode. Beispiel: GET
    • Eine Definition eines Backends. Beispiel: Eine URL oder die OCID einer Funktion in OCI Functions.

    Beispiel: Die folgende grundlegende API-Deployment-Spezifikation definiert eine einfache serverlose Hello World-Funktion in OCI Functions als einzelnes Backend:

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

  2. Fügen Sie einen requestPolicies-Abschnitt vor dem routes-Abschnitt ein (falls noch keiner vorhanden ist), um eine authentication-Anforderungs-Policy zu erstellen, die für alle Routen in der API-Deployment-Spezifikation gilt. Beispiel:

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

  3. Fügen Sie die Anforderungs-Policy authentication wie folgt hinzu:

    
{
  "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"
      }
    }
  ]
}

    Dabei gilt:

    • "authentication": {"type": "TOKEN_AUTHENTICATION"... gibt an, dass Sie Token zur Authentifizierung verwenden möchten.
    • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> gibt an, ob dies ein Anforderungsheader ist, der das Token (wenn ja, wird der Name des Headers angegebenen) enthält, oder ob der Abfrageparameter, der das Token enthält (falls ja, wird der Name des Abfrageparametersangegeben). Beachten Sie, dass Sie entweder "tokenHeader": "<token-header-name>" oder "tokenQueryParam": "<token-query-param-name>"> angeben können, aber nicht beides. Beispiel: "tokenHeader": "Authorization"
    • <tokenAuthScheme> ist der Name des Authentifizierungsschemas, das verwendet werden soll, wenn das Token in einem Anforderungsheader enthalten ist. Beispiel: "Bearer".
    • "isAnonymousAccessAllowed": <true|false> gibt optional an, ob nicht authentifizierte (d.h. anonyme) Endbenutzer auf Routen in der API-Deployment-Spezifikation zugreifen können. Wenn Sie den Zugriff anonymer Endbenutzer auf Routen nie zulassen möchten, setzen Sie diese Eigenschaft auf false. Wenn Sie diese Eigenschaft nicht in die authentication-Policy aufnehmen, wird standardmäßig false verwendet. Hinweis: Wenn Sie diese Eigenschaft aufnehmen und auf true setzen, müssen Sie auch explizit jede Route angeben, auf die anonym zugegriffen werden kann. Setzen Sie dazu in der authorization-Policy jeder einzelnen Route die type-Eigenschaft auf "ANONYMOUS".
    • maxClockSkewInSeconds: <seconds-difference> gibt optional den maximalen Zeitunterschied zwischen den Systemuhren des Identitätsproviders, der ein JWT ausgestellt hat, und dem API-Gateway an. Der angegebene Wert wird berücksichtigt, wenn das API-Gateway das JWT validiert, um zu bestimmen, ob es noch gültig ist. Verwenden Sie hierzu den Claim "nicht vor" (nbf), falls vorhanden) und den Ablaufclaim (exp) im JWT. Der Mindestwert (und Standardwert) ist 0, der Höchstwert ist 120.
    • "validationPolicy": {<validation-policy-config>} gibt eine Validierungs-Policy zur Validierung von Token an, wie in den folgenden Schritten beschrieben.
  4. Wenn das API-Gateway sowohl JWT-Token als auch Nicht-JWT-Token mit dem Introspektionsendpunkt eines OAuth 2.0-Autorisierungsservers mit Clientzugangsdaten (einschließlich eines aus einem Vault im Vault-Service abgerufenen Client-Secrets) validieren soll, fügen Sie dem leeren Abschnitt validationPolicy die folgende Validierungs-Policy hinzu:
          "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>
          }]
        }
      }

    Dabei gilt:

    • "validationPolicy": {"type": "REMOTE_DISCOVERY"...} gibt an, dass Sie Token mit dem Introspektionsendpunkt eines OAuth 2.0-Autorisierungsservers mit Clientzugangsdaten validieren möchten (einschließlich eines Client-Secrets, das aus einem Vault im Vault-Service abgerufen wird).
    • clientDetails": {"type": "CUSTOM"...} gibt Details des Client-Secrets an, das aus einem Vault im Vault-Service abgerufen werden soll:
      • "clientId": "<client-id>" gibt die Client-ID an, die an den Introspektionsendpunkt gesendet werden soll. Sie erhalten eine Client-ID, indem Sie eine Clientanwendung beim Autorisierungsserver erstellen und registrieren. Beispiel: 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1. Siehe Voraussetzungen für die Tokenauthentifizierung.
      • "clientSecretId": "<secret-ocid>" gibt die OCID des Vault Secrets an, das das Client Secret enthält, das an den Introspektionsendpunkt gesendet werden soll. Beispiel: ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
      • "clientSecretVersionNumber": <secret-version-number> gibt die Version des Vault Secret an, das das Client Secret enthält, das an den Introspektionsendpunkt gesendet werden soll. Zum Beispiel 1
    • "uri": "<well-known-uri>" gibt die bekannte URL eines Autorisierungsservers an, von dem das API-Gateway Autorisierungsmetadatenendpunkte abrufen soll. Beispiel: https://my-idp/oauth2/default/.well-known/openid-configuration. Beachten Sie, dass die URL aus dem Subnetz mit dem API-Gateway geroutet werden kann, in dem die API bereitgestellt wird.
    • "isSslVerifyDisabled": <true|false> gibt an, ob die SSL-Überprüfung beim Kommunizieren mit dem Autorisierungsserver deaktiviert werden soll Oracle empfiehlt, diese Option nicht auf true zu setzen, weil sie das JWT-Validierung kompromittieren kann. API Gateway vertraut Zertifikaten von mehreren Certificate Authoritys, die für OCI IAM mit Identitätsdomains, Oracle Identity Cloud Service (IDCS), Auth0 und Okta ausgestellt werden.
    • "maxCacheDurationInHours": <cache-time> gibt an, wie viele Stunden (zwischen 1 und 24) lang das API-Gateway die Antwort vom Introspektionsendpunkt cachen soll.
    • "additionalValidationPolicy": {"issuers": ...} gibt zusätzliche Details für die Tokenvalidierung an:
      • <issuer-url> ist die URL (oder eine Textzeichenfolge) für einen Autorisierungsserver, die im Ausstellerclaim (iss) eines JWTs für den Zugriff auf das API-Deployment zulässig ist. Beispiel: Um ein von OCI IAM mit Identitätsdomains ausgegebenes JWT für den Zugriff auf das API-Deployment zu aktivieren, geben Sie https://identity.oraclecloud.com/ an. Sie können einen oder mehrere Autorisierungsserver (maximal fünf) angeben. Informationen hierzu finden Sie unter Identitätsproviderdetails für iss- und aud-Claims sowie für die JWKS-URI.
      • <intended-audience> ist ein Wert, der im Zielgruppenclaim (aud) eines JWT zur Identifikation des beabsichtigten Empfängers des Tokens zulässig ist. Beispiel: Die Zielgruppe kann (muss aber nicht) dem Hostnamen des API-Gateways entsprechen. Sie können eine oder mehrere Zielgruppen angeben (maximal fünf). Informationen hierzu finden Sie unter Identitätsproviderdetails für iss- und aud-Claims sowie für die JWKS-URI.
      • "verifyClaims": {...} gibt optional zusätzliche Claimnamen und -werte für einen oder mehrere zusätzliche Claims zur Validierung in einem JWT an (maximal zehn):
        • "key": "<claim-name>" ist der Name eines Claims, der in einem JWT enthalten sein kann oder muss. Der angegebene Claimname kann ein reservierter Claimname sein, wie der Subject-Claim (sub), oder ein benutzerdefinierter Claimname, der von einem bestimmten Autorisierungsserver ausgestellt wird.
        • "values": ["<acceptable-value>", "<acceptable-value>"] (optional) gibt einen oder mehrere zulässige Werte für den Claim an.
        • "isRequired": <true|false> gibt an, ob der Claim im JWT enthalten sein muss.

        Beachten Sie, dass alle eingegebenen Schlüsselnamen und -werte einfach wie Zeichenfolgen behandelt werden und exakt mit den Namen und Werten im JWT übereinstimmen müssen. Das Abgleichen von Mustern und andere Datentypen werden nicht unterstützt.

    Beispiel: Die folgende authentication-Policy konfiguriert das API-Gateway so, dass ein Token im Autorisierungsanforderungsheader mit Clientzugangsdaten (einschließlich eines Client-Secrets, das aus einem Vault im Vault-Service abgerufen wird) validiert wird, das an einen OAuth 2.0-Introspektionsendpunkt übergeben wird:

    {
  "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. Wenn das API-Gateway JWTs validieren soll, indem öffentliche Verifizierungsschlüssel zur Laufzeit vom Identitätsprovider abgerufen werden, fügen Sie die folgende Validierungs-Policy zum leeren Abschnitt validationPolicy hinzu:

          "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>
          }]
        }
      }

    Dabei gilt:

    • "validationPolicy": {"type": "REMOTE_JWKS"... gibt an, dass Sie das API-Gateway so konfigurieren möchten, dass bis zu zehn öffentliche Verifizierungsschlüssel zur Laufzeit vom Identitätsprovider abgerufen werden.
    • "uri": "<uri-for-jwks>" gibt die URI an, von der das JSON Web Key Set (JWKS) abgerufen werden soll, mit dem die Signatur der JWTs verifiziert werden soll. Weitere Informationen über die anzugebende URI finden Sie unter Identitätsproviderdetails für iss- und aud-Claims sowie für die JWKS-URI. Beachten Sie dabei Folgendes:
      • Die URI muss aus dem Subnetz mit dem API-Gateway routbar sein, in dem die API bereitgestellt wird.
      • Wenn das API-Gateway das JWKS nicht abrufen kann, geben alle Anforderungen an das API-Deployment einen HTTP 500-Antwortcode zurück. Weitere Informationen zum Fehler finden Sie im Ausführungslog des API-Gateways (siehe Logging zu API-Deployments hinzufügen).
      • Bestimmte Schlüsselparameter müssen im JWKS vorhanden sein, um die JWT-Signatur zu verifizieren (siehe Erforderliche Schlüsselparameter zum Überprüfen von JWT-Signaturen).
      • Der JWKS kann bis zu zehn Schlüssel enthalten.
    • "isSslVerifyDisabled": <true|false> gibt an, ob die SSL-Überprüfung bei der Kommunikation mit dem Identitätsprovider deaktiviert werden soll. Oracle empfiehlt, diese Option nicht auf true zu setzen, weil sie das JWT-Validierung kompromittieren kann. API Gateway vertraut Zertifikaten von mehreren Certificate Authoritys, die für OCI IAM mit Identitätsdomains, Oracle Identity Cloud Service (IDCS), Auth0 und Okta ausgestellt werden.
    • "maxCacheDurationInHours": <cache-time> gibt an, wieviele Stunden (zwischen 1 und 24) lang das API-Gateway das JWKS-Satz nach den Abrufen cachten soll.
    • "additionalValidationPolicy": {"issuers": ...} gibt zusätzliche Details für die Tokenvalidierung an:
      • <issuer-url> ist die URL (oder eine Textzeichenfolge) für einen Identitätsprovider, der im Ausstellerclaim (iss) eines JWTs für den Zugriff auf das API-Deployment zulässig ist. Beispiel: Um ein von OCI IAM ausgestelltes JWT mit Identitätsdomains für den Zugriff auf die API-Bereitstellung zu aktivieren, geben Sie https://identity.oraclecloud.com/ ein. Sie können einen oder mehrere Identitätsprovider angeben (maximal fünf). Informationen hierzu finden Sie unter Identitätsproviderdetails für iss- und aud-Claims sowie für die JWKS-URI.
      • <intended-audience> ist ein Wert, der im Zielgruppenclaim (aud) eines JWT zur Identifikation des beabsichtigten Empfängers des Tokens zulässig ist. Beispiel: Die Zielgruppe kann (muss aber nicht) dem Hostnamen des API-Gateways entsprechen. Sie können eine oder mehrere Zielgruppen angeben (maximal fünf). Informationen hierzu finden Sie unter Identitätsproviderdetails für iss- und aud-Claims sowie für die JWKS-URI.
      • verifyClaims gibt optional zusätzliche Claimnamen und -werte für einen oder mehrere zusätzliche Claims zur Überprüfung in einem JWT an (maximal zehn).
        • "key": "<claim-name>" ist der Name eines Claims, der in einem JWT enthalten sein kann oder muss. Der angegebene Claimname kann ein reservierter Claimname sein, wie der Subject-Claim (sub), oder ein benutzerdefinierter Claimname, der von einem bestimmten Identitätsprovider ausgestellt wird.
        • "values": ["<acceptable-value>", "<acceptable-value>"] (optional) gibt einen oder mehrere zulässige Werte für den Claim an.
        • "isRequired": <true|false> gibt an, ob der Claim im JWT enthalten sein muss.

        Beachten Sie, dass alle eingegebenen Schlüsselnamen und -werte einfach wie Zeichenfolgen behandelt werden und exakt mit den Namen und Werten im JWT übereinstimmen müssen. Das Abgleichen von Mustern und andere Datentypen werden nicht unterstützt.

    Beispiel: Die folgende authentication-Policy konfiguriert das API-Gateway, um das JWT im Autorisierungsanforderungsheader zu validieren, indem öffentliche Verifizierungsschlüssel zur Laufzeit vom Identitätsprovider abgerufen werden:

    {
  "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. Wenn das API-Gateway JWTs mit öffentlichen Prüfschlüsseln validieren soll, die bereits von einem Identitätsprovider ausgestellt wurden (sodass das API-Gateway JWTs lokal verifizieren kann, ohne dass der Identitätsprovider kontaktiert werden müsste), fügen Sie die folgende Validierungs-Policy zum leeren Abschnitt validationPolicy hinzu:

          "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>
          }]
        }
      }

    Dabei gilt:

    • "validationPolicy": {"type": "STATIC_KEYS"... gibt an, dass Sie das API-Gateway mit bis zu zehn öffentlichen Verifizierungsschlüsseln konfigurieren möchten, die bereits von einem Identitätsprovider ausgestellt wurden (So kann das API-Gateway JWTs lokal verifizieren, ohne den Identitätsprovider kontaktieren zu müssen).
    • "keys": [{<key-config>}]: Geben Sie die ID des statischen Schlüssels an, mit dem das JWT signiert wird. Welche Details angegeben werden sollen, hängt vom Format des Schlüssels ab, der bereits vom Identitätsprovider ausgegeben wurde (unabhängig vom Format können Sie bis zu zehn Schlüssel angeben):

      • Wenn es sich bei dem statischen Schlüssel um einen JSON Web Key handelt, geben Sie "format": "JSON_WEB_KEY" an, geben Sie die ID des statischen Schlüssels zum Signieren des JWT als Wert des "kid"-Parameters an, und geben Sie Werte für weitere Parameter zur Überprüfung der JWT-Signatur an.

        Beispiel:

                "keys": [
          {
            "format": "JSON_WEB_KEY",
            "kid": "master_key",
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
        ]

        Beachten Sie, dass bestimmte Parameter im statischen Schlüssel vorhanden sein müssen, um die JWT-Signatur zu verifizieren (siehe Erforderliche Schlüsselparameter zum Überprüfen von JWT-Signaturen). Beachten Sie auch, dass RSA derzeit der einzige unterstützte Schlüsseltyp (kty) ist.

      • Wenn es sich bei dem statischen Schlüssel um einen PEM-codierten Public Key handelt, geben Sie "format": "PEM" an, geben Sie die ID des statischen Schlüssels zum Signieren des JWT als Wert von "kid" an, und geben Sie den Schlüssel als Wert von "key" an.

        Beispiel:

                "keys": [
          {
            "format": "PEM",
            "kid": "master_key"
            "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY-----
          }
        ]

        Beachten Sie, dass die Marker -----BEGIN PUBLIC KEY----- und -----END PUBLIC KEY----- erforderlich sind.

    • "isSslVerifyDisabled": <true|false> gibt an, ob die SSL-Überprüfung bei der Kommunikation mit dem Identitätsprovider deaktiviert werden soll. Oracle empfiehlt, diese Option nicht auf true zu setzen, weil sie das JWT-Validierung kompromittieren kann. API Gateway vertraut Zertifikaten von mehreren Certificate Authoritys, die für OCI IAM mit Identitätsdomains, Oracle Identity Cloud Service (IDCS), Auth0 und Okta ausgestellt werden.
    • "maxCacheDurationInHours": <cache-time> gibt an, wieviele Stunden (zwischen 1 und 24) lang das API-Gateway das JWKS-Satz nach den Abrufen cachten soll.
    • "additionalValidationPolicy": {"issuers": ...} gibt zusätzliche Details für die Tokenvalidierung an:
      • <issuer-url> ist die URL (oder eine Textzeichenfolge) für einen Identitätsprovider, der im Ausstellerclaim (iss) eines JWTs für den Zugriff auf das API-Deployment zulässig ist. Beispiel: Um ein von OCI IAM ausgestelltes JWT mit Identitätsdomains für den Zugriff auf die API-Bereitstellung zu aktivieren, geben Sie https://identity.oraclecloud.com/ ein. Sie können einen oder mehrere Identitätsprovider angeben (maximal fünf). Informationen hierzu finden Sie unter Identitätsproviderdetails für iss- und aud-Claims sowie für die JWKS-URI.
      • <intended-audience> ist ein Wert, der im Zielgruppenclaim (aud) eines JWT zur Identifikation des beabsichtigten Empfängers des Tokens zulässig ist. Beispiel: Die Zielgruppe kann (muss aber nicht) dem Hostnamen des API-Gateways entsprechen. Sie können eine oder mehrere Zielgruppen angeben (maximal fünf). Informationen hierzu finden Sie unter Identitätsproviderdetails für iss- und aud-Claims sowie für die JWKS-URI.
      • verifyClaims gibt optional zusätzliche Claimnamen und -werte für einen oder mehrere zusätzliche Claims zur Überprüfung in einem JWT an (maximal zehn).
        • "key": "<claim-name>" ist der Name eines Claims, der in einem JWT enthalten sein kann oder muss. Der angegebene Claimname kann ein reservierter Claimname sein, wie der Subject-Claim (sub), oder ein benutzerdefinierter Claimname, der von einem bestimmten Identitätsprovider ausgestellt wird.
        • "values": ["<acceptable-value>", "<acceptable-value>"] (optional) gibt einen oder mehrere zulässige Werte für den Claim an.
        • "isRequired": <true|false> gibt an, ob der Claim im JWT enthalten sein muss.

        Beachten Sie, dass alle eingegebenen Schlüsselnamen und -werte einfach wie Zeichenfolgen behandelt werden und exakt mit den Namen und Werten im JWT übereinstimmen müssen. Das Abgleichen von Mustern und andere Datentypen werden nicht unterstützt.

    Beispiel: Die folgende authentication-Policy konfiguriert das API-Gateway mit einem öffentlichen Verifizierungsschlüssel, der bereits von einem Identitätsprovider ausgegeben wurde, um das JWT im Autorisierungsanforderungsheader zu validieren:

    {
  "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. (Optional) Sie können angeben, wie das API-Gateway eine nicht erfolgreiche Authentifizierungsantwort verarbeiten soll (nach einem nicht erfolgreichen Versuch, ein fehlendes oder ungültiges Token zu validieren, zurückgegeben), indem Sie eine Validierungsfehler-Policy einrichten:
    1. Wenn das API-Gateway einen HTTP 401-Statuscode senden soll und der WWW-Authenticate-Header in der Antwort (die Standardantwort auf ein fehlendes oder ungültiges Token) keine Validierungsfehler-Policy definieren soll.

    2. Wenn das API-Gateway einen OpenID Connect-Autorisierungsfluss verwenden soll, um ein neues JWT-Zugriffstoken abzurufen, definieren Sie eine Validierungsfehler-Policy vom Typ OAUTH2. Beachten Sie, dass diese Option nur verfügbar ist, wenn Sie zuvor einen validationPolicy vom Typ REMOTE_DISCOVERY angegeben haben. Wählen Sie eine der folgenden Optionen aus: 

      {
  "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": [
    ...
  ]
}

      Dabei gilt:

      • "scopes": ["<scope>", "<scope"] gibt einen oder mehrere Zugriffsgeltungsbereiche an, die in einen an den Autorisierungsserver gesendeten scope-Claim aufgenommen werden sollen. Um den OpenID Connect-Autorisierungsablauf verwenden zu können, müssen Sie openid als einen der Geltungsbereiche aufnehmen. Beispiel: "scopes": ["openid", "email:read", "profile"]
      • clientDetails": {...} gibt wie folgt die Clientdetails an, die zum Abrufen eines neuen JWT-Zugriffstokens vom Autorisierungsserver verwendet werden sollen:
        • "type": "<VALIDATION_BLOCK|CUSTOM>" gibt an, ob dieselben oder andere Clientdetails als in der vorherigen validationPolicy angegeben verwendet werden sollen. Wenn Sie dieselben Clientdetails wie zuvor verwenden möchten (in der Regel ist dies der Fall), geben Sie "type": "VALIDATION_BLOCK" an, und geben Sie keine zusätzlichen Details an. Wenn Sie andere Clientdetails verwenden möchten, geben Sie "type": "CUSTOM" an, und legen Sie Werte für "clientId", "clientSecretId" und "clientSecretVersionNumber" fest.
        • "clientId": "<client-id>" gibt die Client-ID an, die an den Introspektionsendpunkt gesendet werden soll. Nur verwendet, wenn "type": "CUSTOM". Beispiel: 5hsti38yhy5j2a4tas455rsu6ru8yui3wrst4n1
        • "clientSecretId": "<secret-ocid>" gibt die OCID des Vault Secrets an, das das Client Secret enthält, das an den Introspektionsendpunkt gesendet werden soll. Nur verwendet, wenn "type": "CUSTOM". Beispiel: ocid1.vaultsecret.oc1.iad.amaaaaaa______cggit3q
        • "clientSecretVersionNumber": <secret-version-number> gibt die Version des Vault Secret an, das das Client Secret enthält, das an den Introspektionsendpunkt gesendet werden soll. Nur verwendet, wenn "type": "CUSTOM". Zum Beispiel 1
      • "sourceUriDetails": {"type": "VALIDATION_BLOCK"} gibt an, dass Sie dieselbe URL verwenden möchten, die in der vorherigen validationPolicy angegeben ist, wie die bekannte URL eines Autorisierungsservers, von dem das API-Gateway Autorisierungsmetadatenendpunkte abrufen soll.
      • "maxExpiryDurationInHours": <number-of-hours> gibt an, wie lange das vom Autorisierungsfluss generierte JWT-Token gecacht werden soll. Der Standardwert ist 1.
      • "useCookiesForSession": <true|false> gibt an, wie neu generierte JWT-Token als nicht menschenlesbare Zeichenfolgen am Ende eines OpenID Connect-Autorisierungsablaufs gespeichert werden:
        • Setzen Sie diese Option auf true, wenn Sie das neue JWT-Token in einem Sessioncookie speichern möchten. Um potenzielle CSRF-Angriffe zu verhindern, gibt das API-Gateway, wenn es das TOKEN in einem Sessioncookie speichert, auch ein CSRF-TOKEN in einem X-CSRF-TOKEN-Antwortheader zurück. Nachfolgende Anforderungen (außer GET-Anforderungen) müssen das CSRF-TOKEN in einem X-CSRF-TOKEN-Anforderungsheader enthalten, zusätzlich zum JWT-TOKEN im Sessioncookie, das automatisch enthalten ist.
        • Setzen Sie diese Option auf false, wenn Sie das neue JWT-Token nicht in einem Sessioncookie speichern möchten. Stattdessen gibt das API-Gateway ein nicht menschenlesbares TOKEN in einem X-APIGW-TOKEN-Antwortheader zurück. Nachfolgende Anforderungen an das API-Gateway müssen dasselbe TOKEN in einem X-APIGW-TOKEN-Anforderungsheader enthalten.

        Siehe Hinweise zum Cross-Site Request Forgery-(CSRF-)Schutz

      • "useCookiesForIntermediateSteps": <true|false> gibt an, wie Zwischenschrittwerte für den Autorisierungsablauf gespeichert werden (z.B. Anforderungsparameter). Setzen Sie diese Option auf true, um die Werte in Browser-Cookies zu speichern. Setzen Sie diese Option auf false, um die Werte mit dem API-Gateway zu speichern.
      • "usePkce": <true|false> gibt an, ob PKCE (Proof Key for Code Exchange) für zusätzliche Sicherheit verwendet werden soll. PKCE ist eine OAuth 2.0-Sicherheitserweiterung, um CSRF (Cross-Site Request Forgery) und Autorisierungscode-Injection-Angriffe zu verhindern. PKCE ist kein Ersatz für ein Client Secret, und PKCE wird empfohlen, auch wenn ein Client Secret verwendet wird. Weitere Informationen zu PKCE finden Sie in der Dokumentation zu OAuth 2.0.
      • "responseType": "code" gibt den Typ der Antwort an, die für den Autorisierungsablauf erforderlich ist. Geben Sie code als Antworttyp an.
      • "fallbackRedirectPath": "/home" gibt optional einen relativen Pfad im aktuellen API-Deployment an, an den API-Clients umgeleitet werden sollen, wenn die ursprüngliche Anforderung eine PUT-Anforderung oder eine POST-Anforderung war. Beispiel: /home.

        Wenn die ursprüngliche Anforderung eine GET-Anforderung war, wird die Anforderungsverarbeitung mit einem neuen JWT-Zugriffstoken fortgesetzt, sodass kein Fallback-Pfad verwendet wird.

      • "logoutPath": "<revoke-path>"gibt optional einen relativen Pfad zu einem Abmelde-Backend im aktuellen API-Deployment an. Der angegebene Pfad muss mit dem Pfad übereinstimmen, der für das Abmelde-Backend definiert ist. Beispiel: "logoutPath": "/revoke".

        Ein API-Client kann das Abmelde-Backend aufrufen, um Token zu entziehen. Ein Aufruf des Abmelde-Backends kann eine Abmelde-URL als Abfrageparameter mit dem Namen postLogoutUrl enthalten. Siehe Abmeldung als API-Gateway-Backend hinzufügen.

      Beispiel:

      {
  "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. Wenn Sie die Antwort an einen nicht erfolgreichen Versuch anpassen möchten, ein fehlendes oder ungültiges Token zu validieren, definieren Sie eine Validierungsfehler-Policy vom Typ MODIFY_RESPONSE, und geben Sie einen Statuscode (und einen optionalen Nachrichtentext) an, um zum API-Client zurückzukehren:
      {
  "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": [
    ...
  ]
}

      Dabei gilt:

      • responseCode: Gibt einen alternativen HTTP-Statuscode an. Beispiel: 500.
      • responseMessage: (optional) gibt einen Nachrichtentext an. Beispiel: Unfortunately, authentication failed. Der Nachrichtentext kann eine beliebige Kontextvariable enthalten (außer request.body).
      • responseTransformations: (optional) ändert die Header der Antwort, die das API-Gateway an den API-Client zurückgibt, indem eine Headertransformationsantwort-Policy angegeben wird. Weitere Informationen zu Headertransformations-Policys finden Sie unter Headertransformationsantwort-Policys hinzufügen.

      Beispiel:

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

  8. Fügen Sie eine authorization-Anforderungs-Policy für jede Route in der API-Deployment-Spezifikation hinzu:

    1. Fügen Sie, falls noch nicht vorhanden, einen requestPolicies-Abschnitt nach dem backend-Abschnitt der ersten Route ein. Beispiel:

      {
  "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. Fügen Sie die folgende authorization-Policy zum neuen requestPolicies-Abschnitt hinzufügen:

            "requestPolicies": {
        "authorization": {
          "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
          "allowedScope": [ "<scope>" ]
        }
      }

      Dabei gilt:

      • "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS"> gibt an, wie Zugriff auf die Route erteilt werden soll:

        • "AUTHENTICATION_ONLY": Zugriff wird nur Endbenutzern erteilt, die erfolgreich authentifiziert wurden. In diesem Fall zeigt die "isAnonymousAccessAllowed"-Eigenschaft in der authentication-Policy der API-Deployment-Spezifikation keine Wirkung.
        • "ANY_OF": Zugriff wird nur Endbenutzern erteilt, die erfolgreich authentifiziert wurden, sofern der scope-Claim des JWT einen der Zugriffsgeltungsbereiche enthält, die Sie in der Eigenschaft allowedScope angeben. In diesem Fall zeigt die "isAnonymousAccessAllowed"-Eigenschaft in der authentication-Policy der API-Deployment-Spezifikation keine Wirkung.
        • "ANONYMOUS": Zugriff wird allen Endbenutzern erteilt, selbst wenn diese nicht erfolgreich authentifiziert wurden. In diesem Fall müssen Sie die "isAnonymousAccessAllowed"-Eigenschaft in der authentication-Policy der API-Deployment-Spezifikation explizit auf true setzen.
      • "allowedScope": [ "<scope>" ] ist eine kommagetrennte Liste mit mindestens einer Zeichenfolge, die einem im scope-Claim des JWT enthaltenen Zugriffsgeltungsbereich entspricht. In diesem Fall müssen Sie die type-Eigenschaft auf "ANY_OF" setzen (die "allowedScope"-Eigenschaft wird ignoriert, wenn die type-Eigenschaft auf "AUTHENTICATION_ONLY" oder "ANONYMOUS" gesetzt wurde). Wenn Sie mehr als einen Geltungsbereich angeben, wird der Zugriff auf die Route erteilt, sobald einer der angegebenen Geltungsbereiche im scope-Claim des JWT enthalten ist.

      Beispiel: Die folgende Anforderungs-Policy definiert eine /hello-Route, die nur authentifizierten Endbenutzern mit dem Geltungsbereich read:hello Zugriff gewährt:

      {
  "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. Fügen Sie eine authorization-Anforderungs-Policy für alle restlichen Routen in der API-Deployment-Spezifikation hinzu.
    Hinweis

    Wenn Sie keine authorization-Policy für eine bestimmte Route angeben, wird der Zugriff basierend auf der Annahme erteilt, dass eine solche Policy vorhanden ist, und die type-Eigenschaft wird auf "AUTHENTICATION_ONLY" gesetzt. Anders ausgedrückt: Ungeachtet der Einstellung der isAnonymousAccessAllowed-Eigenschaft in der authentication-Policy der API-Deployment-Spezifikation können:

    • nur authentifizierte Endbenutzer auf die Route zugreifen
    • alle authentifizierten Endbenutzer unabhängig von den Zugriffsgeltungsbereichen im scope-Claim des JWT auf die Route zugreifen
    • anonyme Endbenutzer nicht auf die Route zugreifen
  9. Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.

  10. Verwenden Sie die API-Deployment-Spezifikation, wenn Sie ein API-Deployment wie folgt erstellen oder aktualisieren:

    • Durch Angabe der JSON-Datei in der Konsole bei Auswahl der Option Vorhandene API hochladen
    • Durch Angabe der JSON-Datei in einer Anforderung an die REST-API von API-Gateway

    Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployments in einem API-Gateway implementieren und API-Gateways aktualisieren.

  11. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).