Token zum Hinzufügen von Authentifizierung und Autorisierung zu API-Deployments validieren

Was geschieht bei der Tokenauthentifizierung?

Wenn ein API-Gateway eine Anforderung von einem API-Client empfängt und Sie eine Tokenauthentifizierungs-Policy angegeben haben, sucht das API-Gateway ein Token (z.B. in einem Tokenheader) und verwendet dieses Token.

Sie geben an, wie das API-Gateway das erhaltene Token validiert, indem Sie die Validierungs-Policy der Tokenauthentifizierungs-Policy als einen der folgenden Typen definieren:

• OAuth 2.0-Introspektionsendpunkt: Geben Sie diesen Typ der Validierungs-Policy an, wenn das API-Gateway ein JWT- oder Nicht-JWT-Token mit dem Introspektionsendpunkt eines Identitätsproviders validieren soll. Sie müssen die Discovery-URL des Identitätsproviders angeben, von dem aus der Introspektionsendpunkt abgerufen werden soll. In diesem Fall übergibt das API-Gateway die Clientzugangsdaten (die Client-ID zusammen mit dem vom Vault-Service abgerufenen Client Secret) an den Identitätsprovider, um das Token zu validieren. Das Token wird ohne die Verwendung von Public Keys validiert. Um die zukünftige Validierung zu beschleunigen, können Sie angeben, dass das API-Gateway die Antwort vom Introspektionsendpunkt zwischen 1 Stunde (Standard) und 24 Stunden im Cache speichern soll. Wenn Sie die API-Deployment-Spezifikation in einer JSON-Datei definieren und dieses Verhalten möchten, nehmen Sie eine Validierungs-Policy des Typs REMOTE_DISCOVERY auf.
• Remote-JWKS: Geben Sie diesen Typ der Validierungs-Policy an, wenn das API-Gateway zur Laufzeit öffentliche Verifizierungsschlüssel verwenden soll, die von einem Identitätsprovider abgerufen wurden, um ein JWT zu prüfen. In diesem Fall kontaktiert das API-Gateway den Identitätsprovider, um das JWT zu prüfen. Der Identitätsprovider fungiert als Autorisierungsserver. Wenn Sie die API-Deployment-Spezifikation in einer JSON-Datei definieren und dieses Verhalten möchten, nehmen Sie eine Validierungs-Policy des Typs REMOTE_JWKS auf.
• Statische Schlüssel: Geben Sie diesen Typ der Validierungs-Policy an, wenn das API-Gateway öffentliche Verifizierungsschlüssel verwenden soll, die bereits von einem Identitätsprovider (als "statische Schlüssel" bezeichnet) zur Prüfung eines JWTs ausgegeben wurden. In diesem Fall kann das API-Gateway das JWT zur Laufzeit lokal verifizieren, ohne den Identitätsprovider kontaktieren zu müssen. Das Ergebnis ist eine schnellere Tokenvalidierung. Wenn Sie die API-Deployment-Spezifikation in einer JSON-Datei definieren und dieses Verhalten möchten, fügen Sie eine Validierungs-Policy des Typs STATIC_KEYS hinzu

Wenn die Validierung erfolgreich ist, leitet das API-Gateway die Anforderung an den entsprechenden API-Endpunkt weiter.

Wenn die Validierung aufgrund eines ungültigen oder fehlenden Tokens in der ursprünglichen Anforderung nicht erfolgreich verläuft, geben Sie das Verhalten des API-Gateways an, indem Sie die Validierungsfehler-Policy der Tokenauthentifizierungs-Policy als einen der folgenden Typen definieren:

• Standard (HTTP 401 nicht autorisiert): Geben Sie diesen Typ der Validierungsfehler-Policy an, wenn das API-Gateway eine HTTP-401-Antwort an den API-Client zurückgeben soll. Dies ist die Standardantwort. Wenn Sie die API-Deployment-Spezifikation in einer JSON-Datei definieren und dieses Verhalten wünschen, fügen Sie einfach keine Validierungsfehler-Policy hinzu.
• Benutzerdefinierte Antwort: Geben Sie diesen Typ der Validierungsfehler-Policy an, wenn das API-Gateway anstelle einer HTTP-401-Antwort eine alternative Antwort (eine geänderte Antwort) an den API-Client zurückgeben soll. Wenn Sie die API-Deployment-Spezifikation in einer JSON-Datei definieren und dieses Verhalten möchten, nehmen Sie eine Validierungsfehler-Policy vom Typ MODIFY_RESPONSE auf.
• OAuth 2.0: Geben Sie diesen Typ der Validierungsfehler-Policy an, wenn das API-Gateway ein neues und gültiges JWT-Token vom Identitätsprovider für GET-Anforderungen abrufen soll (wenn zuerst die ursprünglichen Anforderungsabfrageparameter sicher gespeichert wurden). Für PUT-Anforderungen und POST-Anforderungen können Sie einen relativen Pfad im aktuellen API-Deployment angeben, an den API-Clients umgeleitet werden sollen. Mit dieser Art von Validierungsfehler-Policy können Sie auch ein Abmelde-Backend definieren, um verknüpfte Sessioncookies zu entfernen, Token zu entziehen, indem Sie den Sessionendpunkt des Identitätsproviders aufrufen und zu einer zulässigen URL nach der Abmeldung umleiten. Wenn Sie die API-Deployment-Spezifikation in einer JSON-Datei definieren und dieses Verhalten möchten, nehmen Sie eine Validierungsfehler-Policy vom Typ OAUTH2 auf.

  Beachten Sie, dass Validierungsfehler-Policys vom Typ OAuth 2.0 derzeit nur den OpenID Connect-Autorisierungsablauf und nur die JWT-Tokengenerierung unterstützen (siehe Hinweise zu OAuth 2.0 und OpenID Connect). Im Fall des OpenID Connect-Autorisierungsablaufs werden zwei Token mit dem Namen id_token (immer JWT-codiert) und access_token (kann JWT-codiert sein) zurückgegeben. Das API-Gateway speichert die Tokenwerte in den Kontextvariablen request.auth[id_token] und request.auth[access_token] sowie benutzerdefinierte Claims in den Kontextvariablen request.auth[id_token_claims][<claim-name>] und request.auth[access_token_claims][<claim-name>] (siehe Kontextvariablen zu Policys und HTTP-Backend-Definitionen hinzufügen). Nach Erhalt des neuen id_token-JWT-Tokens ruft das API-Gateway die Anforderungsdetails ab und nimmt die Anforderungsverarbeitung mit dem Token wieder auf.

Der Speicherort, von dem das API-Gateway ein Token abruft, hängt sowohl vom Typ der Validierungs-Policy (einer von OAuth 2.0 Introspection-Endpunkten, Remote-JWKS oder statischen Schlüsseln) als auch vom Typ der Validierungsfehler-Policy (einer von Standard (HTTP 401 Unauthorized), Benutzerdefinierte Antwort oder OAuth 2.0) ab:

• Wenn Sie sowohl eine Validierungs-Policy vom Typ OAuth 2.0 Introspection-Endpunkt als auch eine Validierungsfehler-Policy vom Typ OAuth 2.0 angeben, versucht das API-Gateway zunächst, das Token von einem der folgenden Elemente abzurufen:
  • Wenn Sie in der Validierungsfehler-Policy die Option Cookies für Session verwenden aus einem Sessioncookie ausgewählt haben.
  • Andernfalls aus dem X-APIGW-TOKEN-Header in der Anforderung.

  Wenn das API-Gateway kein Token vom anfänglichen Speicherort abrufen kann, ruft das API-Gateway das Token aus dem Anforderungsheader oder Abfrageparameter ab, den Sie in der Tokenauthentifizierungs-Policy angeben.

  Wenn die Tokenvalidierung anschließend erfolgreich war und Sie die Option Cookies für Session verwenden ausgewählt haben, speichert das API-Gateway das generierte Token als nicht menschenlesbare Zeichenfolge in einem Sessioncookie. Wenn der API-Client eine nachfolgende Anforderung stellt, wird das Token aus dem Sessioncookie abgerufen. Um CSRF-Angriffe zu verhindern, gibt das API-Gateway, wenn das generierte TOKEN in einem Sessioncookie gespeichert wird, auch ein CSRF-TOKEN in einem X-CSRF-TOKEN-Antwortheader zurück (siehe Hinweise zum Cross-Site Request Forgery-(CSRF-)Schutz).

• Wenn Sie nicht sowohl eine Validierungs-Policy vom Typ OAuth 2.0 Introspection-Endpunkt als auch eine Validierungsfehler-Policy vom Typ OAuth 2.0 angeben, ruft das API-Gateway das Token aus dem Anforderungsheader oder dem Abfrageparameter ab, den Sie in der Tokenauthentifizierungs-Policy angeben.

Hinweise zu JSON Web Tokens (JWTs)

