Vista geral da autenticação de API baseada na IAM

Esta página aplica-se ao Apigee, mas não ao Apigee Hybrid.

O Apigee suporta a autenticação e a autorização baseadas na IAM para proxies de API. Para usar esta funcionalidade, inclua a política VerifyIAM no fluxo de pedidos do proxy e configure o identificador do utilizador (normalmente, o endereço de email) do consumidor da API para ter o Google Cloud papel ou as autorizações do IAM necessários para invocar as APIs Apigee. O pedido de API deve transmitir uma chave de acesso Google Cloud válida para esse utilizador.

Os administradores podem conceder autorização a qualquer Google Cloud principal, não apenas a utilizadores individuais.

Use o controlo de acesso baseado na IAM

Esta secção descreve o processo completo de configuração da autenticação e autorização baseadas na IAM, como os pedidos são avaliados assim que o acesso é configurado e como revogar o acesso para consumidores da API que tiveram acesso anteriormente.

Adicione a gestão de acessos

Para configurar a gestão de acesso para um proxy de API:

  1. Adicione a política VerifyIAM ao proxy ou aos proxies da API Apigee como parte do fluxo do pedido.
  2. O administrador do Google Cloud para o projeto do Apigee:
    1. Concede a função IAM deploymentInvoker (ou uma função personalizada com a autorização IAM apigee.deployments.invoke) ao principal Google Cloud do consumidor da API ao nível do projeto. Isto dá ao consumidor da API acesso para invocar todas as APIs alojadas na organização do Apigee associada.

      ou

    2. Usa a ação SetIamPolicy para conceder a função ou a autorização ao principal do consumidor da API num determinado Google Cloud implementação ou iterativamente em várias implementações. Use a operação list no recurso de implementação para ver todas as implementações num ambiente, incluindo proxies de API e fluxos partilhados. O nome da implementação é o nome do proxy da API ou do fluxo partilhado.
  3. Indique ao consumidor da API que gere um token de acesso, que vai transmitir no pedido da API Apigee para a verificação de autorização. O token gerado tem de ter o âmbito de autorização https://www.googleapis.com/auth/cloud-platform.

Operações de administração

Esta secção lista as ações que os administradores de APIs (produtores de APIs) realizam quando gerem autorizações baseadas na IAM.

A documentação das operações baseadas em API usadas na gestão do acesso baseado na IAM encontra-se 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 mapeia as operações para as autorizações necessárias:

Operação de administrador Ação Autorização de IAM necessária Recurso de IAM no qual a autorização é necessária*
GetDeployment Recupere informações para uma implementação num ambiente do Apigee apigee.deployments.get Projeto do Google Cloud ou ambiente Apigee
ListDeployments Apresente a lista das implementações num ambiente do Apigee apigee.deployments.list Projeto ou ambiente do Apigee
Definir Política IAM Defina o acesso de invocação para consumidores de API numa implementação de API específica apigee.deployments.setIamPolicy Projeto do Google Cloud ou ambiente Apigee
Obter Política IAM Obtenha o conjunto de definições de acesso de invocação para uma implementação de API apigee.deployments.getIamPolicy Projeto do Google Cloud ou ambiente Apigee
TestIamPermissions Verifique se o utilizador que chama esta API tem a autorização mencionada na carga útil Não é necessária autorização de IAM N/A
* O Google Cloud projeto é o projeto usado para aprovisionar o Apigee. As autorizações ao nível do ambiente do Apigee são definidas no ambiente através de setIAMPolicy.

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

Quando o consumidor da API tenta aceder a uma API com controlo de acesso baseado no IAM, é feita uma verificação para ver se tem o token de acesso necessário e a função ou a autorização adequada ao nível do projeto ou da implementação. Se for o caso, os utilizadores podem continuar a aceder ao proxy. Caso contrário, são bloqueados.

Remover acesso

Para remover o acesso ao nível do projeto: para remover o acesso de um consumidor da API gerido ao nível do projeto, o administrador da nuvem do projeto do Apigee revoga a função do deploymentInvoker IAM (ou a função personalizada com a autorização do apigee.deployments.invoke IAM) do Google Cloud principal do consumidor da API para o Google Cloud projeto.

Se o acesso tiver sido concedido para implementações individuais através de setIamPolicy, remova a função ou a autorização das implementações através de outra operação setIamPolicy.

