Oracle Cloud Infrastructure - Dokumentation

Abmeldung als API-Gateway-Backend hinzufügen

Erfahren Sie, wie Sie ein Abmelde-Backend mit API Gateway definieren.

Eine allgemeine Anforderung besteht darin, dass APIs API-Clients die Möglichkeit bieten, sich sauber abzumelden, indem sie Zugriffstoken entziehen und möglicherweise andere URLs aufrufen, um zusätzliche Aufgaben nach der Abmeldung auszuführen. Mit API Gateway können Sie Abmelde-Backends definieren, um diese Funktionalität bereitzustellen, wenn Sie eine Tokenauthentifizierungs-Policy OAuth 2.0 für ein API-Deployment verwenden. Anforderungen an das Abmelde-Backend können optional eine URL nach der Abmeldung als Wert eines Abfrageparameters namens postLogoutUrl enthalten.

Wenn Sie eine OAuth 2.0-Tokenauthentifizierungs-Policy definieren, können Sie optional einen Pfad zum Abmelde-Backend (Abmeldepfad) angeben, um Zugriffstoken im Falle eines Authentifizierungsfehlers zu widerrufen. Siehe Token validieren, um Authentifizierung und Autorisierung zu API-Deployments hinzuzufügen.

Die Definition des Abmelde-Backends umfasst optional:

  • Eine Liste der zulässigen URLs nach der Abmeldung, an die eine Anforderung umgeleitet werden kann, um Zugriffstoken zu entziehen. Wenn der Abfrageparameter postLogoutUrl in der Anforderung enthalten ist, muss sein Wert eine dieser URLs sein. Die URLs in der Liste können absolute Pfade oder relative Pfade sein, und die URLs können Kontextvariablen enthalten. Wenn Sie einen relativen Pfad angeben (d.h. zu einer anderen Route im API-Deployment), müssen sowohl das API-Deployment als auch die Route anonymen Zugriff zulassen. Wenn Sie nicht explizit eine oder mehrere URLs in die Liste aufnehmen, ist jede Post-Logout-URL zulässig.
  • Daten, die an Abmelde-URLs übergeben werden, wenn die Anforderung umgeleitet wird, als Wert des Abfrageparameters state. Die Daten können nur Kontextvariablen (nicht statische Werte) enthalten.

Beim Empfang einer Anforderung an den Abmeldepfad von einem API-Client prüft das API-Gateway, ob der API-Client authentifiziert ist, um das Abmelde-Backend aufzurufen, prüft, ob eine in der Anforderung enthaltene Post-Logout-URL zulässig ist, und entfernt alle gespeicherten Informationen zur Session des API-Clients (z.B. in Cookies). Angenommen, die Post-Logout-URL ist zulässig. Was als Nächstes geschieht, hängt davon ab, ob der API-Client authentifiziert ist und ob die zuvor gecachte Antwort von der Discovery-URL, die in der Tokenauthentifizierungs-Policy OAuth 2.0 angegeben ist, einen Endpunkt für die Endsession bereitgestellt hat:

  • Wenn der API-Client nicht authentifiziert ist, leitet das API-Gateway die Abmeldeanforderung an die URL nach der Abmeldung um.
  • Wenn der API-Client authentifiziert wurde, die Tokenauthentifizierungs-Policy OAuth 2.0 jedoch keinen Endpunkt für die Endsession bereitstellte, leitet das API-Gateway die Abmeldeanforderung an die Post-Logout-URL um und übergibt alle Statusinformationen, die in der Definition des Abmelde-Backends angegeben sind.
  • Wenn der API-Client authentifiziert ist und die Tokenauthentifizierungs-Policy OAuth 2.0 einen Endpunkt für die Endsession bereitgestellt hat, leitet das API-Gateway die Abmeldeanforderung an diesen Endpunkt der Endsession um und übergibt die Post-Logout-URL sowie alle in der Definition des Abmelde-Backends angegebenen Statusinformationen. In diesem Fall ist der Identitätsprovider dafür verantwortlich, die Anforderung an die URL nach der Abmeldung umzuleiten.

