# Controlar o acesso a uma API REST com permissões do IAM O acesso à sua API do Amazon API Gateway com [permissões do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html) é controlado pelo controle do acesso aos dois processos de componente do API Gateway a seguir: + Para criar, implantar e gerenciar uma API no API Gateway, você deve conceder as permissões de desenvolvedor de APIs para realizar as ações necessárias com suporte pelo componente de gerenciamento de APIs do API Gateway. + Para chamar uma API implantada ou atualizar o armazenamento em cache de APIs, você deve conceder ao autor da chamada da API as devidas permissões para realizar as ações necessárias do IAM com suporte pelo componente de execução de APIs do API Gateway. O controle de acesso para os dois processos envolve diferentes modelos de permissões, explicados em seguida. ## Modelo de permissões do API Gateway para criar e gerenciar uma API Para permitir que um desenvolvedor de API crie e gerencie uma API no API Gateway, você deve [criar políticas de permissões do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) que permitem a um desenvolvedor de API especificado criar, atualizar, implantar, exibir ou excluir [entidades de API](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) necessárias. Você anexa a política de permissões a um usuário, perfil ou grupo. Para conceder acesso, adicione as permissões aos seus usuários, grupos ou perfis: + Usuários e grupos no Centro de Identidade do AWS IAM: Crie um conjunto de permissões. Siga as instruções em [Criação de um conjunto de permissões](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) no *Guia do usuário do Centro de Identidade do AWS IAM*. + Usuários gerenciados no IAM com provedor de identidades: Crie um perfil para a federação de identidades. Siga as instruções em [Criando um perfil para um provedor de identidades de terceiros (federação)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) no *Guia do Usuário do IAM*. + Usuários do IAM: + Crie um perfil que seu usuário possa assumir. Siga as instruções em [Criação de um perfil para um usuário do IAM](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) no *Guia do usuário do IAM*. + (Não recomendado) Vincule uma política diretamente a um usuário ou adicione um usuário a um grupo de usuários. Siga as instruções em [Adição de permissões a um usuário (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) no *Guia do usuário do IAM*. Para obter mais informações sobre como usar esse modelo de permissões, consulte [Políticas baseadas em identidade do API Gateway](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies). ## Modelo de permissões do API Gateway para invocar uma API Para permitir que um autor da chamada de API invoque a API ou atualize seu armazenamento em cache, é necessário criar políticas do IAM que permitam que um autor da chamada de API específico invoque o método de API para o qual a autenticação de usuários está ativada. O desenvolvedor de APIs define a propriedade `authorizationType` do método como `AWS_IAM` para exigir que o autor da chamada envie as credenciais do usuário do IAM a serem autenticadas. O API Gateway é compatível com o Signature Version 4a (SigV4a) e Signature Version 4 (SigV4) para autenticar as credenciais do usuário. Para ter mais informações, consulte [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Depois, é possível anexar a política a um usuário, grupo ou perfil. Nesta instrução de política de permissões do IAM, o elemento `Resource` do IAM contém uma lista de métodos de API implantados identificados por verbos HTTP especificados e por [caminhos de recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) do API Gateway. O elemento `Action` do IAM contém as ações necessárias de execução de API do API Gateway. Essas ações incluem `execute-api:Invoke` ou `execute-api:InvalidateCache`, em que `execute-api` designa o componente de execução de API subjacente do API Gateway. Para obter mais informações sobre como usar esse modelo de permissões, consulte [Controlar o acesso para chamar uma API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). Quando uma API é integrada a um serviço da AWS (por exemplo, AWS Lambda) no backend, o API Gateway também deve ter permissões para acessar recursos integrados da AWS (por exemplo, invocar uma função do Lambda) em nome do autor da chamada da API. Para conceder essas permissões, crie uma função do IAM do tipo **serviço da AWS para API Gateway**. Quando você cria essa função no console de gerenciamento do IAM, essa função resultante contém a seguinte política de confiança do IAM que declara o API Gateway como uma entidade confiável com permissão para assumir a função: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ Se você criar a função do IAM chamando o comando [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) da CLI ou um método de SDK correspondente, forneça a política de confiança acima como o parâmetro de entrada de `assume-role-policy-document`. Não tente criar essa política diretamente no console de gerenciamento do IAM ou chamando o comando da AWS CLI [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) ou um método correspondente do SDK. Para que o API Gateway chame o serviço da AWS integrado, você também deve anexar a essa função políticas de permissões do IAM apropriadas para chamar os serviços integrados da AWS. Por exemplo, para chamar uma função do Lambda, inclua a seguinte política de permissão do IAM na função do IAM: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] } ``` ------ Observe que o Lambda oferece suporte a políticas de acesso com base em recursos, que combina políticas de confiança com políticas de permissões. Ao integrar uma API com uma função do Lambda usando o console do API Gateway, você não é solicitado a definir essa função do IAM explicitamente, pois o console define as permissões com base em recurso na função do Lambda para você, com seu consentimento. **nota** Para implementar o controle de acesso em um serviço da AWS, você pode usar o modelo de permissões com base em autor da chamada, no qual uma política de permissões é diretamente anexada ao usuário ou grupo do autor da chamada, ou ao modelo de permissões com base em perfil, no qual uma política de permissões é anexada a um perfil do IAM que o API Gateway pode assumir. As políticas de permissões podem ser diferentes nos dois modelos. Por exemplo, a política baseada em agente de chamada bloqueia o acesso, enquanto a política baseada em função permite o acesso. Você pode utilizar isso para exigir que um usuário acesse um serviço da AWS somente por meio da API do API Gateway. # Controlar o acesso para chamar uma API Nesta seção, você saberá mais sobre o modelo de permissões para controlar o acesso à sua API usando as permissões do IAM. Quando a autorização do IAM está habilitada, os clientes precisam usar o Signature Version 4a (SigV4a) e o Signature Version 4 (SigV4) para assinar suas solicitações com credenciais da AWS. Para ter mais informações, consulte [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Nesta seção, mostramos um modelo de declaração de política do IAM e a referência de declarações de política. A referência de declarações de política inclui os formatos dos campos `Action` e `Resource` relacionados ao serviço de execução da API. Use essas referências para criar sua declaração de política do IAM. Ao criar a declaração de política do IAM, talvez seja necessário pensar em como as políticas de recursos do API Gateway afetam o fluxo de trabalho de autorização. Para obter mais informações, consulte [Como as políticas de recursos do API Gateway afetam o fluxo de trabalho de autorização](apigateway-authorization-flow.md). 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 REST com políticas de recursos do API Gateway](apigateway-resource-policies.md) + [Usar políticas de VPC endpoint para APIs privadas no API Gateway](apigateway-vpc-endpoint-policies.md) ## 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. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Permission", "Action": [ "execute-api:Execution-operation" ], "Resource": [ "arn:aws:execute-api:region:123456789012: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](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)` 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](#api-gateway-calling-api-permissions). **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](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#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: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/*/GET/pets" ] }, { "Effect": "Deny", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111: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: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333: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: + **\$1**, 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 **\$1** 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:\$1:\$1:\$1** 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:\$1:\$1** para qualquer caminho de recurso em qualquer estágio, para qualquer API na região da AWS `us-east-1`. + **arn:aws:execute-api:us-east-1:\$1:*api-id*/\$1** 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:\$1:*api-id*/`test`/\$1** para qualquer caminho de recurso no estágio de `test`, para a API com o identificador *api-id* na região us-east-1 da AWS. Para saber mais, consulte [Referência de nome de recurso da Amazon (ARN) do API Gateway](arn-format-reference.md). # Exemplos de políticas do IAM para permissões de execução de API Para o modelo de permissões e outras informações de segundo plano, consulte [Controlar o acesso para chamar uma API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). A instrução de política a seguir concede ao usuário permissão para chamar qualquer método POST ao longo do caminho de `mydemoresource`, no estágio de `test`, para a API com o identificador `a123456789`, supondo que a API correspondente tenha sido implantada na região da AWS us-east-1: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:*:a123456789/test/POST/my-demo-resource-path/*" ] } ] } ``` ------ O exemplo de instrução de política a seguir concede ao usuário permissão para chamar qualquer método no caminho de recurso de `petstorewalkthrough/pets`, em qualquer estágio, para a API com o identificador de `a123456789`, em qualquer região da AWS em que a API correspondente tenha sido implantada: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets" ] } ] } ``` ------