Autorisiererfunktion erstellen

So erstellen Sie eine Autorisiererfunktion, die ein benutzerdefiniertes Zugriffstoken mit mehreren Argumenten akzeptiert:

1. Schreiben Sie Code in die Autorisiererfunktion, der JSON im folgenden Format als Eingabe aus API-Gateway akzeptiert:

   
   {
     "type": "USER_DEFINED",
     "data": {
       "<argument-n>": "<context-variable-value>",
       "<argument-n>": "<context-variable-value>",
       "<argument-n>": "<context-variable-value>"
     }
   }

   Dabei gilt:

   • "type": "USER_DEFINED" gibt an, dass die Argumente und Werte, die an die Autorisiererfunktion übergeben werden, in der API-Deployment-Spezifikation definiert sind.
   • "<argument-n>" ist ein Argumentname, der einem benutzerdefinierten Argumentnamen entspricht, der im Abschnitt parameters der API-Deployment-Spezifikation angegeben ist. Beispiel: "state", "xapikey"
   • "<context-variable-value>" ist der Wert der Kontextvariablen, die im Abschnitt parameters der API-Deployment-Spezifikation angegeben ist. Beispiel: Der Wert der Kontextvariable des Abfrageparameters request.query[state], der Wert der Kontextvariable des request.headers[X-Api-Key]-Headerparameters. Wenn Sie mehrere Werte aus Anforderungsheadern und Abfrageparametern an die Autorisiererfunktion übergeben, wird "<context-variable-value>" als Array an die Autorisiererfunktion übergeben. Wenn der Wert für eine Kontextvariable nicht in der ursprünglichen Anforderung an das API-Gateway vorhanden ist, wird die Kontextvariable nicht an die Autorisiererfunktion übergeben.

   Beispiel: Sie möchten, dass die Autorisiererfunktion die Werte der Kontextvariablen für den Abfrageparameter request.query[state] und die Kontextvariable für den Headerparameter request.headers[X-Api-Key] als Eingabe aus API Gateway akzeptiert. Beispiel: Wenn die Werte der Kontextvariablen für den Abfrageparameter request.query[state] und der Kontextvariablen für den Headerparameter request.headers[X-Api-Key] california bzw. abc123def456fhi789 lauten, muss die Autorisiererfunktion die folgende JSON-Eingabe akzeptieren:

   
   {
     "type": "USER_DEFINED",
     "data": {
       "state": "california",
       "xapikey": "abc123def456fhi789"
     }
   }

   Wenn der X-API-Key-Header nicht in der ursprünglichen Anforderung an das API-Gateway vorhanden ist, wird die Kontextvariable xapikey überhaupt nicht an die Autorisiererfunktion übergeben (und nicht mit einem Nullwert übergeben).

