Authentifizierungs- und Autorisierungsanforderungs-Policys für Single-Argument-Zugriffstoken und Autorisiererfunktionen hinzufügen

So fügen Sie Authentifizierungsanforderungs-Policys und Autorisierungsanforderungs-Policys für Einzelargumentzugriffstoken zu einer API-Deployment-Spezifikation mit der Konsole 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 einem Argument an, die zur Authentifizierung des Zugriffstokens mit einem Argument verwendet 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.
   • Funktionsname: Den Namen der Autorisiererfunktion in OCI Functions.
7. Wählen Sie Autorisiererfunktion mit einem Argument aus, um anzugeben, dass Sie ein Zugriffstoken mit einem Argument in einem Header oder Abfrageparameter an eine Autorisiererfunktion mit einem Argument übergeben möchten.
8. Geben Sie im Bereich Zugriffstoken das Zugriffstoken an, das für die Authentifizierung verwendet werden soll:
   • Tokenspeicherort: Wählen Sie Header oder Abfrageparameter aus, um den Speicherort des Zugriffstokens in der Anforderung anzugeben.
   • Tokenheadername oder Tokenparametername: Geben Sie je nach Speicherort des Zugriffstokens den Namen des Headers oder Abfrageparameters ein, der das Zugriffstoken enthält.

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

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

11. Um eine Autorisierungs-Policy anzugeben, die für eine einzelne Route gilt, wählen Sie Routenanforderungs-Policys anzeigen aus, wählen Sie 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 mindestens einer Zeichenfolge, die den von der Autorisiererfunktion zurückgegebenen Zugriffsgeltungsbereichen entspricht. 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
12. Wählen Sie Erstellen, Weiter aus, um die Details zu prüfen, die Sie für das API-Deployment eingegeben haben.
13. Wählen Sie Erstellen oder Aktualisieren aus, um das API-Deployment zu erstellen oder aktualisiert zu werden.
14. (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 Einzelargument-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>",
            <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">
          }
        },
        "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.
      • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> gibt an, ob es sich um einen Anforderungsheader handelt, der das Zugriffstoken enthält (wenn ja, wird der Name des Headers angegeben), oder ob es sich um einen Abfrageparameter handelt, der das Zugriffstoken enthält (wenn ja, wird der Name des Abfrageparameters angegeben). Beachten Sie, dass Sie entweder "tokenHeader": "<token-header-name>" oder "tokenQueryParam": "<token-query-param-name>"> angeben können, aber nicht beides.

      Beispiel: Die folgende authentication-Policy gibt eine OCI-Funktion an, mit der das Zugriffstoken im Autorisierungsanforderungsheader validiert wird:

      {
        "requestPolicies": {
          "authentication": {
            "type": "CUSTOM_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

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",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "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",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "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",
            "isAnonymousAccessAllowed": false,
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
            "tokenHeader": "Authorization"
          }
        },
        "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).