Authentifizierungs- und Autorisierungsanforderungs-Policys für Multi-Argument-Zugriffstoken und Autorisiererfunktionen hinzufügen (empfohlen)

So fügen Sie mit der Konsole Authentifizierungsanforderungs-Policys und Autorisierungsanforderungs-Policys für Zugriffstoken mit mehreren Argumenten zu einer API-Deployment-Spezifikation hinzu

1. Erstellung oder Aktualisierung eines API-Deployments mit der Konsole, wählen Sie die Option Deployment erstellen aus, und geben Sie auf der Seite Basisinformationen Details ein.

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

2. Wählen Sie Weiter, um die Seite Authentifizierung anzuzeigen.

3. Wählen Sie Einzelne Authentifizierung aus, um anzugeben, dass Sie einen einzelnen Authentifizierungsserver für alle Anforderungen verwenden möchten.

   Bei diesen Anweisungen wird davon ausgegangen, dass Sie einen einzelnen Authentifizierungsserver verwenden möchten. Wenn Sie mehrere Authentifizierungsserver verwenden möchten, wählen Sie alternativ Multi-Authentifizierung aus, und befolgen Sie die Anweisungen unter Mehrere Authentifizierungsserver zu demselben API-Deployment mit der Konsole hinzufügen.

4. Wählen Sie Anonymen Zugang aktivieren aus, oder heben Sie die Auswahl auf, um anzugeben, ob nicht authentifizierte (d.h. anonyme) Endnutzer auf Routen im API-Deployment zugreifen dürfen.

   Standardmäßig ist diese Option nicht ausgewählt. Wenn Sie den Zugriff anonymer Benutzer auf Routen nie zulassen möchten, wählen Sie diese Option nicht aus. Hinweis: Wenn Sie diese Option auswählen, müssen Sie auch explizit jede Route angeben, für die anonymer Zugriff zulässig ist, indem Sie in der Autorisierungs-Policy jeder einzelnen Route Anonym als Autorisierungstyp auswählen.

5. Wählen Sie in der Optionsliste Authentifizierungstyp die Option Autorisierungsfunktion aus.
6. Geben Sie die Autorisiererfunktion mit mehreren Argumenten an, mit der das Zugriffstoken mit mehreren Argumenten authentifiziert werden soll:
   • Oracle Functions-Anwendung: Der Name der Anwendung in OCI Functions, die die Autorisiererfunktion enthält. Sie können eine Anwendung aus einem anderen Compartment auswählen.
   • Oracle-Funktion: Der Name der Autorisiererfunktion in OCI Functions.
7. Wählen Sie Autorisiererfunktion für mehrere Argumente aus, um anzugeben, dass Sie mindestens ein Element einer Anforderung als Zugriffstoken an eine Autorisiererfunktion übergeben möchten, die Zugriffstoken mit mehreren Argumenten akzeptieren kann.
8. Geben Sie im Bereich Funktionsargumente eine oder mehrere Kontextvariablen an, die Werte zur Übergabe an die Autorisiererfunktion als Argumente mit Argumentnamen angeben, die Sie eingeben:
   1. Geben Sie eine Kontextvariable an, die einen Wert bereitstellt, der als Argument an die Autorisiererfunktion übergeben werden soll:
      • Kontexttabelle: Wählen Sie die Kontexttabelle mit der Kontextvariable aus der Liste aus:
        • Kontexttabelle request.query, die Abfrageparameternamen und -werte enthält, die in der Anforderung enthalten sind
        • Kontexttabelle request.headers, die Headernamen und -werte enthält, die in der Anforderung enthalten sind
        • request.cert-Kontexttabelle, die eine Base64-codierte Version des Zertifikats enthält, die von einem API-Client präsentiert und bei einem mTLS-Handshake erfolgreich validiert wurde
        • request.host-Kontexttabelle mit dem Namen des Hosts, an den die Anforderung gesendet wurde (extrahiert aus dem Host-Headerfeld in der Anforderung)
        • Kontexttabelle request.body, die den Text der Anforderung enthält
      • Headername oder Abfrageparametername: Wenn Sie die Kontexttabelle request.headers oder request.params ausgewählt haben, geben Sie den Namen des Headers oder Abfrageparameters ein, den Sie an die Autorisiererfunktion übergeben möchten. Beispiel: X-Api-Key, state.
      • Argumentname: Geben Sie den Namen des Arguments ein, dem der Wert der Kontextvariable zugewiesen werden soll. Das Argument wird an die Autorisiererfunktion übergeben. Der eingegebene Argumentname muss dem Argumentnamen entsprechen, den die Autorisiererfunktion erwartet.
   2. Geben Sie bei Bedarf zusätzliche Kontextvariablen und Argumente an (wählen Sie bei Bedarf Weiteres Argument aus).

