# Controlar o acesso a APIs REST usando grupos de usuários do Amazon Cognito como autorizador Em vez de usar [funções e políticas do IAM](permissions.md) ou [autorizadores do Lambda](apigateway-use-lambda-authorizer.md) (anteriormente conhecidos como autorizadores personalizados), você pode usar um [grupo de usuários do Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) para controlar quem pode acessar sua API no Amazon API Gateway. Para usar um grupo de usuários do Amazon Cognito com sua API, primeiro é necessário criar um autorizador do tipo `COGNITO_USER_POOLS` e depois configurar um método da API para usar esse autorizador. Após a implantação da API, o cliente deve primeiro inserir o usuário no grupo de usuários, obter uma [identidade ou token de acesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) para o usuário e, então, chamar o método de API com um dos tokens, que são normalmente definidos para o cabeçalho `Authorization` da solicitação. A chamada de API é realizada somente se o token necessário é fornecido e válido; caso contrário, o cliente não está autorizado a fazer a chamada, pois o cliente não tem credenciais que poderiam ser autorizadas. O token de identidade é usado para autorizar chamadas de API com base nas declarações de identidade do usuário conectado. O token de acesso é usado para autorizar chamadas de API com base nos escopos personalizados de recursos protegidos por acesso especificado. Para obter mais informações, consulte [Uso de tokens com grupos de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) e [Servidor de recursos e escopos personalizados](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Para criar e configurar um grupo de usuários do Amazon Cognito para sua API, realize as seguintes tarefas: + Use o console, a CLI/SDK ou a API do Amazon Cognito para criar um grupo de usuários ou use um pertencente a outra conta da AWS. + Use o console, a CLI/SDK ou a API do API Gateway para criar um autorizador do API Gateway com o grupo de usuários escolhido. + Use o console, a CLI/SDK ou a API do API Gateway para habilitar o autorizador em métodos de API selecionados. Para chamar quaisquer métodos de API com um grupo de usuários ativado, os clientes da API realizam as seguintes tarefas: + Use a CLI/SDK ou a API do Amazon Cognito para conectar um usuário ao grupo de usuários escolhido e obter um token de identidade ou de acesso. Para saber mais sobre o uso dos SDKs, consulte [Exemplos de código do Amazon Cognito usando AWS SDKs](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html). + Use um framework específico do cliente para chamar a API do API Gateway e fornecer o token apropriado no cabeçalho `Authorization`. Como um desenvolvedor de API, você deve fornecer aos desenvolvedores de clientes o ID do grupo de usuários, um ID de cliente e, possivelmente, os segredos de cliente associado, que são definidos como parte do grupo de usuários. **nota** Para permitir que um usuário faça login usando as credenciais do Amazon Cognito e também obtenha credenciais temporárias para usar com as permissões de uma função do IAM, use as [identidades federadas do Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html). Para cada método HTTP do endpoint de recurso de API, defina o tipo de autorização, categoria `Method Execution`, como `AWS_IAM`. Nesta seção, descrevemos como criar um grupo de usuários, integrar uma API do API Gateway a esse grupo de usuários e invocar essa API integrada a ele. **Topics** + [ # Criar um grupo de usuários do Amazon Cognito para uma API REST ](apigateway-create-cognito-user-pool.md) + [ # Integre uma API REST com um grupo de usuários do Amazon Cognito ](apigateway-enable-cognito-user-pool.md) + [ # Chamar uma API REST integrada a um grupo de usuários do Amazon Cognito ](apigateway-invoke-api-integrated-with-cognito-user-pool.md) + [ # Configurar o autorizador do Amazon Cognito entre contas para uma API REST usando o console do API Gateway ](apigateway-cross-account-cognito-authorizer.md) + [ # Criar um autorizador do Amazon Cognito para uma API REST usando o CloudFormation ](apigateway-cognito-authorizer-cfn.md) # Criar um grupo de usuários do Amazon Cognito para uma API REST Antes de integrar sua API a um grupo de usuários, você deve criar o grupo de usuários no Amazon Cognito. A configuração do grupo de usuários deve seguir todas as [cotas de recursos do Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html). Todas as variáveis do Amazon Cognito definidas pelo usuário, como grupos, usuários e perfis, devem usar apenas caracteres alfanuméricos. Para obter instruções sobre como criar um grupo de usuários, consulte [Tutorial: criar um grupo de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) no *Guia do desenvolvedor do Amazon Cognito*. Anote o ID do grupo de usuários, o ID do cliente e qualquer segredo de cliente. O cliente deverá fornecê-los ao Amazon Cognito para que o usuário se registre no grupo de usuários, conecte-se a esse grupo de usuários e obtenha um token de identidade ou acesso a ser incluído em solicitações para chamar métodos de API que são configurados com o grupo de usuários. Além disso, você deve especificar o nome do grupo de usuários ao configurá-lo como um autorizador no API Gateway, conforme descrito a seguir. Se você estiver usando tokens de acesso para autorizar chamadas de método da API, certifique-se de configurar a integração do aplicativo com o grupo de usuários para definir os escopos personalizados que você deseja em um determinado servidor de recursos. Para obter mais informações sobre o uso de tokens com grupos de usuários do Amazon Cognito, consulte [Uso de tokens com grupos de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Para obter mais informações sobre servidores de recursos, consulte [Definir servidores de recursos para seu grupo de usuários](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Anote os identificadores do servidor de recursos configurado e os nomes de escopo personalizados. Você precisará deles para elaborar os nomes completos do escopo de acesso para **OAuth Scopes (Escopos OAuth)**, que são usados pelo autorizador do `COGNITO_USER_POOLS`. ![\[Servidores e escopos de recursos do grupo de usuários do Amazon Cognito\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png) # 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). # Chamar uma API REST integrada a um grupo de usuários do Amazon Cognito Para chamar um método com um autorizador de grupo de usuários configurado, o cliente deve fazer o seguinte: + Permitir que o usuário se inscreva no grupo de usuários. + Permitir que o usuário se conecte ao grupo de usuários. + Obtenha uma [token de acesso ou identidade](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) do usuário conectado no grupo de usuários. + Inclua o token no cabeçalho `Authorization` (ou outro cabeçalho especificado quando você criou o autorizador). Você pode usar o [AWS Amplify]() para executar essas tarefas. Para obter mais informações, consulte [Como integrar o Amazon Cognito com aplicações Web e móveis](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html). + Para Android, consulte [Conceitos básicos do Amplify para Android](https://docs.amplify.aws/android/build-a-backend/auth/). + Para usar o iOS, consulte [Conceitos básicos do Amplify para iOS](https://docs.amplify.aws/swift/build-a-backend/auth/). + Para usar o JavaScript, consulte [Conceitos básicos do Amplify para Javascript](https://docs.amplify.aws/javascript/build-a-backend/auth/). # Configurar o autorizador do Amazon Cognito entre contas para uma API REST usando o console do API Gateway Agora você também pode usar um grupo de usuários do Amazon Cognito de uma conta da AWS diferente como seu autorizador de API. O grupo de usuários do Amazon Cognito pode usar estratégias de autenticação de token de portador, como OAuth ou SAML. Isso facilita o gerenciamento central e o compartilhamento de um autorizador central do grupo de usuários do Amazon Cognito em várias APIs do API Gateway. Nesta seção, mostramos como configurar um grupo de usuários do Amazon Cognito entre contas usando o console do Amazon API Gateway. Essas instruções pressupõem que você já tem uma API do API Gateway em uma conta da AWS e um grupo de usuários do Amazon Cognito em outra conta. ## Configurar o autorizador do Amazon Cognito entre contas para uma API REST Faça login no console do Amazon API Gateway na conta que contém a sua API e faça o seguinte: 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**, copie e cole o ARN completo do grupo de usuários de sua segunda conta. **nota** No console do Amazon Cognito é possível encontrar o ARN do grupo de usuários no campo **Pool ARN (ARN do grupo)** do painel **General Settings (Configurações gerais)**. 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**. # Criar um autorizador do Amazon Cognito para uma API REST usando o CloudFormation É possível usar o CloudFormation para criar um grupo de usuários e um autorizador do Amazon Cognito. O modelo do CloudFormation de exemplo faz o seguinte: + Criar um grupo de usuários do Amazon Cognito. O cliente deve primeiro inscrever o usuário no grupo de usuários e obter uma [identidade ou um token de acesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Se você estiver usando tokens de acesso para autorizar chamadas de método da API, certifique-se de configurar a integração do aplicativo com o grupo de usuários para definir os escopos personalizados que você deseja em um determinado servidor de recursos. + Cria uma API do API Gateway com um método `GET`. + Cria um autorizador do Amazon Cognito que usa o cabeçalho `Authorization` como fonte do token. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: UserPool: Type: AWS::Cognito::UserPool Properties: AccountRecoverySetting: RecoveryMechanisms: - Name: verified_phone_number Priority: 1 - Name: verified_email Priority: 2 AdminCreateUserConfig: AllowAdminCreateUserOnly: true EmailVerificationMessage: The verification code to your new account is {####} EmailVerificationSubject: Verify your new account SmsVerificationMessage: The verification code to your new account is {####} VerificationMessageTemplate: DefaultEmailOption: CONFIRM_WITH_CODE EmailMessage: The verification code to your new account is {####} EmailSubject: Verify your new account SmsMessage: The verification code to your new account is {####} UpdateReplacePolicy: Retain DeletionPolicy: Retain CogAuthorizer: Type: AWS::ApiGateway::Authorizer Properties: Name: CognitoAuthorizer RestApiId: Ref: Api Type: COGNITO_USER_POOLS IdentitySource: method.request.header.Authorization ProviderARNs: - Fn::GetAtt: - UserPool - Arn Api: Type: AWS::ApiGateway::RestApi Properties: Name: MyCogAuthApi ApiDeployment: Type: AWS::ApiGateway::Deployment Properties: RestApiId: Ref: Api DependsOn: - CogAuthorizer - ApiGET ApiDeploymentStageprod: Type: AWS::ApiGateway::Stage Properties: RestApiId: Ref: Api DeploymentId: Ref: ApiDeployment StageName: prod ApiGET: Type: AWS::ApiGateway::Method Properties: HttpMethod: GET ResourceId: Fn::GetAtt: - Api - RootResourceId RestApiId: Ref: Api AuthorizationType: COGNITO_USER_POOLS AuthorizerId: Ref: CogAuthorizer Integration: IntegrationHttpMethod: GET Type: HTTP_PROXY Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets Outputs: ApiEndpoint: Value: Fn::Join: - "" - - https:// - Ref: Api - .execute-api. - Ref: AWS::Region - "." - Ref: AWS::URLSuffix - / - Ref: ApiDeploymentStageprod - / ```