2. Schreiben Sie Code in die Autorisiererfunktion, der die folgende JSON als HTTP 200-Antwort an API Gateway zurückgibt, wenn das benutzerdefinierte Zugriffstoken mit mehreren Argumenten erfolgreich mit einem Identitätsprovider verifiziert wurde und der Identitätsprovider bestimmt hat, dass das Token gültig ist:

   {
     "active": true,
     "scope": ["<scopes>"],
     "expiresAt": "<date-time>",
     "context": {
       "<key>": "<value>", ... 
     }
   }

   Dabei gilt:

   • "active": true gibt an, dass der Identitätsprovider ermittelt hat, dass das ursprünglich an die Autorisiererfunktion übergebene Zugriffstoken gültig ist. Beachten Sie, dass dieses boolesche Feld optional ist, aber standardmäßig false lautet, wenn es nicht in der JSON-Antwort enthalten ist.
   • "scope": ["<scopes>"] ist optional die Zugriffsgeltungsbereiche, die von der Autorisiererfunktion vom Identitätsprovider abgerufen werden. Beachten Sie, dass ["<scopes>"] entweder ein JSON-Array mit durch Komma getrennten Zeichenfolgen, wie ["list:hello", "read:hello", "create:hello"], oder eine durch Leerzeichen getrennte Zeichenfolge wie "list:hello read:hello create:hello" sein kann. Beachten Sie, dass dieses Feld erforderlich ist, wenn die Eigenschaft type der Autorisierungsanforderungs-Policy auf ANY_OF gesetzt ist.
   • "expiresAt": "<date-time>" ist optional eine Datums-/Uhrzeitzeichenfolge im ISO-8601-Format, die angibt, wann das Zugriffstoken, das ursprünglich an die Autorisiererfunktion übergeben wurde, abläuft. Dieser Wert wird verwendet, wenn bestimmt wird, wie lange Ergebnisse nach dem Aufruf der Autorisiererfunktion gecacht werden sollen. Sie können Ergebnisse für mindestens 60 Sekunden und maximal 1 Stunde cachen. Wenn dieses Feld nicht in der JSON-Antwort enthalten ist oder "<date-time>" ungültig ist, werden die Ergebnisse 60 Sekunden lang im Cache gespeichert.
   • "context": {"<key>": "<value>", ... } ist eine optionale durch Komma getrennte Liste von Schlüsselwertpaaren im JSON-Format, die an API-Gateway zurückgegeben werden sollen. Die Autorisiererfunktion kann ein beliebiges Schlüssel/Wert-Paar zur Verwendung durch das API-Deployment zurückgeben (z.B. den Benutzernamen oder die E-Mail-Adresse des Endbenutzers). Weitere Informationen zur Verwendung des Wertes in dem Schlüssel/Wert-Paar, das von einer Autorisiererfunktion als Kontextvariable in einer HTTP-Backend-Definition zurückgegeben wird, finden Sie unter Kontextabhängige Variablen zu Policys und HTTP-Backend-Definitionen hinzufügen.

   Beispiel:

   {
     "active": true,
     "scope": ["list:hello", "read:hello", "create:hello", "update:hello", "delete:hello", "someScope"],
     "expiresAt": "2019-05-30T10:15:30+01:00",
     "context": {
       "email": "john.doe@example.com"
     }
   }

   Wenn die Autorisiererfunktion eine HTTP 200-Antwort und active: true im JSON-Body der Antwort zurückgibt, gibt API Gateway eine HTTP 200-Antwort an den API-Client zurück.