9. Passen Sie optional an, wie die Antwort von einer Autorisiererfunktion mit mehreren Argumenten gecacht wird:

   1. Wählen Sie Erweiterte Optionen aus.

      Im Bereich Funktionsergebnis-Caching wird angezeigt, welche Argumente im Cacheschlüssel vorhanden sind. Der Cacheschlüssel identifiziert die gecachte Antwort, die von der Autorisiererfunktion zurückgegeben wird, eindeutig und verwendet Argumente und Argumentwerte, die in der ursprünglichen Authentifizierungsanforderung übergeben werden. Standardmäßig werden alle Argumente und Argumentwerte (mit Ausnahme eines Arguments mit einem Wert aus der Kontexttabelle request.body), die Sie für die Übergabe an die Autorisiererfunktion angegeben haben, zum Erstellen des Cacheschlüssels verwendet.

   2. Um Argumente zum Cacheschlüssel hinzuzufügen oder daraus zu entfernen, wählen Sie Bearbeiten.
   3. Wählen Sie die an die Autorisiererfunktion übergebenen Argumente aus, oder heben Sie die Auswahl auf, um sie in den Cache-Schlüssel einzuschließen oder aus diesem auszuschließen.

   Siehe Hinweise zum Caching der Ergebnisse der Autorisiererfunktion mit mehreren Argumenten.

