Controlar o acesso para chamar uma API

Nesta seção, você aprenderá a escrever instruções de política do IAM para controlar quem pode ou não pode chamar uma API implantada no API Gateway. Aqui, você também encontrará a referência da instrução de política, incluindo os formatos dos campos Action e Resource relacionados ao serviço de execução da API. Você também deve examinar a seção do IAM em Como as políticas de recursos do API Gateway afetam o fluxo de trabalho de autorização.

Para APIs privadas, é necessário usar uma combinação de uma política de recursos do API Gateway e de uma política do VPC endpoint. Para obter mais informações, consulte os tópicos a seguir:

• Controlar o acesso a uma API com políticas de recursos do API Gateway

• Usar políticas de VPC endpoint para APIs privadas no API Gateway

Controlar quem pode chamar um método de API do API Gateway com políticas do IAM

Para controlar quem pode ou não pode chamar uma API implantada com permissões do IAM, crie um documento de política do IAM com as permissões necessárias. Um modelo para esse documento de política é mostrado da seguinte maneira.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Permission",
      "Action": [
        "execute-api:Execution-operation"           
      ],
      "Resource": [
        "arn:aws:execute-api:region:account-id:api-id/stage/METHOD_HTTP_VERB/Resource-path"
      ]
    }
  ]
} 

Aqui, é necessário substituir Permission por Allow ou Deny dependendo se você deseja conceder ou revogar as permissões incluídas. É necessário substituir Execution-operation pelas operações com suporte pelo serviço de execução de API. METHOD_HTTP_VERB representa um verbo HTTP com suporte pelos recursos especificados. Resource-path é o espaço reservado para o caminho da URL de uma instância de Resource da API implantada que oferece suporte ao METHOD_HTTP_VERB mencionado. Para obter mais informações, consulte Referência de instrução de políticas do IAM para executar a API no API Gateway.

nota

Para que as políticas do IAM sejam eficazes, você deve ter habilitado a autenticação do IAM em métodos de API, definindo AWS_IAM para a propriedade authorizationType do método. Se isso não for feito, esses métodos de API se tornarão acessíveis ao público.

Por exemplo, para conceder a um usuário a permissão para visualizar uma lista de animais de estimação exposta por uma API especificada, mas negar a esse usuário a permissão para adicionar um animal de estimação à lista, você pode incluir a seguinte instrução na política do IAM:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "execute-api:Invoke"           
      ],
      "Resource": [
        "arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/pets"
      ]
    },
    {
      "Effect": "Deny",
      "Action": [
        "execute-api:Invoke"           
      ],
      "Resource": [
        "arn:aws:execute-api:us-east-1:account-id:api-id/*/POST/pets"
      ]
    }
  ]
} 

Para conceder a um usuário a permissão para visualizar um animal de estimação exposto por uma API que é configurada como GET /pets/{petId}, você pode incluir a seguinte instrução na política do IAM:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "execute-api:Invoke"           
      ],
      "Resource": [
        "arn:aws:execute-api:us-east-1:account-id:api-id/*/GET/pets/a1b2"
      ]
    }
  ]
}

Referência de instrução de políticas do IAM para executar a API no API Gateway

As informações a seguir descrevem o formato de Ação e Recurso das instruções de política do IAM de permissões de acesso para a execução de uma API.

Formato de ação das permissões para executar a API no API Gateway

A expressão Action de execução de API possui o seguinte formato geral:

execute-api:action

em que action é uma ação de execução de API disponível:

• *, que representa todas as ações a seguir.

• Invocar, usado para chamar uma API mediante a solicitação de um cliente.

• InvalidateCache, usado para invalidar o cache de API mediante a solicitação de um cliente.

Formato de recurso das permissões para executar a API no API Gateway

A expressão Resource de execução de API possui o seguinte formato geral:

arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier

em que:

• region é a região da AWS (como us-east-1 ou * para todas as regiões da AWS) que corresponde à API implantada para o método.

• account-id é o ID de 12 dígitos da conta da AWS do proprietário da API REST.

• api-id é o identificador que o API Gateway atribuiu à API para o método.

• stage-name é o nome do estágio associado ao método.

• HTTP-VERB é o verbo HTTP do método. Pode ser um dos seguintes: GET, POST, PUT, DELETE, PATCH.

• resource-path-specifier é o caminho para o método desejado.

nota

Se você especificar um curinga (*), a expressão Resource aplicará o curinga ao resto da expressão.

Algumas expressões de recursos de exemplo incluem:

• arn:aws:execute-api:*:*:* para qualquer caminho de recurso em qualquer estágio, para qualquer API em qualquer região da AWS.

• arn:aws:execute-api:us-east-1:*:* para qualquer caminho de recurso em qualquer estágio, para qualquer API na região da AWS de us-east-1.

• arn:aws:execute-api:us-east-1:*:api-id/* para qualquer caminho de recurso em qualquer estágio, para a API com o identificador de api-id na região da AWS us-east-1.

• arn:aws:execute-api:us-east-1:*:api-id/test/* para o caminho do recurso no estágio de test, para a API com o identificador api-id na região da AWS us-east-1.

Para saber mais, consulte Referência de nome de recurso da Amazon (ARN) do API Gateway.