Visão geral da autenticação de API baseada no IAM

Esta página se aplica à Apigee, mas não à Apigee híbrida.

A Apigee suporta autenticação e autorização baseadas no IAM para proxies de API. Com essa solução, o acesso para invocar uma API é baseado em vários fatores, incluindo se o fluxo de solicitação inclui a política VerifyIAM e se o consumidor da API tem a função ou as permissões necessárias do IAM do Google Cloud para invocar APIs da Apigee. A autorização pode ser concedida para qualquer principal do Google Cloud e não é limitada a usuários individuais.

Usar o controle de acesso baseado em IAM

Esta seção descreve o processo completo de configuração da autenticação e autorização com base no IAM, como as solicitações são avaliadas após a configuração do acesso e como revogar o acesso para consumidores da API que já tiveram acesso.

Adicionar gerenciamento de acesso

Para configurar o gerenciamento de acesso de um proxy de API:

  1. Adicione a política VerifyIAM ao proxy ou aos proxies da API Apigee como parte do fluxo de solicitação.
  2. O administrador do Cloud para o projeto do Apigee:
    1. Concede o papel do IAM deploymentInvoker (ou um papel personalizado com a permissão apigee.deployments.invoke do IAM) ao principal do Google Cloud do consumidor da API no nível do projeto. Isso dá ao consumidor da API acesso para invocar todas as APIs hospedadas na organização da Apigee associada.

      ou

    2. Usa a ação SetIamPolicy para conceder o papel ou a permissão ao principal do Google Cloud do consumidor da API em uma implantação específica ou de forma iterativa em várias implantações. Use a operação de lista no recurso de implantação para conferir todas as implantações em um ambiente, incluindo proxies de API e fluxos compartilhados. O nome da implantação é o nome do proxy da API ou do fluxo compartilhado.
  3. Direcione o consumidor da API para gerar um token de acesso, que será transmitido na solicitação da API Apigee para a verificação de permissão. O token gerado precisa ter o escopo de autenticação https://www.googleapis.com/auth/cloud-platform.

Operações do administrador

Esta seção lista as ações que os administradores de API (produtores de API) realizam ao gerenciar permissões baseadas no IAM.

A documentação de operações baseadas em API usadas ao gerenciar o acesso baseado no IAM está disponível na documentação de referência da API organizations.environments e organizations.environments.deployments e inclui as operações SetIamPolicy, GetIamPolicy, TestIamPermissions e GetDeployment.

Esta tabela associa operações às permissões necessárias:

Operação do administrador Ação Permissão do IAM necessária Recurso do IAM em que a permissão é necessária*
GetDeployment Extrair informações de uma implantação em um ambiente da Apigee apigee.deployments.get Projeto do Google Cloud ou ambiente da Apigee
ListDeployments Listar as implantações em um ambiente da Apigee apigee.deployments.list Projeto ou ambiente da Apigee
SetIamPolicy Definir o acesso de invocação para consumidores da API em uma implantação específica apigee.deployments.setIamPolicy Projeto do Google Cloud ou ambiente da Apigee
GetIamPolicy Buscar o conjunto de configurações de acesso de invocação para uma implantação de API apigee.deployments.getIamPolicy Projeto do Google Cloud ou ambiente da Apigee
TestIamPermissions Verificar se o usuário que chama essa API tem a permissão mencionada no payload Nenhuma permissão do IAM necessária N/A
* O projeto do Google Cloud é o usado para provisionar a Apigee. As permissões do ambiente do Apigee são definidas no ambiente usando setIAMPolicy.

Verificação de acesso no tempo de execução

Quando o consumidor da API tenta acessar uma API com controle de acesso baseado no IAM, é realizada uma verificação para saber se ele tem o token de acesso necessário e a função ou permissão adequada no nível do projeto ou da implantação. Se for o caso, o acesso ao proxy será permitido. Caso contrário, eles serão bloqueados.

Remover acesso

Para remover o acesso no nível do projeto: para remover o acesso de um consumidor de API gerenciado no nível do projeto, o administrador do Cloud para o projeto da Apigee revoga o papel do IAM deploymentInvoker (ou o papel personalizado com a permissão apigee.deployments.invoke) do principal do Google Cloud do consumidor de API para o projeto do Google Cloud.

Se o acesso foi concedido para implantações individuais usando setIamPolicy, remova o papel ou a permissão das implantações usando outra operação setIamPolicy.

Características e limitações do controle de acesso baseado em IAM