10. Passen Sie optional an, wie eine nicht erfolgreiche Authentifizierungsantwort von einer Autorisiererfunktion mit mehreren Argumenten verarbeitet werden soll, indem Sie eine Validierungsfehler-Policy einrichten:

    1. Wählen Sie Erweiterte Optionen aus.

       Im Bereich Benutzerdefinierte Antwort für nicht erfolgreiche Authentifizierung. werden der HTTP-Statuscode und der Meldungstext angezeigt, die an den API-Client zurückgegeben werden, wenn die Autorisiererfunktion die Anforderung nicht authentifizieren kann. Standardmäßig sendet das API-Gateway einen HTTP 401-Statuscode und den WWW-Authenticate-Header in der Antwort. Siehe Hinweise zu Validierungsfehler-Policys und zur Behandlung nicht erfolgreicher Authentifizierungsantworten aus Autorisiererfunktionen mit mehreren Argumenten.

    2. Geben Sie einen Statuscode (und einen optionalen Nachrichtentext) an, um zum API-Client zurückzukehren, wenn die Autorisiererfunktion die Anforderung nicht authentifizieren kann:
       • HTTP-Statuscode: Geben Sie einen alternativen HTTP-Statuscode ein (z.B. 500). Alternativ können Sie eine Kontextvariable einschließen, um den von der Autorisiererfunktion zurückgegebenen Code zurückzugeben. Beispiel: Wenn die Autorisiererfunktion einen Antwortcode im Parameter responseCode zurückgibt, geben Sie request.auth[responseCode] an.
       • Nachrichtentext: Geben Sie einen Nachrichtentext ein. Beispiel: Unfortunately, authentication failed.Der Nachrichtentext kann eine beliebige Kontextvariable enthalten (mit Ausnahme von request.body). Beispiel: Unfortunately, authentication failed ${request.auth[my-auth-variable]}.

    3. Ändern Sie optional die Header der Antwort, die das API-Gateway an den API-Client zurückgibt, indem Sie Erweiterte Optionen auswählen und eine Headertransformationsantwort-Policy angeben:

       • Um die in einer Antwort enthaltenen Header zu begrenzen, geben Sie Folgendes an:

         • Aktion: Filtern.
         • Typ: Entweder Blockieren, um die explizit aufgelisteten Header aus der Antwort zu entfernen, oder Zulassen, um nur die explizit aufgelisteten Header in der Antwort zuzulassen (alle anderen Header werden aus der Antwort entfernt).
         • Headernamen: Die Liste der Header, die aus der Antwort entfernt oder in der Antwort zugelassen werden sollen (je nach der Einstellung im Feld "Typ"). Bei den angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem dürfen sie nicht in anderen Transformationsantwort-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: User-Agent.

       • Um den Namen eines Headers in einer Antwort (unter Beibehaltung des ursprünglichen Wertes) zu ändern, geben Sie Folgendes an:

         • Aktion: Umbenennen.
         • Headername: Der ursprüngliche Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein. Beispiel: X-Username.
         • Neuer Headername: Der neue Name des Headers, den Sie umbenennen möchten. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein (mit Ausnahme der Elemente in ALLOW-Listen). Beispiel: X-User-ID.

       • Um einer Antwort einen neuen Header hinzuzufügen (oder die Werte eines vorhandenen Headers zu ändern oder beizubehalten, der bereits in einer Antwort enthalten ist), geben Sie Folgendes an:

         • Aktion: Festlegen.

         • Verhalten: Wenn der Header bereits vorhanden ist, geben Sie an, was Sie mit dem vorhandenen Wert des Headers tun möchten:

           • Überschreiben, um den vorhandenen Wert des Headers durch den angegebenen Wert zu ersetzen.
           • Anhängen, um den angegebenen Wert an den vorhandenen Wert des Headers anzuhängen.
           • Überspringen, um den vorhandenen Wert des Headers beizubehalten.
         • Headername: Der Name des Headers, der zur Antwort hinzugefügt (oder dessen Wert geändert) werden soll. Bei dem angegebenen Namen muss die Groß-/Kleinschreibung nicht beachtet werden. Außerdem darf er nicht in anderen Transformationsantwort-Policys für die Route enthalten sein (mit Ausnahme der Elemente, die Sie als zugelassen filtern). Beispiel: X-Api-Key.
         • Werte: Der Wert des neuen Headers (oder der Wert, der den Wert eines vorhandenen Headers ersetzen oder daran angehängt werden soll, je nach der Einstellung im Feld Verhalten). Sie können mehrere Werte angeben. Der angegebene Wert kann eine einfache Zeichenfolge sein oder kontextabhängige Variablen enthalten, die in Begrenzungszeichen (${...}) eingeschlossen sind (außer request.body). Beispiel: "value": "zyx987wvu654tsu321".

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

11. Wählen Sie Weiter aus, um Details für einzelne Routen im API-Deployment auf der Seite Routen einzugeben.