3. Schreiben Sie Code in die Autorisiererfunktion, der die folgende JSON als HTTP 200-Antwort an API Gateway zurückgibt, wenn das benutzerdefinierte Zugriffstoken mit mehreren Argumenten erfolgreich mit einem Identitätsprovider verifiziert wurde, der Identitätsprovider jedoch festgestellt hat, dass das Token ungültig ist:

   {
     "active": false,
     "wwwAuthenticate": "<directive>"
   }

   Dabei gilt:

   • "active": false gibt an, dass der Identitätsprovider ermittelt hat, dass das ursprünglich an die Autorisiererfunktion übergebene Zugriffstoken ungültig ist. Beachten Sie, dass dieses Feld optional ist. Der Standardwert ist jedoch false, wenn es nicht in der JSON-Antwort vorhanden ist.
   • "wwwAuthenticate": "<directive>" ist optional der Wert des WWW-Authenticate-Header, der von der Autorisiererfunktion zurückgegeben werden soll, wenn das Zugriffstoken ungültig ist. Dabei wird auf den erforderlichen Authentifizierungstyp hingewiesen (z.B. "Basis" oder "Bearer". Beispiel: "wwwAuthenticate": "Bearer realm=\"example.com\"". Weitere Informationen finden Sie unter RFC 2617 HTTP-Authentifizierung: Basis- und Digest-Access-Authentifizierung.

   Beispiel:

   {
     "active": false,
     "wwwAuthenticate": "Bearer realm=\"example.com\""
   }

   Sie können optional einen validationFailurePolicy-Abschnitt in die API-Deployment-Spezifikation aufnehmen, um den Antwortcode, die Antwortnachricht und die Antwortheader zu ändern, die an den API-Client zurückgegeben werden. Wenn Sie keinen validationFailurePolicy-Abschnitt einschließen, gibt API Gateway den WWW-Authenticate-Header in der Antwort an den API-Client zusammen mit einem 401-Statuscode zurück. Siehe Notizen zu Validierungsfehler-Policys und Behandlung nicht erfolgreicher Authentifizierungsantworten aus Autorisiererfunktionen mit mehreren Argumenten.

4. Schreiben Sie Code in die Autorisiererfunktion, der eine HTTP 5xx-Antwort zurückgibt, wenn das Token nicht mit dem Identitätsprovider verifiziert werden konnte (also nicht bekannt ist, ob das Token gültig oder ungültig ist), oder im Falle eines Fehlers in der Autorisiererfunktion oder in OCI Functions.

   Wenn die Autorisiererfunktion eine HTTP 5xx-Antwort zurückgibt, gibt API Gateway eine HTTP 502-Antwort an den API-Client zurück. Jede JSON im Text der Antwort wird ignoriert.

So erstellen Sie eine Autorisiererfunktion, die ein Zugriffstoken mit einem Argument akzeptiert, das einen einzelnen Wert enthält, der in einem Anforderungsheader oder Abfrageparameter enthalten ist:

1. Schreiben Sie Code in die Autorisiererfunktion, der die folgende JSON-Eingabe aus API-Gateway akzeptiert:

   
   {
     "type": "TOKEN",
     "token": "<token-value>"
   }

   Dabei gilt:

   • "type": "TOKEN" gibt an, dass der an die Autorisiererfunktion übergebene Wert ein Authentifizierungstoken ist.
   • "token": "<token-value>" ist das Authentifizierungstoken, das an die Autorisiererfunktion übergeben wird.

   Beispiel:

   
   {
     "type": "TOKEN",
     "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1nHyDtTwR3SEJ3z489..."
   }

2. Schreiben Sie Code in die Autorisiererfunktion, der die folgende JSON als HTTP 200-Antwort an API Gateway zurückgibt, wenn das Zugriffstoken erfolgreich mit einem Identitätsprovider verifiziert wurde und der Identitätsprovider festgestellt hat, dass das Token gültig ist:

   {
     "active": true,
     "scope": ["<scopes>"],
     "expiresAt": "<date-time>",
     "context": {
       "<key>": "<value>", ... 
     }
   }

   Dabei gilt:

   • "active": true gibt an, dass der Identitätsprovider ermittelt hat, dass das ursprünglich an die Autorisiererfunktion übergebene Zugriffstoken gültig ist. Beachten Sie, dass dieses boolesche Feld optional ist, aber standardmäßig false lautet, wenn es nicht in der JSON-Antwort enthalten ist.
   • "scope": ["<scopes>"] ist optional die Zugriffsgeltungsbereiche, die von der Autorisiererfunktion vom Identitätsprovider abgerufen werden. Beachten Sie, dass ["<scopes>"] entweder ein JSON-Array mit durch Komma getrennten Zeichenfolgen, wie ["list:hello", "read:hello", "create:hello"], oder eine durch Leerzeichen getrennte Zeichenfolge wie "list:hello read:hello create:hello" sein kann. Beachten Sie, dass dieses Feld erforderlich ist, wenn die Eigenschaft type der Autorisierungsanforderungs-Policy auf ANY_OF gesetzt ist.
   • "expiresAt": "<date-time>" ist optional eine Datums-/Uhrzeitzeichenfolge im ISO-8601-Format, die angibt, wann das Zugriffstoken, das ursprünglich an die Autorisiererfunktion übergeben wurde, abläuft. Dieser Wert wird verwendet, wenn bestimmt wird, wie lange Ergebnisse nach dem Aufruf der Autorisiererfunktion gecacht werden sollen. Sie können Ergebnisse für mindestens 60 Sekunden und maximal 1 Stunde cachen. Wenn dieses Feld nicht in der JSON-Antwort enthalten ist oder "<date-time>" ungültig ist, werden die Ergebnisse 60 Sekunden lang im Cache gespeichert.
   • "context": {"<key>": "<value>", ... } ist eine optionale durch Komma getrennte Liste von Schlüsselwertpaaren im JSON-Format, die an API-Gateway zurückgegeben werden sollen. Die Autorisierungsfunktion kann jedes Schlüsselwertpaar zur Verwendung durch das API-Deployment zurückgeben (z.B. den Benutzernamen oder die E-Mail-Adresse eines Endbenutzers). Weitere Informationen zur Verwendung des Wertes in dem Schlüssel/Wert-Paar, das von einer Autorisiererfunktion als Kontextvariable in einer HTTP-Backend-Definition zurückgegeben wird, finden Sie unter Kontextabhängige Variablen zu Policys und HTTP-Backend-Definitionen hinzufügen.

   Beispiel:

   {
     "active": true,
     "scope": ["list:hello", "read:hello", "create:hello", "update:hello", "delete:hello", "someScope"],
     "expiresAt": "2019-05-30T10:15:30+01:00",
     "context": {
       "email": "john.doe@example.com"
     }
   }

   Wenn die Autorisiererfunktion eine HTTP 200-Antwort und active: true im JSON-Body der Antwort zurückgibt, gibt API Gateway eine HTTP 200-Antwort an den API-Client zurück.

   Beachten Sie, dass die Antwort von der Autorisierungsfunktion mit einem Argument dasselbe Format hat wie eine Antwort von einer Autorisierungsfunktion mit mehreren Argumenten (siehe Autorisierungsfunktion mit mehreren Argumenten erstellen (empfohlen)).

3. Schreiben Sie Code in die Autorisiererfunktion, der die folgende JSON als HTTP 200-Antwort an API Gateway zurückgibt, wenn das Zugriffstoken erfolgreich mit einem Identitätsprovider verifiziert wurde, der Identitätsprovider jedoch festgestellt hat, dass das Token ungültig ist:

   {
     "active": false,
     "wwwAuthenticate": "<directive>"
   }

   Dabei gilt:

   • "active": false gibt an, dass der Identitätsprovider ermittelt hat, dass das ursprünglich an die Autorisiererfunktion übergebene Zugriffstoken ungültig ist. Beachten Sie, dass dieses Feld optional ist. Der Standardwert ist jedoch false, wenn es nicht in der JSON-Antwort vorhanden ist.
   • "wwwAuthenticate": "<directive>" ist optional der Wert des WWW-Authenticate-Header, der von der Autorisiererfunktion zurückgegeben werden soll, wenn das Zugriffstoken ungültig ist. Dabei wird auf den erforderlichen Authentifizierungstyp hingewiesen (z.B. "Basis" oder "Bearer". Beispiel: "wwwAuthenticate": "Bearer realm=\"example.com\"". Weitere Informationen finden Sie unter RFC 2617 HTTP-Authentifizierung: Basis- und Digest-Access-Authentifizierung.

   Beispiel:

   {
     "active": false,
     "wwwAuthenticate": "Bearer realm=\"example.com\""
   }

   API Gateway gibt den WWW-Authenticate-Header in der Antwort an den API-Client zusammen mit einem 401-Statuscode zurück.

   Beachten Sie, dass die Antwort von der Autorisierungsfunktion mit einem Argument dasselbe Format hat wie eine Antwort von einer Autorisierungsfunktion mit mehreren Argumenten (siehe Autorisierungsfunktion mit mehreren Argumenten erstellen (empfohlen)).

4. Schreiben Sie Code in die Autorisiererfunktion, der eine HTTP 5xx-Antwort zurückgibt, wenn das Token nicht mit dem Identitätsprovider verifiziert werden konnte (also nicht bekannt ist, ob das Token gültig oder ungültig ist), oder im Falle eines Fehlers in der Autorisiererfunktion oder in OCI Functions.

   Wenn die Autorisiererfunktion eine HTTP 5xx-Antwort zurückgibt, gibt API Gateway eine HTTP 502-Antwort an den API-Client zurück. Jede JSON im Text der Antwort wird ignoriert.

Ein zugehöriges Entwicklertutorial mit einem Beispiel für eine Autorisiererfunktion finden Sie unter Funktionen: API-Schlüssel mit API-Gateway validieren.