Como usar a autenticação do Google

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Este tópico explica como configurar e implantar um proxy de API configurado para usar a autenticação do Google.

Usuários da Apigee híbrida: se você estiver usando a Apigee híbrida, observe que esse recurso é compatível apenas com a v1.6.x e versões posteriores da plataforma.

Introdução

A Apigee é compatível com o uso de tokens do OAuth do Google ou tokens do Connect Connect para autenticação com serviços do Google, como o Cloud Logging e o Gerenciador de segredos e serviços personalizados em execução em determinados produtos do Google Cloud, como o Cloud Functions e o Cloud Run.

Para usar esse recurso, configure o elemento XML <Authentication> em um dos seguintes contextos:

• Políticas do ServiceCallout
• Políticas de destaque externo
• Configurações de TargetEndpoint

Depois que você concluir algumas etapas básicas de configuração, conforme descrito neste tópico, a Apigee executará a geração de tokens e fará chamadas seguras para serviços segmentados do Google ou serviços hospedados personalizados para você, sem a necessidade de definir manualmente cabeçalhos de autenticação. caso contrário, modifique uma solicitação de serviço. Da perspectiva de um desenvolvedor de APIs, o processo de chamar os serviços do Google em um proxy de API configurado corretamente é processado de maneira integrada.

Opções de configuração de proxy da API

Nesta seção, explicamos onde é possível usar o elemento XML <Authentication> para ativar a autenticação do token OAuth do Google ou do OpenID Connect:

Opção de configuração	Descrição
Política ServiceCallout	A política ServiceFrase de destaque permite chamar outros serviços internos ou externos a partir de um proxy de API. Por exemplo, é possível usá-lo para chamar serviços externos do Google ou serviços hospedados personalizados. Veja detalhes e exemplos de uso em Política de ServiceCallout.
Política ExternalCallout	A política ExternalCallout permite enviar solicitações gRPC ao servidor gRPC para implementar um comportamento personalizado que não é compatível com as políticas da Apigee. Para detalhes de uso e exemplos, consulte Política de chamada externa.
TargetEndpoint	Especifique um serviço do Google ou um serviço hospedado personalizado como um endpoint de destino do proxy de API. Para ver detalhes de uso e exemplos, consulte a Referência de configuração do proxy de API.

Contextos compatíveis com o token de autenticação do Google

O elemento <Authentication> tem duas configurações de subelementos: <GoogleAccessToken> ou <GoogleIDToken>. A tabela a seguir mostra os contextos em que esses elementos são compatíveis:

Usado em	GoogleAccessToken	GoogleIDToken
Política ServiceCallout	Compatível	Compatível
Política ExternalCallout	Sem suporte	Compatível
TargetEndpoint	Compatível	Compatível

Observação: a política ExternalCall não pode chamar APIs do Google, portanto, os tokens de acesso do Google não são compatíveis com a política. No entanto, os tokens OpenID Connect são compatíveis. Portanto, se o serviço de destino estiver hospedado, por exemplo, no Cloud Run, a política poderá se conectar perfeitamente a ele.

Atenção: evite usar segmentações dinâmicas não SSL. Por exemplo, tente não substituir a variável de fluxo target.url para levar a um endpoint de destino não SSL. Se você usar um destino dinâmico não SSL, o token de autenticação do Google ainda será gerado. No entanto, o token de autenticação será exibido em texto simples.

Etapas da implantação

Esta seção explica como implantar um proxy de API que usa a autenticação do Google para chamar serviços do Google segmentados ou serviços hospedados personalizados. Explicamos as etapas de implantação para a Apigee e a Apigee híbrida separadamente.

Observação: as implantações de fluxo compartilhado também são compatíveis com o uso da tag Authentication nas políticas compatíveis e na configuração do TargetEndpoint. Consulte também a documentação da API de implantação de fluxo compartilhado.

Implantar na Apigee