Observe estas características e limitações ao usar a autenticação e autorização baseadas no IAM:

  • Normalmente, a execução da política com o VerifyIAM leva aproximadamente 10 milissegundos. No entanto, algumas chamadas podem ter latências de conclusão de aproximadamente 50 ms. Por exemplo, na região asia-east2 especificamente, a latência média pode aumentar para 50 ms, e algumas chamadas podem levar cerca de 100 ms para serem concluídas.

    Esses valores de latência não são garantidos.
  • A inclusão da política VerifyIAM para um proxy é uma verificação verificada/não verificada. As funções e permissões específicas do consumidor da API não são consideradas em processos posteriores no fluxo de solicitação ou resposta.
  • Como uma verificação de autorização é realizada apenas no momento da execução da política VerifyIAM, ela precisa ser a primeira política no fluxo de solicitações, depois das políticas de gerenciamento de tráfego.
  • Se a validação de permissão for bem-sucedida ou o produtor da API tiver marcado a política VerifyIAM para continuar em caso de erro, o fluxo de solicitação continuará a executar as outras políticas, se houver, alcançando o servidor de destino. Se a verificação de permissão falhar e o produtor da API não tiver marcado a política para continuar em caso de erro, o usuário vai receber um erro.
  • Adicionar o acesso de invocação (apigee.deployments.invoke) no nível do ambiente não transmite o acesso de invocação em todas as implantações de API no ambiente.
  • As condições do IAM não são compatíveis com o recurso de implantação e não podem ser usadas para controlar o acesso de invocação. Consulte Como adicionar condições do IAM da Apigee às políticas para mais informações.
  • O controle de acesso baseado em IAM oferece suporte a um máximo de 1.500 vinculações de função em uma única política e outras limitações. Consulte Cotas e limites do IAM.
  • O controle de acesso baseado no IAM está sujeito a atrasos na propagação do IAM.
  • A tentativa de gerenciar outras operações apigee.deployments, como apigee.deployments.delete, usando o setIAMPolicy no nível da implantação, não será eficaz, mas também não retornará um erro. Apenas apigee.deployements.invoke é eficaz.
  • O acesso a uma implantação é excluído quando o proxy correspondente é desimplantado do ambiente ou excluído. O acesso precisa ser adicionado novamente na nova implantação.
  • No momento, a autenticação e autorização baseadas no IAM não estão disponíveis no modo híbrido.

Exemplos

Esta seção apresenta exemplos de como conceder e revogar o acesso baseado no IAM às APIs. Esses exemplos presumem que o VerifyIAM já foi adicionado ao proxy de API apropriado.

Nestes exemplos, use o console do Cloud ou a gcloud (mostrada) para gerenciar papéis ou permissões no principal do Google Cloud do consumidor da API. O $Project nos exemplos é o projeto do Google Cloud.

Conceder e revogar o acesso do usuário para invocar todas as APIs em uma organização da Apigee

Para conceder acesso, adicione o papel deploymentInvoker:

gcloud projects add-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

Para revogar o acesso, remova a função deploymentInvoker:

gcloud projects remove-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

Conceder e revogar o acesso do usuário a implantações específicas em um ambiente

Para adicionar a função de invocação de um usuário a uma implantação específica:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
    --header 'Authorization: Bearer $TOKEN ' \
    --header 'Content-Type: application/json' \
    --data '{"policy":{"bindings":[{"members":["user:$user"],"role":"roles/apigee.deploymentInvoker"}]}}'

Uma resposta de sucesso vai ser parecida com esta:

  {
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

Para confirmar se o objeto de política adicionado foi mantido corretamente (opcional):

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

Você vai receber uma resposta de sucesso como a mostrada acima.

Para que o usuário verifique se pode acessar a implantação especificada (se a permissão apigee.deployments.invoke está definida para o usuário especificado em uma implantação especificada), instrua o usuário a enviar essa solicitação usando o token de acesso gerado anteriormente:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

A resposta precisa incluir a permissão apigee.deployments.invoke para o usuário.

Para revogar o acesso a uma implantação específica, remova a função deploymentInvoker. Primeiro, acesse o objeto de política associado à implantação: 

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

A resposta de êxito será semelhante a esta: Talvez você também veja outras vinculações.

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

Para remover a vinculação:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

Fornecer um payload vazio remove o acesso de todos os usuários, mas é apropriado neste exemplo porque temos apenas um usuário com acesso. Ao remover o acesso de um usuário em uma circunstância em que o acesso deve continuar para outros usuários, especifique os usuários que devem continuar tendo acesso no payload, como você faria ao definir o acesso inicial para esses usuários.

Para verificar se a vinculação foi removida, verifique se a permissão apigee.deployments.invoke não existe para o usuário na implantação:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

Isso vai retornar uma saída vazia se nenhum usuário tiver a permissão.