Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # 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 [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html)-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 [REST-APIs in API Gateway bereitstellen](how-to-deploy-api.md). **So erstellen Sie einen `COGNITO_USER_POOLS`-Genehmiger unter Verwendung der API Gateway-Konsole:** 1. Erstellen Sie eine neue API oder wählen Sie eine vorhandene API in API Gateway aus. 1. Wählen Sie im Hauptnavigationsbereich **Genehmiger**. 1. Wählen Sie **Genehmiger erstellen** aus. 1. 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. 1. Wählen Sie als **Genehmiger-Typ** **Cognito** aus. 1. 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. Mit einer Stufenvariablen können Sie Ihren Benutzerpool definieren. Verwenden Sie das folgende Format für den Benutzerpool: `arn:aws:cognito-idp:{{us-east-2}}:{{111122223333}}:userpool/${stageVariables.{{MyUserPool}}}`. 1. 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. 1. 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. 1. Wählen Sie **Genehmiger erstellen** aus. 1. Nach der Erstellung des `COGNITO_USER_POOLS`-Genehmigers können Sie einen Testaufruf durchführen, indem Sie ein vom Benutzerpool bereitgestelltes Identitätstoken übergeben. Sie können kein Zugriffstoken verwenden, um Ihren Autorisierer testweise aufzurufen. Sie können dieses Identitätstoken erhalten, indem Sie das [Amazon Cognito Identity-SDK](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) aufrufen, um die Benutzeranmeldung durchzuführen. Sie können auch die [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html)-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** 1. Wählen Sie **Resources** aus. Wählen Sie eine neue oder eine vorhandene Methode aus. Falls erforderlich, erstellen Sie eine Ressource. 1. Wählen Sie auf der Registerkarte **Methodenanfrage** unter **Methodenanfrage-Einstellungen** die Option **Bearbeiten** aus. 1. Wählen Sie für **Genehmiger** aus dem Dropdown-Menü die **Amazon-Cognito-Benutzerpool-Genehmiger**, die Sie soeben erstellt haben. 1. Zur Verwendung eines Identitätstokens führen Sie die folgenden Schritte aus: 1. Lassen Sie das Feld **Genehmigungsbereiche** leer. 1. 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](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) `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']" } } ``` 1. 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](apigateway-create-cognito-user-pool.md) 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. 1. Wählen Sie **Speichern**. 1. Wiederholen Sie diese Schritte für weitere Methoden Ihrer Wahl. Wenn beim `COGNITO_USER_POOLS` Authorizer die Option **OAuthScopes** nicht angegeben ist, behandelt API Gateway das bereitgestellte Token als Identitätstoken und verifiziert die beanspruchte Identität anhand der Identität 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** 1. Erstellen (oder exportieren) Sie eine Swagger-Definitionsdatei für Ihre API. 1. 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: ------ #### [ OpenAPI 3.0 ] ``` "securitySchemes": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ #### [ OpenAPI 2.0 ] ``` "securityDefinitions": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ 1. 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" } }, ... } ``` 1. 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" } }, ... } ``` 1. Bei Bedarf können Sie mithilfe der geeigneten Swagger-Definitionen oder -Erweiterungen weitere API-Konfigurationseinstellungen festlegen. Weitere Informationen finden Sie unter [OpenAPI-Erweiterungen für API Gateway](api-gateway-swagger-extensions.md).