Nas etapas a seguir, explicamos como implantar um proxy de API na Apigee, em que o proxy é configurado para fazer chamadas autenticadas para serviços do Google ou serviços hospedados personalizados. As etapas pressupõem que você já tenha criado o proxy e que ele inclui um elemento <Authentication> em um dos contextos compatíveis listados.

1. Crie uma conta de serviço do Google no mesmo projeto do Google Cloud em que sua organização da Apigee foi criada. Forneça o nome dessa conta de serviço ao implantar um proxy de API configurado para usar a autenticação do Google, e os tokens OAuth gerados representarão a conta de serviço. É possível criar a conta de serviço no Console do Google Cloud ou com o comando gcloud. Consulte Como criar e gerenciar contas de serviço.
2. Dê ao usuário que fará a implantação (o implantador) a permissão iam.serviceAccounts.actAs na conta de serviço. Consulte também Sobre permissões da conta de serviço.
   Cuidado: os usuários que receberam o papel de usuário da conta de serviço em uma conta de serviço podem usá-lo para acessar indiretamente todos os recursos acessíveis a essa conta. Para detalhes, consulte Papel de usuário da conta de serviço. Recomendamos que você configure a conta de serviço para privilégio mínimo para minimizar o impacto das atribuições de papel do usuário.
   Observação: esta etapa pode ser opcional se o implantador já tiver permissão suficiente, por exemplo, ao implantar por meio da IU e o usuário do Google Cloud tiver o papel Proprietário no projeto.

   gcloud iam service-accounts add-iam-policy-binding \
   SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --member="MEMBER" \
     --role="roles/iam.serviceAccountUser"
   

Em que:

• PROJECT_ID: é o ID do projeto. Ele é igual ao nome da sua organização.
• SA_NAME: o nome que você forneceu quando criou a conta de serviço.
• MEMBER: o membro para quem a vinculação deve ser adicionada. Ele precisa estar no formato user|group|serviceAccount:email ou domain:domain.
3. Dê à conta de serviço as permissões necessárias para se comunicar com os Serviços do Google segmentados. Por exemplo, se você quiser chamar o serviço Google Logging, essa conta de serviço precisará incluir as permissões necessárias para se comunicar com esse serviço. Consulte também Noções básicas sobre papéis.
4. Antes de implantar um proxy de API configurado para usar a autenticação do Google, você precisa de:
   • O nome da conta de serviço que você criou anteriormente. Por exemplo: SA_NAME@PROJECT_ID.iam.gserviceaccount.com
   • Como o usuário que está realizando a implantação (o implantador), você precisa já ter ou receber a permissão iam.serviceAccounts.actAs na conta de serviço. Consulte Como conceder, alterar e revogar acesso a recursos.
5. Implante o proxy de API que contém a configuração de autenticação do Google que você implementou. É possível usar a IU ou a API da Apigee para implantar o proxy. Para saber mais, consulte Como implantar um proxy de API.
   • Se estiver usando a IU, você será solicitado a fornecer um nome de conta de serviço. Use o nome da conta de serviço do proxy que você criou na Etapa 1. Por exemplo, SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

     

   • Se você preferir implantar o proxy usando a API de implantação da Apigee, veja um exemplo de comando cURL que pode ser usado. Observe que o comando inclui um nome de conta de serviço como um parâmetro de consulta. Esse é o nome da conta de serviço criada na Etapa 1:

     curl -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
     -H "Content-Type: application/json" -X POST

     Em que:

     • TOKEN: um token OAuth que você precisa acessar em troca das suas credenciais do Google. Para detalhes, consulte Como receber um token de acesso do OAuth 2.0.
     • ORG_NAME: o nome da organização da Apigee.
     • ENV_NAME: o nome do ambiente para implantar o proxy de API.
     • SA_NAME: o nome que você forneceu quando criou a conta de serviço.
     • PROJECT_ID: o ID do projeto do Google Cloud (mesmo que o nome da organização).
6. Quando a implantação for concluída, teste o proxy de API para garantir que o serviço do Google retorne a resposta esperada.

Implantar na Apigee híbrida