12. Wählen Sie Route hinzufügen aus, und geben Sie die erste Route im API-Deployment ein, die einem Backend-Service einen Pfad und eine oder mehrere Methoden zuordnet:

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

      • relativ zum Deployment-Pfadpräfix ist
      • einen Schrägstrich ( / ) vorangestellt haben muss. Es kann nur ein einzelner Schrägstrich verwendet werden
      • mehrere Schrägstriche enthalten (sofern diese nicht aufeinander folgen) und mit einem Schrägstrich enden kann
      • alphanumerische Zeichen in Großbuchstaben und Kleinbuchstaben enthalten kann
      • die folgenden Sonderzeichen enthalten kann: $ - _ . + ! * ' ( ) , % ; : @ & =
      • Parameter und Platzhalter enthalten kann (siehe Pfadparameter und Platzhalter zu Routenpfaden hinzufügen)
    • Methoden: Eine oder mehrere Methoden, die vom Backend-Service akzeptiert werden (durch Komma getrennt). Beispiel: GET, PUT.

    • Ein einzelnes Backend hinzufügen oder Mehrere Backends hinzufügen: Gibt an, ob alle Anforderungen an dasselbe Backend weitergeleitet oder gemäß der eingegebenen Kontextvariablen und Regeln an andere Backends weitergeleitet werden sollen.

      Bei diesen Anweisungen wird davon ausgegangen, dass Sie ein einzelnes Backend verwenden möchten. Wählen Sie daher Ein einzelnes Backend hinzufügen aus. Wenn Sie andere Backends verwenden möchten, wählen Sie alternativ Mehrere Backends hinzufügen aus, und befolgen Sie die Anweisungen unter Dynamische Backend-Auswahl mit der Konsole zu einer API-Deployment-Spezifikation hinzufügen.

    • Backend-Typ: Der Typ des Backend-Service. Folgende Optionen sind verfügbar:
      • HTTP: Bei einem HTTP-Backend müssen Sie auch eine URL und Timeoutdetails angeben. Außerdem müssen Sie angeben, ob die SSL-Überprüfung deaktiviert werden soll (siehe HTTP- oder HTTPS-URL als API-Gateway-Backend hinzufügen).
      • Oracle Functions: Bei einem OCI Functions-Backend müssen Sie auch die Anwendung und Funktion angeben (siehe Funktion in OCI Functions als API-Gateway-Backend hinzufügen).
      • Stockantwort: Bei einem Standardantwort-Backend müssen Sie auch den HTTP-Statuscode, den Inhalt im Hauptteil der Antwort und mindestens eines HTTP-Headerfeldes angeben (siehe Standardantworten als API-Gateway-Backend hinzufügen).
      • Abmeldung: Bei einem Abmelde-Backend müssen Sie auch eine Liste der zulässigen URLs angeben, zu denen eine Anforderung umgeleitet werden kann, um Token zu entziehen, und optional Daten, die an die Abmelde-URL übergeben werden sollen (siehe Abmeldung als API-Gateway-Backend hinzufügen).

13. Um eine Autorisierungs-Policy anzugeben, die für eine einzelne Route gilt, wählen Sie Routenanforderungs-Policys anzeigen und dann die Schaltfläche Hinzufügen neben Autorisierung aus, und geben Sie folgende an:

    • Autorisierungstyp: Gibt an, wie Zugriff auf die Route erteilt werden. Wählen Sie eine der folgenden Optionen aus:

      • Beliebig: Zugriff kann nur Endbenutzern erteilt werden, die erfolgreich authentifiziert wurden, sofern die Autorisiererfunktion auch einen der Zugriffsgeltungsbereiche zurückgegeben hat, die Sie im Feld Zulässigen Geltungsbereich hinzufügen angegeben hat. In diesem Fall zeigt die Option Anonymen Zugang aktivieren der Authentifizierungs-Policy keine Wirkung.
      • Anonym: Zugriff wird allen Endbenutzern erteilt, selbst wenn diese nicht erfolgreich von der Autorisiererfunktion authentifiziert wurden. In diesem Fall müssen Sie die Option Anonymen Zugang aktivieren der Authentifizierungs-Policy ausgewählt haben.
      • Nur Authentifizierung: Zugriff wird nur Endbenutzern erteilt, die von der Autorisiererfunktion erfolgreich authentifiziert wurden. In diesem Fall zeigt die Option Anonymen Zugang aktivieren der Authentifizierungs-Policy keine Wirkung.
    • Zulässigen Geltungsbereich hinzufügen: Wenn Sie Beliebig als Autorisierungstyp ausgewählt haben, geben Sie eine kommagetrennte Liste mit einer oder mehreren Zeichenfolgen ein, die den von der Autorisiererfunktion zurückgegebenen Zugriffsbereichen entsprechen. Zugriff wird nur Endbenutzern erteilt, die erfolgreich authentifiziert wurden, sofern die Autorisiererfunktion einen der angegebenen Zugriffsgeltungsbereiche zurückgibt. Beispiel: read:hello
    Hinweis
    
    

    Wenn Sie keine Autorisierungs-Policy für eine bestimmte Route angeben, wird der Zugriff basierend auf der Akzeptanz erteilt, das eine solche Policy vorhanden ist, und die Autorisierungstyp wird auf Nur Authentifizierung gesetzt. Anders ausgedrückt: Ungeachten der Einstellung der Option Anonymen Zugang aktivieren der Authentifizierungs-Policy:

    • nur authentifizierte Endbenutzer auf die Route zugreifen
    • alle authentifizierten Endbenutzer auf die Route zugreifen, und zwar unabhängig von den Zugriffsgeltungsbereichen, die von der Autorisiererfunktion zurückgegeben werden
    • anonyme Endbenutzer nicht auf die Route zugreifen
