REST-API mit einem Amazon Cognito-Benutzerpool integrieren

Nach der Erstellung eines Amazon Cognito-Benutzerpools müssen Sie in API Gateway einen COGNITO_USER_POOLS-Genehmiger erstellen, der den Benutzerpool verwendet. Im folgenden Verfahren wird gezeigt, wie Sie dies mithilfe der API-Gateway-Konsole tun.

Anmerkung

Sie können mit der CreateAuthorizer-Aktion einen COGNITO_USER_POOLS-Autorisierer erstellen, der mehrere Benutzerpools verwendet. Sie können bis zu 1 000 Benutzerpools für einen COGNITO_USER_POOLS-Autorisierer verwenden. Dieses Limit kann nicht erhöht werden.

Wichtig

Nachdem Sie eines der folgenden Verfahren durchgeführt haben, müssen Sie Ihre API bereitstellen oder erneut bereitstellen, um die Änderungen zu übernehmen. Weitere Informationen zum Bereitstellen Ihrer API finden Sie unter RESTAPIsIn API Gateway bereitstellen.

So erstellen Sie einen `COGNITO_USER_POOLS`-Genehmiger unter Verwendung der API Gateway-Konsole:

Erstellen Sie eine neue API oder wählen Sie eine vorhandene API in API Gateway aus.
Wählen Sie im Hauptnavigationsbereich Genehmiger.
Wählen Sie Genehmiger erstellen aus.
Zur Konfiguration des neuen Genehmigers für die Verwendung eines Benutzerpools führen Sie die folgenden Schritte aus:
1. Geben Sie unter Name des Genehmigers einen Namen ein.
2. Wählen Sie als Genehmiger-Typ Cognito aus.
3. Wählen Sie für den Cognito-Benutzerpool den Ort aus, AWS-Region an dem Sie Ihren Amazon Cognito erstellt haben, und wählen Sie einen verfügbaren Benutzerpool aus.
  
  Sie können eine Stufenvariable verwenden, um Ihren Benutzerpool zu definieren. Verwenden Sie das folgende Format für Ihren Benutzerpool:arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}.
4. Geben Sie für Token-Quelle als Header-Name Authorization ein, um das Identitäts- oder Zugriffstoken zu übergeben, das von Amazon Cognito bei erfolgreicher Anmeldung eines Benutzers zurückgegeben wird.
5. Optional können Sie einen regulären Ausdruck im Feld Tokenvalidierung eingeben, um das aud-Feld (Zielgruppe) des Identitätstokens auszuwerten, bevor die Anfrage mit Amazon Cognito genehmigt wird. Beachten Sie, dass diese Validierung bei Verwendung eines Zugriffstoken die Anforderung zurückweist, da das Zugriffstoken das aud-Feld nicht enthält.
6. Wählen Sie Genehmiger erstellen aus.
Nach der Erstellung des COGNITO_USER_POOLS-Genehmigers können Sie einen optionalen Testaufruf durchführen, indem Sie ein vom Benutzerpool bereitgestelltes Identitätstoken übergeben. Sie können dieses Identitätstoken erhalten, indem Sie das Amazon Cognito Identity-SDK aufrufen, um die Benutzeranmeldung durchzuführen. Sie können auch die InitiateAuth-Aktion verwenden. Wenn Sie keine Genehmigungsbereiche konfigurieren, behandelt API Gateway das bereitgestellte Token als Identitätstoken.

Das vorhergehende Verfahren erstellt einen COGNITO_USER_POOLS-Genehmiger, der den neu erstellten Amazon Cognito-Benutzerpool verwendet. Je nach der Aktivierungsweise des Genehmigers mit einer API-Methode können Sie entweder ein Identitäts- oder Zugriffstoken verwenden, das vom integrierten Benutzerpool bereitgestellt wird.

So konfigurieren Sie einen `COGNITO_USER_POOLS`-Genehmiger mit Methoden

Wählen Sie Resources aus. Wählen Sie eine neue oder eine vorhandene Methode aus. Falls erforderlich, erstellen Sie eine Ressource.
Wählen Sie auf der Registerkarte Methodenanfrage unter Methodenanfrage-Einstellungen die Option Bearbeiten aus.
Wählen Sie für Genehmiger aus dem Dropdown-Menü die Amazon-Cognito-Benutzerpool-Genehmiger, die Sie soeben erstellt haben.
Zur Verwendung eines Identitätstokens führen Sie die folgenden Schritte aus:
1. Lassen Sie das Feld Genehmigungsbereiche leer.
2. Fügen Sie bei Bedarf unter Integrationsanforderung den Ausdruck $context.authorizer.claims['property-name'] oder $context.authorizer.claims.property-name in einer Text-Mapping-Vorlage hinzu, um die angegebene Eigenschaft für Identitätsansprüche vom Benutzerpool an das Backend zu übergeben. Bei einfachen Eigenschaftsnamen (wie z. B. sub oder custom-sub) sind beide Notationen gleich. Bei komplexen Eigenschaftsnamen (wie z. B. custom:role) darf keine punktierte Schreibweise verwendet werden. Beispielsweise werden die Standardfelder sub und email des Anspruchs mit den folgenden Mapping-Ausdrücken an das Backend übergeben:
```
{
	"context" : {
		"sub" : "$context.authorizer.claims.sub",
		"email" : "$context.authorizer.claims.email"
	}
}
```
  Wenn Sie bei der Konfiguration des Benutzerpools ein Feld für einen benutzerdefinierten Anspruch deklariert haben, können Sie auf die gleiche Art auf die benutzerdefinierten Felder zugreifen. Im folgenden Beispiel wird das benutzerdefinierte Feld role eines Anspruchs abgerufen:
```
{
	"context" : {
		"role" : "$context.authorizer.claims.role"
    }
}
```
  Wurde das Feld für den benutzerdefinierten Anspruch mit custom:role deklariert, verwenden Sie folgendes Beispiel für den Abruf der Anspruchseigenschaft:
```
{
	"context" : {
		"role" : "$context.authorizer.claims['custom:role']"
    }
}
```
Zur Verwendung eines Zugriffstokens führen Sie die folgenden Schritte aus:
1. Geben Sie für Genehmigungsbereiche einen oder mehrere vollständige Namen eines Bereichs ein, der bei der Erstellung des Amazon-Cognito-Benutzerpools konfiguriert wurde. Im Beispiel, das in Amazon Cognito-Benutzerpool für eine REST-API erstellen gezeigt wurde, ist einer der Bereiche beispielsweise https://my-petstore-api.example.com/cats.read.
  
  Bei Laufzeit ist der Methodenaufruf dann erfolgreich, wenn ein Bereich, der in diesem Schritt in der Methode angegeben wird, einem Bereich entspricht, der im eingehenden Token beantragt wird. Andernfalls schlägt der Aufruf mit einer 401 Unauthorized-Antwort fehl.
2. Wählen Sie Speichern.
Wiederholen Sie diese Schritte für weitere Methoden Ihrer Wahl.

Wenn beim COGNITO_USER_POOLS-Genehmiger die Option OAuth Scopes nicht angegeben wird, behandelt Amazon API Gateway den angegebenen Token als Identitätstoken und bestätigt die beantragte Identität mit der aus dem Benutzerpool. Andernfalls behandelt API Gateway den angegebenen Token als Zugriffstoken und prüft die im Token beanspruchten Zugriffsbereiche gegen die in der Methode deklarierten Autorisierungsbereiche.

Statt die API Gateway-Konsole zu verwenden, können Sie auch einen Amazon Cognito-Benutzerpool für eine Methode aktivieren, indem Sie eine OpenAPI-Definitionsdatei angeben und die API-Definition in API Gateway importieren.

So importieren Sie einen COGNITO_USER_POOLS-Genehmiger mit einer Swagger-Definitionsdatei

Erstellen (oder exportieren) Sie eine Swagger-Definitionsdatei für Ihre API.

Geben Sie die COGNITO_USER_POOLS -Genehmiger (MyUserPool) -Definition als Teil der JSON- securitySchemes Abschnitt in OpenAPI 3.0 oder den securityDefinitions Abschnitt im Open API-2.0 wie folgt an:

Wenn Sie den Identitätstoken für die Methodenautorisierung verwenden möchten, fügen Sie der { "MyUserPool": [] }-Definition der Methode security hinzu, wie in der folgenden GET-Methode auf der Root-Ressource dargestellt.


  "paths": {
    "/": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "text/html"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Content-Type": {
                "type": "string"
              }
            }
          }
        },
        "security": [
          {
            "MyUserPool": []
          }
        ],        
        "x-amazon-apigateway-integration": {
          "type": "mock",
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Content-Type": "'text/html'"
              },
            }
          },
          "requestTemplates": {
            "application/json": "{\"statusCode\": 200}"
          },
          "passthroughBehavior": "when_no_match"
        }
      },
      ...
   }

Um den Zugriffstoken für die Methodenautorisierung zu verwenden, ändern Sie die obige Sicherheitsdefinition in { "MyUserPool": [resource-server/scope, ...] }:


  "paths": {
    "/": {
      "get": {
        "consumes": [
          "application/json"
        ],
        "produces": [
          "text/html"
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Content-Type": {
                "type": "string"
              }
            }
          }
        },
        "security": [
          {
            "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"]
          }
        ],        
        "x-amazon-apigateway-integration": {
          "type": "mock",
          "responses": {
            "default": {
              "statusCode": "200",
              "responseParameters": {
                "method.response.header.Content-Type": "'text/html'"
              },
            }
          },
          "requestTemplates": {
            "application/json": "{\"statusCode\": 200}"
          },
          "passthroughBehavior": "when_no_match"
        }
      },
      ...
   }

Bei Bedarf können Sie mithilfe der geeigneten Swagger-Definitionen oder -Erweiterungen weitere API-Konfigurationseinstellungen festlegen. Weitere Informationen finden Sie unter APIErweiterungen für API Gateway öffnen.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Amazon Cognito-Benutzerpool für eine REST-API erstellen

Aufrufen einer in einen Benutzerpool integrierten REST-API