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 CreateAuthorizer 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 uma API REST no Amazon API Gateway.

Como criar um autorizador `COGNITO_USER_POOLS` usando o console do API Gateway

Crie uma nova API ou selecione uma API existente no API Gateway.
No painel de navegação principal, selecione Autorizadores.
Selecione Criar autorizador.
Para configurar o novo autorizador para usar um grupo de usuários, faça o seguinte:
1. Em Nome do autorizador, insira um nome.
2. Em Tipo de autorizador, selecione Cognito.
3. 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.
4. 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.
5. (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.
6. Selecione Criar autorizador.
Após criar o autorizador COGNITO_USER_POOLS, você tem a opção de testar a invocação fornecendo um token de identidade que é provisionado do grupo de usuários. Você pode obter esse token de identidade chamando o SDK de identidade do Amazon Cognito para fazer login do usuário. Você também pode usar a ação InitiateAuth. 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

Escolha Recursos. Selecione um novo método ou escolha um método existente. Se necessário, crie um recurso.
Na guia Solicitação de método, em Configurações de solicitação de método, escolha Editar.
Para Autorizador, no menu suspenso, selecione os Autorizadores do grupo de usuários do Amazon Cognito que você acabou de criar.
Para usar um token de identidade, faça o seguinte:
1. Mantenha Escopos de autorização em branco.
2. 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 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']"
    }
}
```
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, 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.
2. Escolha Save (Salvar).
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_USER_POOLS com um arquivo de definição do OpenAPI

Crie (ou exporte) um arquivo de definição do OpenAPI para a sua API.

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:

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"
        }
      },
      ...
   }

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"
        }
      },
      ...
   }

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 Trabalhar com extensões o API Gateway para o OpenAPI.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Criar um grupo de usuários do Amazon Cognito para uma API REST

Chamar uma API REST integrada a um grupo de usuários