14. Wählen Sie Erstellen, Weiter aus, um die Details zu prüfen, die Sie für das API-Deployment eingegeben haben.
15. Wählen Sie Erstellen oder Aktualisieren aus, um das API-Deployment zu erstellen oder aktualisiert zu werden.
16. (Optional) Bestätigen Sie, dass die API erfolgreich bereitgestellt wurde, indem Sie sie aufrufen (siehe In einem API-Gateway bereitgestellte API aufrufen).

So fügen Sie Authentifizierungsanforderungs-Policys und Autorisierungsanforderungs-Policys für Multi-Argument-Zugriffstoken zu einer API-Deployment-Spezifikation in einer JSON-Datei hin:

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 eine authentication-Anforderungs-Policy hinzu, die für alle Routen in der API-Deployment-Spezifikation gilt:

   1. Fügen Sie, falls noch nicht vorhanden, einen requestPolicies-Abschnitt vor dem routes-Abschnitt ein. Beispiel:

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

   2. Fügen Sie die folgende authentication-Policy zum neuen requestPolicies-Abschnitt hinzu.

      {
        "requestPolicies": {
          "authentication": {
            "type": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "functionId": "<function-ocid>",
            "parameters": {
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>"
            },
            "cacheKey": [
              "<cache-key-argument-n>", "<cache-key-argument-n>"
            ]
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      Dabei gilt:

      • <type-value> ist der Authentifizierungstyp. Um eine Autorisiererfunktion für die Authentifizierung zu verwenden, geben Sie CUSTOM_AUTHENTICATION an.
      • "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".
      • <function-ocid> ist die OCID der Autorisiererfunktion, die in OCI Functions bereitgestellt wird.
      • <argument-n> ist der Name des Arguments, dem der Wert einer einzigen Kontextvariablen zugewiesen werden soll. Das Argument wird an die Autorisiererfunktion übergeben. Der eingegebene Argumentname muss dem Argumentnamen entsprechen, den die Autorisiererfunktion erwartet. Sie können mehrere Variablenpaare für Argument/Kontext einschließen.
      • <context-variable> ist eine Kontextvariable, deren Wert Sie dem entsprechenden Argument zuweisen möchten. <context-variable> muss das Format <context-table-name> oder <context-table-name>[<key>] aufweisen, wobei <context-table-name> einer der folgenden Werte ist:
        • request.query, eine Kontexttabelle mit Abfrageparameternamen und -werten, die in der Anforderung enthalten sind. Wenn Sie einen Abfrageparameter angeben möchten, müssen Sie sowohl die Kontexttabelle request.query als auch den Namen des Abfrageparameters als Schlüssel im Format request.query[<query-parameter-name>] angeben. Beispiel: request.query[state]
        • request.headers, eine Kontexttabelle mit Headernamen und -werten, die in der Anforderung enthalten sind. Wenn Sie einen Header angeben möchten, müssen Sie sowohl die Kontexttabelle request.headers als auch den Namen des Headers als Schlüssel im Format request.headers[<header-name>] angeben. Beispiel: request.headers[X-Api-Key]
        • request.cert-Kontexttabelle, die eine Base64-codierte Version des Zertifikats enthält, die von einem API-Client präsentiert und bei einem mTLS-Handshake erfolgreich validiert wurde
        • request.host, eine Kontexttabelle mit dem Namen des Hosts, an den die Anforderung gesendet wurde (extrahiert aus dem Host-Headerfeld in der Anforderung)
        • request.body, eine Kontexttabelle mit dem Text der Anforderung.
      • "cacheKey": ["<cache-key-argument-n>", "<cache-key-argument-n>"] beschränkt den Cacheschlüssel optional auf die Verwendung der angegebenen Argumente. Der Cacheschlüssel identifiziert die gecachte Antwort, die von der Autorisiererfunktion zurückgegeben wird, eindeutig und verwendet Argumente und Argumentwerte, die in der ursprünglichen Authentifizierungsanforderung übergeben werden. Standardmäßig werden alle Argumente und Argumentwerte (mit Ausnahme eines Arguments mit einem Wert aus der Kontexttabelle request.body) in der Liste parameters: {…} zum Erstellen des Cacheschlüssels verwendet. Ein Argument, das Sie für <cache-key-argument-n> angeben, muss eines der Argumente in der Liste parameters: {…} sein. Siehe Hinweise zum Caching der Ergebnisse der Autorisiererfunktion mit mehreren Argumenten.
   3. Fügen Sie optional eine validationFailurePolicy zum Policy-Abschnitt authentication hinzu:

      {
        "requestPolicies": {
          "authentication": {
            "type": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "functionId": "<function-ocid>",
            "parameters": {
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>",
              "<argument-n>": "<context-variable>"
            },
            "cacheKey": [
              "<cache-key-argument-n>", "<cache-key-argument-n>"
            ],
            "validationFailurePolicy": {
              "type": "MODIFY_RESPONSE",
              "responseCode": "<alternative-response-code>",
              "responseMessage": "<custom-message-body>",
              "responseTransformations": {
                "headerTransformations": {
                  <valid-header-transformation-response-policy>
                }
              }
            }
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      Dabei gilt:

      • Mit "validationFailurePolicy": {…} können Sie optional den HTTP-Statuscode, den Nachrichtentext und die Header in der Antwort auf den API-Client ändern, wenn die Autorisiererfunktion eine Anforderung nicht authentifizieren kann. Standardmäßig sendet das API-Gateway einen HTTP 401-Statuscode und den WWW-Authenticate-Header in der Antwort. Siehe Hinweise zu Validierungsfehler-Policys und zur Behandlung nicht erfolgreicher Authentifizierungsantworten aus Autorisiererfunktionen mit mehreren Argumenten.
      • <policy-type> ist der Typ der Validierungsfehler-Policy. Um die Antwort zu ändern, geben Sie MODIFY_RESPONSE an.
      • "responseCode": "<alternative-response-code>" gibt einen alternativen HTTP-Statuscode an. Beispiel: "responseCode": "500". Alternativ können Sie eine Kontextvariable einschließen, um den von der Autorisiererfunktion zurückgegebenen Code zurückzugeben. Beispiel: Wenn die Autorisiererfunktion einen Antwortcode im Parameter responseCode zurückgibt, geben Sie "request.auth[responseCode]" an.
      • "responseMessage": "<custom-message-body>" gibt den Inhalt an, der in den Nachrichtentext aufgenommen werden soll. Beispiel: "responseMessage": "Unfortunately, authentication failed.". Der Nachrichtentext kann eine beliebige Kontextvariable enthalten (außer request.body). Beispiel: "responseMessage": "Unfortunately, authentication failed ${request.auth[my-auth-variable]}".
      • "headerTransformations": {<valid-header-transformation-response-policy>} ist eine gültige Headertransformationsantwort-Policy. Siehe Headertransformationsantwort-Policys hinzufügen.

3. 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": "CUSTOM_AUTHENTICATION",
            .
            .
            .
          }
        },
        "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 requestPolicies-Abschnitt hinzu:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            .
            .
            .
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
                "allowedScope": [ "<scope>" ]
              }
            }
          }
        ]
      }

      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 die Autorisiererfunktion auch einen der Zugriffsgeltungsbereiche zurückgegeben hat, die Sie in der Eigenschaft allowedScope angegeben haben. 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 den von der Autorisiererfunktion zurückgegebenen Zugriffsbereichen 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 von Ihnen angegebenen Geltungsbereiche von der Autorisiererfunktion zurückgegeben wird.

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

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            .
            .
            .
          }
        },
        "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 auf die Route zugreifen, und zwar unabhängig von den Zugriffsgeltungsbereichen, die von der Autorisiererfunktion zurückgegeben werden
   • anonyme Endbenutzer nicht auf die Route zugreifen