Die Token, mit denen Sie den Zugriff auf APIs kontrollieren, sind in der Regel JSON Web Tokens (JWTs). Ein JWT ist ein JSON-basiertes Zugriffstoken, das in einer HTTP-Anforderung von einem API-Client an eine Ressource gesendet wird. JWTs werden von Identitätsprovidern ausgegeben. API Gateway unterstützt die Verwendung aller OAuth2-konformen Identitätsprovider, wie OCI IAM mit Identitätsdomains, Oracle Identity Cloud Service (IDCS), Auth0 und Okta. Wenn ein JWT für den Zugriff auf eine Ressource erforderlich ist, validiert die Ressource das JWT über einen Autorisierungsserver mit einem entsprechenden öffentlichen Verifizierungsschlüssel, indem entweder ein Validierungsendpunkt auf dem Autorisierungsserver aufgerufen oder ein lokaler, vom Autorisierungsserver bereitgestellter Verifizierungsschlüssel verwendet wird.

Ein JWT umfasst Folgendes:

• Einen Header, der den Tokentyp und den kryptografischen Algorithmus zur Generierung der Signatur identifiziert.
• Eine Payload, die Claims zur Identität des Endbenutzers und die Eigenschaften des JWT selbst enthält. Ein Claim ist ein Schlüssel/Wert-Paar, wobei der Schlüssel dem Namen des Claims entspricht. Eine Payload wird empfohlen (ist jedoch nicht erforderlich). Sie enthält reservierte Claims mit bestimmten Namen wie exp (Ablaufzeit), aud (Zielgruppe), iss (Aussteller) und nbf (nicht vor). Eine Payload kann auch benutzerdefinierte Claims mit benutzerdefinierten Namen enthalten.
• Eine Signatur zur Validierung der Authentizität des JWT (abgeleitet von base64, das den Header und die Payload codiert).

Wenn Sie JWTs zur Kontrolle des Zugriffs auf APIs verwenden, können Sie angeben, dass reservierte Claims in der Payload des JWT bestimmte Werte aufweisen müssen, bevor das API-Gateway das JWT als gültig betrachtet. Standardmäßig validieren API-Gateways JWTs mit dem Ablaufclaim (exp), dem Zielgruppenclaim (aud) und dem Ausstellerclaim (iss) sowie mit dem Claim "nicht vor" (nbf), falls vorhanden. Außerdem können Sie zulässige Werte für benutzerdefinierte Claims angeben. Informationen hierzu finden Sie unter Identitätsproviderdetails für iss- und aud-Claims sowie für die JWKS-URI.

Wenn ein JWT validiert wurde, extrahiert das API-Gateway Claims als Schlüssel/Wert-Paar aus der Payload des JWT und speichert sie als Datensätze in der Kontexttabelle request.auth zur Verwendung durch das API-Deployment. Beispiel: Als Kontextvariablen zur Verwendung in einer HTTP-Backend-Definition (siehe Kontextabhängige Variablen zu Policys und HTTP-Backend-Definitionen hinzufügen). Wenn die JWT-Payload den scope-Claim enthält, können Sie die Werte des Claims in Autorisierungsanforderungs-Policys für einzelne Routen verwenden, um die Vorgänge anzugeben, die ein Endbenutzer ausführen darf.

Hinweise zu OAuth 2.0 und OpenID Connect

Das OAuth 2.0-Protokoll ermöglicht den sicheren Abruf sicherer Ressourcen und schützt gleichzeitig die Clientzugangsdaten. OAuth 2.0 ist ein flexibles und sicheres Protokoll, das auf SSL (Secure Sockets Layer) basiert, um sicherzustellen, dass Daten zwischen Webservern und Browsern privat bleiben. Obwohl OAuth 2.0 sich von JWT unterscheidet und für verschiedene Zwecke verwendet wird, sind OAuth 2.0 und JWT kompatibel. Da das OAuth2-Protokoll das Format von Token nicht angibt, können JWTs in die Verwendung von OAuth2 integriert werden. Weitere Informationen zu OAuth 2.0 finden Sie in der OAuth 2.0-Dokumentation.

OpenID Connect ist eine einfache Identitätsschicht über dem OAuth 2.0-Protokoll. Mit OpenID Connect können API-Gateways die Identität eines API-Clients basierend auf der von einem Autorisierungsserver ausgeführten Authentifizierung prüfen. Mit OpenID Connect können API-Gateways auch grundlegende Profilinformationen zum API-Client abrufen. Weitere Informationen zu OpenID Connect finden Sie in der OpenID Connect-Dokumentation.

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