Sie können ein Abmelde-Backend zu einer API-Deployment-Spezifikation hinzufügen, indem Sie:

  • die Konsole verwenden
  • eine JSON-Datei bearbeiten

Mit der Konsole Abmelde-Backends zu einer API-Deployment-Spezifikation hinzufügen

So fügen Sie mit der Konsole Abmelde-Backends zu einer API-Deployment-Spezifikation hinzu:

  1. Erstellen oder aktualisieren Sie ein API-Deployment mit der Konsole, wählen Sie die Option Völlig neu aus, und geben Sie auf der Seite Basisinformationen Details ein.

    Weitere Informationen finden Sie unter API durch das Erstellen eines API-Deployment in einem API-Gateway bereitstellen und API-Gateway aktualisieren.

  2. Geben Sie auf der Seite Authentifizierung die Authentifizierungsoptionen an.

    Weitere Informationen zu Authentifizierungsoptionen finden Sie unter Hinzufügen von Authentifizierung und Autorisierung zu API-Deployments.

  3. Erstellen Sie auf der Seite Routen eine neue Route, und geben Sie Folgendes an:

    • Pfad: Einen Pfad zum Backend-Service für API-Aufrufe, die die aufgeführten Methoden verwenden. Beachten Sie, dass der von Ihnen angegebene Routenpfad:

    • Methoden: Eine oder mehrere Methoden, die vom Backend-Service akzeptiert werden. Bei Abmelde-Backends wird nur GET akzeptiert.
    • Backend-Typ: Den Typ des Backend-Service als Logout.
    • Zulässige URIs nach der Abmeldung: (optional) Eine Liste mit mindestens einer zulässigen URL, zu der eine Abmeldeanforderung umgeleitet werden kann, um Token zu entziehen. Die URLs in der Liste können absolute Pfade oder relative Pfade sein, und die URLs können Kontextvariablen enthalten. Beispiel: ["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"].

      Beachten Sie dabei Folgendes:

      • Eine Post-Logout-URL kann in eine Anforderung an das Abmelde-Backend als Wert eines Abfrageparameters mit dem Namen postLogoutUrl aufgenommen werden.
      • Wenn Sie einen relativen Pfad angeben (d.h. zu einer anderen Route im API-Deployment), müssen sowohl das API-Deployment als auch die Route anonymen Zugriff zulassen.
      • Wenn Sie nicht explizit eine oder mehrere URLs in die Liste aufnehmen, ist jede Post-Logout-URL zulässig.
    • Status nach Abmeldung: (Optional) Daten, die übergeben werden, wenn eine Abmeldeanforderung an einen Sessionendpunkt und/oder eine Post-Logout-URL umgeleitet wird. Die Daten können nur Kontextvariablen (nicht statische Werte) enthalten. Beispiel: request.query[region]

      Die Daten werden als Wert des Abfrageparameters state übergeben.

  4. (Optional) Wählen Sie Weitere Route aus, um Details zusätzlicher Routen einzugeben.
  5. Wählen Sie Weiter aus, um die Details zu prüfen, die Sie für das API-Deployment eingegeben haben.
  6. Wählen Sie Erstellen oder Änderungen speichern aus, um das API-Deployment zu erstellen oder zu aktualisieren.
  7. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

JSON-Datei zum Hinzufügen von Abmelde-Backends zu einer API-Deployment-Spezifikation bearbeiten