Veja nas etapas a seguir como implantar na Apigee híbrida de um proxy de API configurado para fazer chamadas autenticadas aos serviços do Google. As etapas pressupõem que você já tenha criado o proxy e que ele inclui um elemento <Authentication> em um dos contextos compatíveis listados.

Observação : as etapas de 1 a 3 abaixo são obrigatórias, mas são etapas de configuração únicas.

1. Crie uma conta de serviço e uma chave para o híbrido da Apigee tempo de execução usando um dos seguintes métodos:
   Observação: se você já criou uma conta de serviço apigee-runtime quando você instalou o híbrido da Apigee, pule esta etapa.
   • Use a ferramenta create-service-account fornecida com a Apigee híbrida para criar uma conta de serviço apigee-runtime. A ferramenta cria a conta de serviço e retorna uma chave da conta de serviço. Consulte create-service-account para detalhes.
   • Crie a conta de serviço no Console do Google Cloud ou com o comando gcloud. Consulte Como criar e gerenciar contas de serviço. Para buscar a chave da conta de serviço, consulte Como criar e gerenciar chaves de conta de serviço.
   Observação : é possível criar a conta de serviço do ambiente de execução em qualquer projeto do Google Cloud em que você tenha permissão para fazer isso. Ele não precisa ser criado no mesmo projeto usado para sua organização da Apigee.
2. Abra o arquivo overrides.yaml e especifique o caminho para o arquivo de chave da conta do serviço de cada ambiente que requer a capacidade de autenticação do Google:

   envs:
     - name: "ENVIRONMENT_NAME"
       serviceAccountPaths:
         runtime: "KEY_FILE_PATH"

   Observação: se você tiver vários ambientes que exigem o recurso de autenticação do Google, cada um pode ter sua própria conta de serviço ou todos podem compartilhar a mesma. Consulte também Sobre permissões da conta de serviço.

   Exemplo:

   envs:
     - name: "test"
       serviceAccountPaths:
         runtime: "./service_accounts/my_runtime_sa.json"

3. Aplique o arquivo de modificações ao cluster usando apigeectl apply.
4. Crie uma segunda conta de serviço, chamada de conta de serviço proxy. Essa conta de serviço precisa estar no mesmo projeto do Google Cloud usado para criar sua organização da Apigee. Forneça o e-mail dessa conta de serviço ao implantar um proxy de API configurado para usar a autenticação do Google, e os tokens OAuth gerados representarão a conta de serviço.
5. Dê ao usuário que fará a implantação (o implantador) a permissão iam.serviceAccounts.actAs na conta de serviço. Consulte também Sobre permissões da conta de serviço.
   Cuidado: os usuários que receberam o papel de usuário da conta de serviço em uma conta de serviço podem usá-lo para acessar indiretamente todos os recursos acessíveis a essa conta. Para detalhes, consulte Papel de usuário da conta de serviço. Recomendamos que você configure a conta de serviço para privilégio mínimo para minimizar o impacto das atribuições de papel do usuário.
   Observação: esta etapa pode ser opcional se o implantador já tiver permissão suficiente, por exemplo, ao implantar por meio da IU e o usuário do Google Cloud tiver o papel Proprietário no projeto.

   gcloud iam service-accounts add-iam-policy-binding \
   SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --member="MEMBER" \
     --role="roles/iam.serviceAccountUser"
   

Em que:

• PROJECT_ID: é o ID do projeto. Ele é igual ao nome da sua organização.
• SA_NAME: o nome que você forneceu quando criou a conta de serviço.
• MEMBER: o membro para quem a vinculação deve ser adicionada. Precisa ter o formato user|group|serviceAccount:email ou domain:domain.
6. Dê ao proxy a conta de serviço as permissões necessárias para se comunicar com os Serviços do Google segmentados. Por exemplo, se você quiser chamar o serviço Google Logging, essa conta de serviço precisará incluir as permissões necessárias para se comunicar com esse serviço. Consulte também Noções básicas sobre papéis.
7. Verifique se o tempo de execução tem a capacidade de personificar a conta de serviço de proxy. Para fornecer essa capacidade, conceda à conta de serviço runtime o papel iam.serviceAccountTokenCreator na conta de serviço do proxy. Consulte também Sobre permissões da conta de serviço. Exemplo:

   gcloud iam service-accounts add-iam-policy-binding \
   PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --member=serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/iam.serviceAccountTokenCreator
   

   Em que:

   • PROJECT_ID: é o ID do projeto. Ele é igual ao nome da sua organização. Não foi necessário usar o projeto associado à organização para criar a conta de serviço do ambiente de execução. Use os IDs corretos do projeto neste comando.
   • PROXY_SA_NAME: o ID da conta de serviço proxy.
   • RUNTIME_SA_NAME: o ID da conta de serviço runtime.
8. Antes de implantar um proxy de API configurado para usar a autenticação do Google, você precisa de:
   • O nome da conta de serviço do proxy que você criou anteriormente. Exemplo: PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
   • Como usuário que realiza a implantação, você precisa ter ou receber a permissão iam.serviceAccounts.actAs no projeto do Google Cloud em que a organização da Apigee é provisionada. Consulte Como conceder, alterar e revogar acesso a recursos.
9. Implante o proxy de API que contém a configuração de autenticação do Google que você implementou. É possível usar a IU ou a API da Apigee para implantar o proxy. Para saber mais, consulte Como implantar um proxy de API.
   • Se estiver usando a IU, você será solicitado a fornecer um nome de conta de serviço. Use o nome da conta de serviço proxy criada anteriormente. Por exemplo, PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

     

   • Se você preferir implantar o proxy usando a API de implantação da Apigee, veja um exemplo de comando cURL que pode ser usado. Observe que o comando inclui um nome de conta de serviço como um parâmetro de consulta. Esse é o nome da conta de serviço do proxy:

     curl -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
     -H "Content-Type: application/json" -X POST

     Em que:

     • TOKEN: um token OAuth que você precisa acessar em troca das suas credenciais do Google. Para detalhes, consulte Como receber um token de acesso do OAuth 2.0.
     • ORG_NAME: o nome da organização da Apigee.
     • ENV_NAME: o nome do ambiente para implantar o proxy de API.
     • PROXY_SA_NAME: o nome da conta de serviço do proxy.
     • PROJECT_ID: o ID do projeto do Google Cloud (mesmo que o nome da organização).
10. Quando a implantação for concluída, teste o proxy de API para garantir que o serviço do Google retorne a resposta esperada.

Sobre as permissões da conta de serviço

Se você quiser configurar um proxy de API para usar a autenticação do Google, crie uma conta de serviço conforme descrito na tabela a seguir. Consulte também Como criar e gerenciar contas de serviço.

Conta de serviço	Necessário para	Descrição
Proxy	Apigee e Apigee híbrida	Tem as permissões necessárias para que um proxy de API faça chamadas autenticadas aos serviços do Google segmentados. Precisa ser criado no mesmo projeto do Google Cloud que sua organização do Apigee. O usuário que executa a implantação (o implantador) precisa ter ou receber a permissão iam.serviceAccounts.actAs na conta de serviço do proxy. Precisa incluir as permissões necessárias para falar com serviços específicos do Google de destino. Por exemplo, se você quiser chamar o serviço Google Logging, essa conta de serviço precisará incluir as permissões necessárias para se comunicar com esse serviço. Consulte também Noções básicas sobre papéis. O nome da conta de serviço precisa ser fornecido quando você implanta o proxy que usa a autenticação do Google.
Ambiente de execução	Somente híbrido da Apigee	Permite que o ambiente de execução da Apigee gere tokens para autenticar nos serviços do Google solicitados por um proxy de API. Essa conta de serviço "representa" a conta de serviço específica do proxy para fazer chamadas autenticadas em nome dela. Para representar a conta de serviço do proxy e criar tokens, a conta de serviço do runtime precisa receber o papel roles/iam.serviceAccountTokenCreator no proxy. Consulte Gerenciar o acesso a contas de serviço.