Esta página foi traduzida pela API Cloud Translation.

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. Para usar esse recurso, inclua a política VerifyIAM no fluxo de solicitação do proxy e configure o identificador do usuário (geralmente o endereço de e-mail) do consumidor da API para ter a função ou as permissões necessárias do IAM Google Cloud para invocar APIs da Apigee. A solicitação de API precisa transmitir um token de acesso Google Cloud válido para esse usuário.

Os administradores podem conceder autorização a qualquer principal doGoogle Cloud , não apenas a usuários individuais.

Usar o controle de acesso baseado no 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:

Adicione a política VerifyIAM ao proxy ou aos proxies da API Apigee como parte do fluxo de solicitação.
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 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 a função ou a permissão ao principal 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.
  Observação:adicionar a função ou permissão em implantações de fluxos compartilhados não cria uma verificação de política do VerifyIAM nos fluxos compartilhados. Aplique as permissões apenas a proxies. Para proxies que chamam fluxos compartilhados, as permissões precisam ser aplicadas aos proxies. Com o encadeamento de proxy, conceda a permissão no proxy com a política. A permissão não é necessária em outros proxies da cadeia.
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 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 do projeto do Apigee revoga o papel do IAM deploymentInvoker (ou o papel personalizado com a permissão apigee.deployments.invoke do IAM) do principal Google Cloud do consumidor de API para o projeto 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 entre 10 e 50 milissegundos. No entanto, algumas chamadas podem ter latências mais altas. 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 Google Cloud do consumidor da API.

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:

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects add-iam-policy-binding "${APIGEE_ORG}" --member="${USER}" \
    --role='roles/apigee.deploymentInvoker'

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

APIGEE_ORG=GCP_PROJECT
USER=USER_EMAIL_HERE
gcloud projects remove-iam-policy-binding "${APIGEE_ORG}" --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 único usuário a uma implantação específica:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_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-email@example.com"
        ]
      }
    ]
  }

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

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER1=EMAIL_FOR_USER1
USER2=EMAIL_FOR_USER2
USER3=EMAIL_FOR_USER3
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:setIamPolicy" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "policy": {
    "bindings": [
      {
        "members": [
        "user:'"$USER1"'",
        "user:'"$USER2"'",
        "user:'"$USER3"'"
        ],
        "role": "roles/apigee.deploymentInvoker"
      }
    ]
  }
}'

Para consultar o objeto de política que foi definido anteriormente:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

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

O usuário pode verificar se consegue acessar a implantação especificada (se a permissão apigee.deployments.invoke está definida para o usuário em uma implantação especificada), sem invocar a API implantada diretamente. Para isso, o usuário pode enviar essa solicitação usando um token de acesso gerado por ele:

APIGEE_ORG=GCP_PROJECT
ENV=APIGEE_ENVIRONMENT
API=APIPROXY_NAME
USER=USER_EMAIL_HERE
TOKEN=$(gcloud auth print-access-token)
curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: 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 para um único usuário, remova a função deploymentInvoker dele. Para fazer isso, primeiro acesse o objeto de política associado à implantação:

curl "https://apigee.googleapis.com/v1/organizations/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:getIamPolicy" \
  --header "Authorization: Bearer $TOKEN"

A resposta de êxito será semelhante a esta:

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:user1-email@example.com",
          "user:user2-email@example.com",
          "user:user3-email@example.com"
        ]
      }
    ]
  }

Para remover a vinculação de um único usuário, use setIamPolicy e especifique no payload os usuários que devem continuar tendo acesso, como você faria ao definir o acesso inicial para essas pessoas. Continuando com o exemplo acima, se você quisesse remover o acesso do USER1, mas manter o acesso do USER2 e do USER3, use este comando:

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

Para remover a vinculação de todos os usuários em uma implantação específica, especifique uma carga útil vazia:

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

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/${APIGEE_ORG}/environments/${ENV}/deployments/${API}:testIamPermissions" \
    --header "Authorization: Bearer $TOKEN" \
    --header 'Content-Type: application/json' \
    --data '{"permissions":["apigee.deployments.invoke"]}'

Isso vai retornar uma resposta adequada, por exemplo, uma saída vazia se nenhum usuário tiver a permissão para invocar a API.