Integre uma API REST com um grupo de usuários do Amazon Cognito

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.

   É 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}.

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.

Escolha atributos. 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 Salvar.

Repita essas etapas para outros métodos que você quiser.

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 ter mais informações, consulte Extensões OpenAPI para o API Gateway.