4. Speichern Sie die JSON-Datei, die die API-Deployment-Spezifikation enthält.

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

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

Die folgende API-Deployment-Spezifikation definiert:

• Eine Authentifizierungsanforderungs-Policy, die eine Autorisiererfunktion mit mehreren Argumenten zur Ausführung der Authentifizierung aufruft.
• Eine Autorisierungsanforderungs-Policy, die angibt, welche Aktionen authentifizierte Endbenutzer ausführen können.

{
  "requestPolicies": {
    "authentication": {
      "type": "CUSTOM_AUTHENTICATION",
      "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
      "isAnonymousAccessAllowed": true,
      "parameters": {
        "xapikey": "request.headers[X-Api-Key]",
        "referer": "request.headers[Referer]",
        "state": "request.query[state]",
        "city": "request.query[city]",
        "cert": "request.cert",
        "body": "request.body",
        "host": "request.host"
        },
      "cacheKey": [
        "xapikey", "referer"
        ],
      "validationFailurePolicy": {
        "type": "MODIFY_RESPONSE",
        "responseCode": "request.auth[responseCode]",
        "responseMessage": "Unfortunately, authentication failed.",
        "responseTransformations": {
        "headerTransformations": {
          "setHeaders": {
            "items": [
              {
                "name": "Location",
                "values": [
                  "${request.auth[location]}"
                  ]
                }
              ]
            },
          "filterHeaders": {
            "type": "BLOCK",
            "items": [
              {
                "name": "topSecret"
                }
              ]
            }
          }
        }
      }
    }
  },
  "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" ]
        }
      }
    }
  ]
}