Características e limitações do controlo de acesso baseado na IAM

Tenha em atenção estas caraterísticas e limitações quando usar a autenticação e a autorização baseadas na IAM:

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

    Tenha em atenção que estes valores de latência não são garantidos.

  • A inclusão da política VerifyIAM para um proxy é apenas uma verificação validada/não validada; as funções e as autorizações específicas do consumidor da API não são consideradas em processos posteriores no fluxo de pedidos ou respostas.
  • Uma vez que é feita uma verificação de autorização apenas no momento da execução da política VerifyIAM, a política VerifyIAM deve ser a primeira no fluxo de pedidos, depois apenas das políticas de gestão de tráfego.
  • Se a validação de autorizações for bem-sucedida ou o produtor da API tiver marcado a política VerifyIAM para continuar em caso de erro, o fluxo de pedidos continua a executar as outras políticas, se existirem, alcançando finalmente o servidor de destino. Se a verificação de autorizações falhar e o produtor da API não tiver marcado a política para continuar em caso de erro, o utilizador recebe um erro.
  • Adicionar acesso de invocação (apigee.deployments.invoke) ao nível do ambiente não transmite o acesso de invocação a todas as implementações de API no ambiente.
  • As condições da IAM não são suportadas no recurso de implementação e não podem ser usadas para controlar o acesso de invocação. Consulte o artigo Adicionar condições da IAM do Apigee a políticas para mais informações.
  • O controlo de acesso baseado na IAM suporta um máximo de 1500 associações de funções numa única política e outras limitações. Consulte as cotas e os limites do IAM.
  • O controlo de acesso baseado na IAM está sujeito a atrasos na propagação da IAM.
  • A tentativa de gerir outras operações apigee.deployments, como apigee.deployments.delete, através de setIAMPolicy ao nível da implementação, não é eficaz, mas também não devolve um erro. Apenas apigee.deployements.invoke é eficaz.
  • O acesso numa implementação é eliminado quando o proxy correspondente é desimplementado do ambiente ou eliminado. O acesso tem de ser adicionado novamente na reimplementação.
  • A autenticação e a autorização baseadas na IAM não estão disponíveis no modo híbrido neste momento.

Exemplos

Esta secção fornece exemplos de concessão e revogação do acesso baseado no IAM a APIs. Estes exemplos partem do princípio de que o VerifyIAM já foi adicionado ao proxy da API adequado.

Nestes exemplos, use a Cloud Console ou o gcloud (mostrado) para gerir funções ou autorizações no principal Google Cloud do consumidor da API.

Conceder e revogar o acesso do utilizador para invocar todas as APIs numa organização do Apigee

Para adicionar acesso, adicione a função 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 de utilizadores a implementações específicas num ambiente

Para adicionar a função de invocador de um único utilizador a uma implementaçã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 êxito deve ter um aspeto semelhante ao seguinte:

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

Para adicionar a função de invocador para vários utilizadores a uma implementaçã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"

Deverá ver uma resposta de êxito como a apresentada acima.

O utilizador pode verificar se consegue aceder à implementação especificada (se a autorização apigee.deployments.invoke estiver definida para o utilizador numa implementação especificada), sem invocar diretamente a API implementada. Para tal, o utilizador pode enviar este pedido através de uma chave de acesso gerada por si:

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 deve incluir a autorização apigee.deployments.invoke para o utilizador.

Para revogar o acesso numa implementação específica para um único utilizador, remova a função deploymentInvoker desse utilizador. Para o fazer, obtenha primeiro o objeto de política que está atualmente associado à implementação: 

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

A resposta de sucesso deve ter um aspeto semelhante ao seguinte.

{
  "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 associação de um único utilizador, use setIamPolicy e especifique no payload os utilizadores que devem continuar a ter acesso, tal como faria quando definisse o acesso inicial para esses utilizadores. Continuando com o exemplo apresentado acima, se quiser remover o acesso do USER1, mas manter o acesso do USER2 e 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 associação para todos os utilizadores numa implementaçã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 associação foi removida, certifique-se de que a autorização apigee.deployments.invoke não existe para o utilizador na implementaçã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"]}'

Isto deve devolver uma resposta adequada; por exemplo, um resultado vazio se nenhum utilizador tiver a autorização para invocar a API.