Ein Angreifer kann einen CSRF-Angriff mounten, indem er das Vorhandensein eines Browsercookies ausnutzt, um einen Benutzer dazu zu bringen, einen unbeabsichtigten Befehl an eine Webanwendung, wie ein API-Gateway, weiterzuleiten. Wenn die Anwendung feststellt, dass der Benutzer aufgrund der Existenz des Browsercookies bereits erfolgreich authentifiziert wurde, führt die Anwendung den Befehl mit potenziell schädlichen Folgen aus.

Wenn Sie eine Validierungs-Policy vom Typ OAuth 2.0-Introspektionsendpunkt und eine Validierungsfehler-Policy vom Typ OAuth 2.0 definieren, geben Sie an, wie ein API-Gateway ein neues JWT-Token speichert, das es mit dem OpenID Connect-Autorisierungsablauf erhalten hat:

• Wählen Sie die Option Cookies für Session verwenden aus, wenn Sie das neue JWT-Token in einem Sessioncookie speichern möchten. Um potenzielle CSRF-Angriffe zu verhindern, gibt das API-Gateway beim Speichern des Tokens in einem Sessioncookie auch ein CSRF-TOKEN in einem X-CSRF-TOKEN-Antwortheader zurück. Nachfolgende Mutationsanforderungen an das API-Gateway (wie POST-, PUT- und DELETE-Anforderungen, aber keine GET-Anforderungen) müssen das CSRF-TOKEN zusätzlich zum JWT-TOKEN im Sessioncookie, das automatisch enthalten ist, in einen X-CSRF-TOKEN-Anforderungsheader aufnehmen.

  Beachten Sie, dass das API-Gateway auch das CSRF-Token in der Kontextvariablen request.auth[apigw_csrf_token] speichert. Wenn der API-Client den anfänglichen X-CSRF-TOKEN-Antwortheader aus irgendeinem Grund nicht lesen kann, können Sie die Kontextvariable request.auth[apigw_csrf_token] in eine Headertransformationsantwort-Policy aufnehmen, um einen Antwortheader mit dem CSRF-Token zu jeder Antwort hinzuzufügen, die an den API-Client zurückgegeben wird. Dieser Ansatz stellt sicher, dass der API-Client das CSRF-Token erfolgreich aus dem Antwortheader extrahieren kann, um es in nachfolgende X-CSRF-TOKEN-Mutationsanforderungsheader aufzunehmen, die es an das API-Gateway sendet. Im Folgenden finden Sie ein Beispiel für eine geeignete Headertransformationsantwort-Policy:

  "responsePolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items": [
                {
                  "name": "MY-CSRF-TOKEN",
                  "values": ["${request.auth[apigw_csrf_token]}"],
                  "ifExists": "OVERWRITE"              }
              ]
            }
          }
        }

  Weitere Informationen zu Headertransformationsantwort-Policys finden Sie unter Headertransformationsantwort-Policys hinzufügen.

• Wählen Sie die Option Cookies für Session verwenden nicht aus, 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.

Weitere Informationen zu CSRF finden Sie online.

Hinweise zur Verwendung von JWT_AUTHENTICATION-Anforderungs-Policys

In früheren Releases haben Sie möglicherweise Authentifizierungsanforderungs-Policys vom Typ JWT_AUTHENTICATION erstellt, um JWTs zur Authentifizierung zu verwenden.

Wenn Sie neue Authentifizierungsanforderungs-Policys zur Verwendung von JWTs erstellen, wird jetzt empfohlen, stattdessen Authentifizierungsanforderungs-Policys vom Typ TOKEN_AUTHENTICATION zu erstellen (siehe Tokenauthentifizierungs- und Autorisierungsanforderungs-Policys mit der Konsole hinzufügen und JSON-Datei zum Hinzufügen von Tokenauthentifizierungs- und Autorisierungsanforderungs-Policys bearbeiten). Außerdem wird empfohlen, vorhandene JWT_AUTHENTICATION-Anforderungs-Policys in TOKEN_AUTHENTICATION-Policys zu migrieren.

Beachten Sie, dass vorhandene JWT_AUTHENTICATION-Anforderungs-Policys derzeit noch unterstützt werden. Beachten Sie außerdem, dass Sie zwar neue JWT_AUTHENTICATION-Anforderungs-Policys erstellen können (wie in den ursprünglichen Anweisungen im Abschnitt Verwenden einer JWT_AUTHENTICATION-Authentifizierungsanforderungs-Policy (nicht mehr empfohlen) beschrieben), dass Sie stattdessen Authentifizierungsanforderungs-Policys vom Typ TOKEN_AUTHENTICATION erstellen.