# Integre uma API REST com um grupo de usuários do Amazon Cognito Depois de criar um grupo de usuários do Amazon Cognito, no API Gateway, você deve criar um autorizador `COGNITO_USER_POOLS` que use o grupo de usuários. O procedimento a seguir mostra como fazer isso usando o console do API Gateway. **nota** Você pode usar a ação [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) para criar um autorizador `COGNITO_USER_POOLS` que usa vários grupos de usuários. Você pode usar até 1.000 grupos de usuários para um autorizador `COGNITO_USER_POOLS`. Este limite não pode ser aumentado. **Importante** Depois de executar qualquer um dos procedimentos a seguir, você precisará implantar ou reimplantar sua API para propagar as alterações. Para mais informações sobre como implantar sua API, consulte [Implantar APIs REST no API Gateway](how-to-deploy-api.md). **Como criar um autorizador `COGNITO_USER_POOLS` usando o console do API Gateway** 1. Crie uma nova API ou selecione uma API existente no API Gateway. 1. No painel de navegação principal, selecione **Autorizadores**. 1. Selecione **Criar autorizador**. 1. Para configurar o novo autorizador para usar um grupo de usuários, faça o seguinte: 1. Em **Nome do autorizador**, insira um nome. 1. Em **Tipo de autorizador**, selecione **Cognito**. 1. Em **Grupo de usuários do Cognito**, escolha a Região da AWS onde você criou o Amazon Cognito e selecione um grupo de usuários disponível. É possível usar uma variável de estágio para definir o grupo de usuários. Use o seguinte formato para o grupo de usuários: `arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`. 1. Em **Origem do token**, insira **Authorization** como o nome de cabeçalho para passar o token de identidade ou acesso que é retornado pelo Amazon Cognito quando um usuário faz login com êxito. 1. (Opcional) Insira uma expressão regular no campo **Validação do token** para validar o campo `aud` (público) do token de identidade antes de a solicitação ser autorizada com o Amazon Cognito. Observe que, ao usar um token de acesso, essa validação rejeita a solicitação porque o token de acesso não contém o campo `aud`. 1. Selecione **Criar autorizador**. 1. Depois de criar o autorizador `COGNITO_USER_POOLS`, você tem a opção de testar a invocação fornecendo um token de identidade provisionado do grupo de usuários. Não é possível usar um token de acesso para testar a invocação do autorizador. Você pode obter esse token de identidade chamando o [SDK de identidade do Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) para fazer login do usuário. Você também pode usar a ação [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). Se você não configurar **Escopos de autorização**, o API Gateway tratará o token fornecido como um token de identidade. O procedimento anterior cria um autorizador `COGNITO_USER_POOLS` que usa o grupo de usuários do Amazon Cognito recém-criado. Dependendo de como você habilita o autorizador em um método de API, você pode usar um token de identidade ou de acesso que é provisionado do grupo de usuários integrado. **Para configurar um autorizador do `COGNITO_USER_POOLS` nos métodos** 1. Escolha **atributos**. Selecione um novo método ou escolha um método existente. Se necessário, crie um recurso. 1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, escolha **Editar**. 1. Para **Autorizador**, no menu suspenso, selecione os **Autorizadores do grupo de usuários do Amazon Cognito** que você acabou de criar. 1. Para usar um token de identidade, faça o seguinte: 1. Mantenha **Escopos de autorização** em branco. 1. Se necessário, em **Solicitação de integração**, adicione as expressões `$context.authorizer.claims['property-name']` ou `$context.authorizer.claims.property-name` em um modelo de mapeamento de corpo para transmitir a propriedade de declarações de identidade especificada do grupo de usuários para o back-end. Para nomes de propriedades simples, como `sub` ou `custom-sub`, as duas notações são idênticas. Para nomes de propriedades complexos, como `custom:role`, você não pode usar a notação de pontos. Por exemplo, as seguintes expressões de mapeamento passam os [campos padrão](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) da declaração de `sub` e `email` para o backend: ``` { "context" : { "sub" : "$context.authorizer.claims.sub", "email" : "$context.authorizer.claims.email" } } ``` Se você tiver declarado um campo de declaração personalizado quando configurou um grupo de usuários, poderá seguir o mesmo padrão para acessar os campos personalizados. O exemplo a seguir obtém um campo `role` personalizado de uma declaração: ``` { "context" : { "role" : "$context.authorizer.claims.role" } } ``` Se o campo de declaração personalizada for declarado como `custom:role`, use o exemplo a seguir para obter a propriedade da declaração: ``` { "context" : { "role" : "$context.authorizer.claims['custom:role']" } } ``` 1. Para usar um token de acesso, faça o seguinte: 1. Em **Escopos de autorização**, insira um ou mais nomes completos de um escopo que tenha sido configurado quando o grupo de usuários do Amazon Cognito foi criado. Por exemplo, seguindo o exemplo apresentado em [Criar um grupo de usuários do Amazon Cognito para uma API REST](apigateway-create-cognito-user-pool.md), um dos escopos é `https://my-petstore-api.example.com/cats.read`. Durante o runtime, a chamada do método ocorre com êxito se qualquer escopo especificado no método desta etapa corresponder a um escopo que foi reivindicado no token de entrada. Caso contrário, a chamada falhará com uma resposta `401 Unauthorized`. 1. Escolha **Salvar**. 1. Repita essas etapas para outros métodos que você quiser. Com o autorizador `COGNITO_USER_POOLS`, se a opção **OAuth Scopes** não estiver especificada, o API Gateway trata o token fornecido como um token de identidade e verifica a identidade declarada em relação à do grupo de usuários. Caso contrário, o API Gateway trata o token fornecido como um token de acesso e verifica os escopos de acesso que são declarados no token em relação aos escopos de autorização declarados no método. Em vez de usar o console do API Gateway, você também pode habilitar um grupo de usuários do Amazon Cognito em um método especificando um arquivo de definição do OpenAPI e importando a definição da API para o API Gateway. **Para importar um autorizador COGNITO\$1USER\$1POOLS com um arquivo de definição do OpenAPI** 1. Crie (ou exporte) um arquivo de definição do OpenAPI para a sua API. 1. Especifique a definição JSON do autorizador `COGNITO_USER_POOLS` (`MyUserPool`) como parte da seção `securitySchemes` no OpenAPI 3.0 ou da seção `securityDefinitions` no OpenAPI 2.0 da seguinte forma: ------ #### [ 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. Para usar o token de identidade para a autorização de método, adicione `{ "MyUserPool": [] }` à definição `security` do método, conforme mostrado no seguinte método GET no recurso raiz. ``` "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. Para usar o token de acesso para a autorização do método, mude a definição de segurança acima para `{ "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. Se necessário, é possível definir outras configurações de API usando as extensões ou definições do OpenAPI apropriadas. Para obter mais informações, consulte [Extensões OpenAPI para o API Gateway](api-gateway-swagger-extensions.md).