Die Authentifizierungsanforderungs-Policy in dieser API-Deployment-Spezifikation:

• Gibt die Autorisiererfunktion mit mehreren Argumenten an, die zum Ausführen der Authentifizierung aufgerufen werden soll, und definiert die Argumente xapikey, referer, state, city, cert, body und host, die an die Autorisiererfunktion übergeben werden sollen. Die Werte dieser Argumente werden aus Kontextvariablen abgerufen, die Werte aus der ursprünglichen Anforderung enthalten.
• Definiert einen benutzerdefinierten Cacheschlüssel zur eindeutigen Identifizierung der gecachten Antwort, die von der Autorisiererfunktion zurückgegeben wird. Anstatt den Standardcacheschlüssel (der alle an die Autorisiererfunktion gesendeten Argumente enthält und empfohlen wird) zu verwenden, gibt diese Authentifizierungsanforderungs-Policy an, dass der Cacheschlüssel nur die Werte der an die Autorisiererfunktion übergebenen Argumente xapikey und referrer umfassen soll.
• Enthält eine Validierungsfehler-Policy, mit der die Standardantwort auf Validierungsfehler geändert wird, um den Standardstatuscode HTTP 401 durch den Wert der Kontextvariablen request.auth[responseCode] zu ersetzen. Die Kontextvariable request.auth[responseCode] enthält den Wert eines Authentifizierungsparameters (in diesem Fall responseCode), der von der Autorisiererfunktion zurückgegeben wird. Entsprechend wird die Standard-Validierungsfehlermeldung durch eine benutzerdefinierte Meldungszeichenfolge ("Unfortunately, authentication failed.") ersetzt.
• Enthält eine Headertransformationsanforderungs-Policy in der Validierungsfehler-Policy, die den location-Header zur Antwort auf den Validierungsfehler hinzufügt. Der location-Header erhält den Wert der Kontextvariablen request.auth[location], die den Wert eines Authentifizierungsparameters (in diesem Fall location) enthält, der von der Autorisiererfunktion zurückgegeben wird. Die Headertransformationsanforderungs-Policy entfernt auch Header mit dem Namen topSecret aus der Antwort.

Mit der Autorisierungsanforderungs-Policy in dieser API-Deployment-Spezifikation können Endbenutzer, die von der Autorisiererfunktion und mit dem Geltungsbereich read:hello authentifiziert wurden, nur auf die Route /hello zugreifen.