So fügen Sie Abmelde-Backends zu einer API-Deployment-Spezifikation in einer JSON-Datei hinzu: 

  1. Bearbeiten Sie mit Ihrem bevorzugten JSON-Editor die vorhandene API-Deploymentspezifikation, der Sie ein Abmelde-Backend hinzufügen möchten, oder erstellen Sie eine neue API-Deploymentspezifikation (siehe API-Deploymentspezifikation erstellen).

    Beispiel: Die folgende grundlegende API-Deployment-Spezifikation definiert eine einfache serverlose "Hello World"-Funktion in Oracle 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 im routes-Abschnitt einen neuen Abschnitt für ein Abmelde-Backend ein.

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "<logout-route-path>",
      "methods": ["<method-list>"],
      "backend": {
        "type": "OAUTH2_LOGOUT",
        "allowedPostLogoutUris": ["<url>", "<url"],
        "postLogoutState": "<logout-data>"
      }
    }
  ]
}

    Dabei gilt:

    • <logout-route-path> gibt einen Pfad für Aufrufe mit den aufgelisteten Methoden zum Abmelde-Backend an. Beachten Sie, dass der von Ihnen angegebene Routenpfad:

    • <method-list> gibt eine oder mehrere Methoden, die vom Abmelde-Backend akzeptiert werden, durch Komma getrennt an. Im Fall von Abmelde-Backends wird nur GET akzeptiert.
    • "type": "OAUTH2_LOGOUT" gibt an, dass das Backend ein Abmelde-Backend ist.

    • "allowedPostLogoutUris": ["<url>", "<url>"] gibt optional eine Liste mit mindestens einer zulässigen URL an, an die eine Abmeldeanforderung umgeleitet werden kann, um Token zu widerrufen. Die URLs in der Liste können absolute Pfade oder relative Pfade sein, und die URLs können Kontextvariablen enthalten. Beispiel: ["https://${request.header[tenant-id].page.html}", "https://fixed-path.page.html", "/logout_html"].

      Beachten Sie dabei Folgendes:

      • Eine Post-Logout-URL kann in eine Anforderung an das Abmelde-Backend als Wert eines Abfrageparameters mit dem Namen postLogoutUrl aufgenommen werden.
      • Wenn Sie einen relativen Pfad angeben (d.h. zu einer anderen Route im API-Deployment), müssen sowohl das API-Deployment als auch die Route anonymen Zugriff zulassen.
      • Wenn Sie nicht explizit eine oder mehrere URLs in die Liste aufnehmen, ist jede Post-Logout-URL zulässig.

    • "postLogoutState": "<logout-data>" gibt optional Daten an, die übergeben werden sollen, wenn eine Abmeldeanforderung an einen Endpunkt der Endsession und/oder eine URL nach der Abmeldung umgeleitet wird. Die Daten können nur Kontextvariablen (nicht statische Werte) enthalten. Beispiel: request.query[region]

      Die Daten werden als Wert des Abfrageparameters state übergeben.

    In diesem Beispiel kann eine Anforderung an das Backend /logout eine der für allowedPostLogoutUris angegebenen URLs als Wert des Abfrageparameters postLogoutUrl enthalten. Wenn die URL nach der Abmeldung aufgerufen wird, wird der Wert der Kontextvariablen request.query[region] an die URL übergeben. Beachten Sie, dass in diesem Beispiel einer der allowedPostLogoutUris-Werte ("/logout_html") ein relativer Pfad zum Standardantwort-Backend /logout_html in demselben API-Deployment ist. Da es sich um einen relativen Pfad zu einer anderen Route in demselben API-Deployment handelt, muss das /logout_html-Backend eine Autorisierungs-Policy vom Typ ANONYMOUS enthalten, wie hier gezeigt.

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      }
    },
    {
      "path": "/logout",
      "methods": ["GET"],
      "backend": {
        "type": "OAUTH2_LOGOUT",
        "allowedPostLogoutUris": ["https://${request.header[tenant-id].page.html}", "/logout_html"],
        "postLogoutState": "request.query[region]"
      }
    },
    {
      "path": "/logout_html",
      "methods": ["GET"],
      "backend": {
        "type": "STOCK_RESPONSE_BACKEND",
        "body": "Token could not be revoked."
      },
      "requestPolicies": {
        "authorization": {
          "type": "ANONYMOUS"
        }
      }
    }
  ]
}
  3. Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.

  4. 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-Deployment in einem API-Gateway bereitstellen und API-Gateway aktualisieren.

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