Autenticar com identidades de serviço

Uma identidade de serviço no Google Distributed Cloud (GDC) isolado por air-gap fornece uma identidade dedicada para que cargas de trabalho ou serviços acessem recursos e microsserviços de forma programática e segura. São identidades especiais usadas por aplicativos ou cargas de trabalho, em vez de uma pessoa, e não podem ser usadas para login humano. Assim como nas contas de usuário, você concede permissões e papéis a uma identidade de serviço para definir o que ela está autorizada a acessar.

Você pode notar dois termos usados para esse conceito. O console do GDC usa principalmente o termo "identidade de serviço", enquanto os comandos gdcloud e as interações da API costumam usar o termo "conta de serviço". O último reflete o nome do recurso personalizado do Kubernetes subjacente, ProjectServiceAccount. Os dois termos se referem à mesma coisa: a identidade não humana das suas cargas de trabalho. Este documento usa o termo "identidade de serviço" como principal.

As identidades de serviço são úteis para gerenciar a infraestrutura do GDC, como:

• Serviços e cargas de trabalho internos do Distributed Cloud para acessar com segurança a interface de programação de aplicativos (API) do plano de controle do Distributed Cloud. Por exemplo, os serviços de banco de dados interagem com as APIs do Kubernetes para criar e excluir bancos de dados.
• Workloads do cliente no Distributed Cloud para acessar serviços do Distributed Cloud e fazer chamadas autorizadas de interface de programação de aplicativos (API). Por exemplo, as identidades de serviço podem gerenciar um cliente usando um notebook do Vertex AI Workbench para transcrever arquivos de áudio com a API Speech-to-Text.
• Cargas de trabalho externas para federar com o Distributed Cloud. Por exemplo, as identidades de serviço podem gerenciar um aplicativo externo ao Distributed Cloud que digitaliza documentos, mas quer usar a API Optical Character Recognition (OCR) para substituir o mecanismo de OCR atual.
• Serviços do Distributed Cloud ou controladores de sistema para acessar com segurança recursos do cliente ou clusters de usuários. Por exemplo, as identidades de serviço podem gerenciar fluxos de trabalho de autenticação e autorização em que os controladores de serviço executados em clusters de administrador precisam executar cargas de trabalho nos clusters de usuário gerenciados pelos clientes.

É possível gerenciar contas para identidades de serviço usando o console do GDC, a CLI gdcloud ou a API. Com a CLI gdcloud, o recurso de identidade do serviço é criado com base na API ProjectServiceAccount global. Como os recursos ProjectServiceAccount são configurados globalmente, eles operam em todas as zonas do seu universo gdcloud.

Antes de começar

Só é possível criar uma identidade de serviço em um projeto. Para saber como criar um projeto, consulte Criar um projeto.

O gerenciamento de identidades de serviço envolve tanto a identidade de serviço (representada por um recurso ProjectServiceAccount) quanto as credenciais associadas (pares de chaves públicas e privadas). Para receber as permissões necessárias para gerenciar identidades de serviço e as credenciais delas, peça ao administrador do IAM da organização ou do projeto para conceder a você a função de administrador do IAM do projeto (project-iam-admin) nesse projeto.

Observação: os usuários com o papel de administrador do IAM do projeto podem acessar todas as identidades de serviço no projeto. Isso inclui o gerenciamento dos recursos ProjectServiceAccount e das chaves públicas associadas.

Criar uma identidade de serviço

Para criar uma identidade de serviço, é necessário criar uma conta e as credenciais associadas.

Criar uma conta

Para criar uma conta para uma identidade de serviço, use o console do GDC, a CLI gdcloud ou a API para criar um recurso ProjectServiceAccount em um projeto.

Console

1. Faça login no console do GDC.
2. No menu de navegação, selecione Identidade e acesso > Identidades de serviço.
3. Clique em Criar identidade do serviço. A página Detalhes da identidade do serviço é aberta.
4. No campo Nome da identidade de serviço, insira um nome para sua identidade de serviço. Por exemplo, testserviceidentity.
5. Clique em Criar.

gdcloud

Crie uma conta:

gdcloud iam service-accounts create NAME \
    --project=PROJECT

Substitua os seguintes valores:

• NAME: o nome do ProjectServiceAccount. O nome precisa ser exclusivo no namespace do projeto.
• PROJECT: o projeto em que a identidade de serviço será criada. Se gdcloud init já estiver definido, omita a flag --project.

Esse comando cria um ProjectServiceAccount no namespace do projeto no servidor da API Management.

API

1. Crie um arquivo YAML de recurso personalizado ProjectServiceAccount, como my-project-sa.yaml:

   apiVersion: resourcemanager.global.gdc.goog/v1
   kind: ProjectServiceAccount
   metadata:
     name: NAME
     namespace: PROJECT
   spec:
     keys:
     - algorithm: ALGORITHM
     id: KEY_ID
     key: BASE64_ENCODED_KEY
     validAfter: "START_TIME"
     validBefore: "EXPIRATION_TIME"
   

   Substitua as seguintes variáveis:

   • NAME: o nome do recurso ProjectServiceAccount. O nome precisa ser exclusivo no namespace do projeto.
   • PROJECT: o projeto em que a identidade de serviço será criada.
   • ALGORITHM: o algoritmo da chave. Apenas chaves ES256 são aceitas.
   • KEY_ID: o identificador exclusivo da chave. O ID é usado para determinar qual chave verificar.
   • BASE64_ENCODED_KEY: a chave pública codificada em base64 no formato PEM para verificação. A chave privada usada para gerar essa chave pública precisa estar no formato PEM ECDSA P256.
   • START_TIME: o horário de início em que a chave se torna válida, como 2025-02-07T00:59:34Z.
   • EXPIRATION_TIME: o prazo de validade da chave, como 2026-02-07T00:59:34Z.

2. Aplique o recurso personalizado ProjectServiceAccount ao servidor da API global:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
   

   Substitua a variável GLOBAL_API_SERVER_KUBECONFIG pelo caminho para o arquivo kubeconfig do servidor de API global.

Criar credenciais

Para permitir que uma carga de trabalho ou um aplicativo se autentique como a identidade do serviço (representada pela conta que você criou), é necessário gerar credenciais. Para criar credenciais, é necessário gerar um par de chaves criptográficas privada e pública e associar a chave pública à identidade do serviço.

Para criar credenciais para uma identidade de serviço, use o console do GDC, a CLI gdcloud ou a API.

Console

1. Faça login no console do GDC.
2. No menu de navegação, selecione Identidade e acesso > Identidades de serviço.
3. Clique no nome da identidade de serviço que você quer adicionar à chave.
4. Clique em Criar nova chave.
5. A nova chave aparece na lista Chaves, e uma caixa de diálogo confirma que você criou a chave.

gdcloud

O comando gdcloud cria um arquivo JSON de credenciais padrão do aplicativo e um par de chaves pública e privada:

gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
    --project=PROJECT \
    --iam-account=NAME \
    --ca-cert-path=CA_CERTIFICATE_PATH

Substitua os seguintes valores:

• APPLICATION_DEFAULT_CREDENTIALS_FILENAME: o nome do arquivo JSON.
• PROJECT : seleciona o projeto para criar a chave. Se gdcloud init já estiver definido, omita a flag --project.
• NAME: o nome da identidade de serviço para adicionar a chave.
• CA_CERTIFICATE_PATH: opcional: o caminho do certificado da autoridade de certificação (CA) para verificar o endpoint de autenticação. Se você não especificar esse caminho, os certificados de CA do sistema serão usados. É necessário instalar a CA nos certificados de CA do sistema.

O Distributed Cloud adiciona a chave pública às chaves ProjectServiceAccount usadas para verificar os JSON Web Tokens (JWTs) assinados pela chave privada. A chave privada é gravada no arquivo JSON de credenciais padrão do aplicativo.

O exemplo a seguir mostra o arquivo JSON de credenciais padrão do aplicativo:

{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN PRIVATE KEY-----\nETC\n-----END PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "/path/to/ca.crt",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

Este exemplo usa os seguintes valores:

• project: o namespace do projeto na organização.
• private_key_id: o ID atribuído à chave.
• private_key: a chave privada ECDSA P256 no formato PEM que a CLI gera.
• name: o nome da identidade de serviço.
• ca_cert_path: o caminho para o certificado da autoridade de certificação (CA) usado para verificar o endpoint de autenticação.
• token_uri: o endereço do endpoint de autenticação.

API

1. Gere o par de chaves pública e privada. Os comandos a seguir usam openssl como exemplo, que é uma ferramenta comum para essa finalidade.

   openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
   openssl ec -in "key.pem" -pubout > "pub.pem"
   

2. Codifique em base64 a chave pública e recupere o ID dela:

   KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //')
   BASE64_ENCODED_KEY=$(cat pub.pem | base64)
   

3. Crie ou atualize o arquivo YAML do recurso personalizado ProjectServiceAccount, incluindo as informações de chave geradas na etapa anterior:

   apiVersion: resourcemanager.global.gdc.goog/v1
   kind: ProjectServiceAccount
   metadata:
     name: NAME
     namespace: PROJECT
   spec:
     keys:
     - algorithm: ALGORITHM
     id: KEY_ID
     key: BASE64_ENCODED_KEY
     validAfter: "START_TIME"
     validBefore: "EXPIRATION_TIME"
   

   Substitua as seguintes variáveis:

   • NAME: o nome do recurso ProjectServiceAccount. O nome precisa ser exclusivo no namespace do projeto.
   • PROJECT: o projeto em que você está criando a chave.
   • ALGORITHM: o algoritmo da chave. Apenas chaves ES256 são aceitas.
   • KEY_ID: o identificador exclusivo da chave. O ID é usado para determinar qual chave verificar.
   • BASE64_ENCODED_KEY: a chave pública codificada em base64 no formato PEM para verificação. A chave privada usada para gerar essa chave pública precisa estar no formato PEM ECDSA P256.
   • START_TIME: o horário de início em que a chave se torna válida, como 2025-02-07T00:59:34Z.
   • EXPIRATION_TIME: o prazo de validade da chave, como 2026-02-07T00:59:34Z.

4. Aplique o recurso personalizado ProjectServiceAccount ao servidor de API global:

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
   

   Substitua a variável GLOBAL_API_SERVER_KUBECONFIG pelo caminho para o arquivo kubeconfig do servidor de API global.

5. Crie o arquivo JSON de credenciais padrão do aplicativo que contém a chave privada. Verifique se a variável KEY_ID no arquivo JSON está definida com o mesmo valor da variável KEY_ID usada na especificação ProjectServiceAccount.

   cat <<EOF > "key_file.json"
   {
     "format_version": "1",
     "name": "NAME",
     "private_key": "$(tr '\n' '\t' < "key.pem" | sed 's/\t/\\n/g')",
     "private_key_id": "KEY_ID",
     "project": "PROJECT",
     "token_uri": "AUTH_URL",
     "type": "gdch_service_account"
   }
   EOF
   

   Substitua as seguintes variáveis:

   • NAME: o nome da identidade de serviço.
   • KEY_ID: o identificador exclusivo da chave. O ID é usado para determinar qual chave verificar e precisa corresponder ao valor KEY_ID usado na especificação ProjectServiceAccount.
   • PROJECT: o namespace do projeto na organização.
   • AUTH_URL: o endereço do endpoint de autenticação.

Para detalhes sobre como usar o arquivo de chave gerado para autenticar a CLI gdcloud como essa identidade de serviço, consulte a seção Autorizar uma identidade de serviço usando uma chave.

Ver identidades de serviço

Nesta seção, descrevemos como ver as identidades de serviço e as chaves públicas associadas.

Conferir uma lista de identidades de serviço

Para conferir uma lista de identidades de serviço em um projeto, use o console do GDC ou a CLI gdcloud.

Console

1. Faça login no console do GDC.
2. Selecione um projeto.
3. No menu de navegação, clique em Identidade e acesso > Identidades de serviço para conferir a lista de identidades de serviço do projeto.

gdcloud

Listar as contas de identidade de serviço em um projeto:

gdcloud iam service-accounts list \
    --project=PROJECT

Substitua PROJECT pelo ID do projeto.

Conferir uma lista de chaves públicas para uma identidade de serviço

Liste as chaves públicas registradas com uma conta de identidade de serviço no projeto:

gdcloud iam service-accounts keys list \
    --project=PROJECT \
    --iam-account=NAME

Substitua:

• PROJECT: o ID do projeto;
• NAME: o nome da conta de identidade de serviço a ser usada.

Conceder permissões para identidades de serviço

Para conceder permissões a uma identidade de serviço, atribua a ela um ou mais papéis criando vinculações de papéis usando o console do GDC ou a CLI gdcloud.

Console

1. Faça login no console do GDC.
2. Selecione um projeto.
3. No menu de navegação, selecione Identidade e acesso > Acesso.
4. Na lista Membro, clique em Adicionar membro. A página Usuários e papéis aparece.
5. Selecione Identidade de serviço na lista Tipo de membro.
6. Na lista Identidade do serviço, selecione a identidade a que você quer atribuir uma vinculação de função.
7. Na lista Papel, selecione o papel que você quer atribuir à identidade de serviço, como Criador de backup.
8. Opcional: para adicionar outro papel, clique em Adicionar outro papel. Selecione a função adicional.
9. Clique em Adicionar.

gdcloud

É possível vincular a conta de identidade de serviço a papéis no namespace do projeto ou em um namespace diferente.

Observação: as flags --project e --role-namespace são mutuamente exclusivas. Isso significa que você só pode usar uma ou outra em um único comando, não as duas.

• Vincule a conta a uma função no namespace do projeto:

  gdcloud iam service-accounts add-iam-policy-binding \
      --project=PROJECT \
      --role=ROLE \
      --iam-account=NAME
  

  Substitua:

  • PROJECT: o projeto em que a vinculação de função será criada. Se gdcloud init já estiver definido, você poderá omitir a flag --project.
  • ROLE: o papel predefinido a ser atribuído à conta. Especifique os papéis no formato Role/name, em que Role é o tipo do Kubernetes IAMRole e name é o nome do papel predefinido. Por exemplo, para atribuir o papel de visualizador de projetos, defina o papel como IAMRole/project-viewer.
  • NAME: o nome da conta de identidade de serviço a ser usada.

• Vincule a conta a uma função em um namespace diferente:

  gdcloud iam service-accounts add-iam-policy-binding \
      --role=ROLE \
      --role-namespace=ROLE_NAMESPACE \
      --iam-account=NAME
  

  Substitua:

  • ROLE: o papel predefinido a ser atribuído à conta. Especifique os papéis no formato Role/name, em que Role é o tipo do Kubernetes IAMRole e name é o nome do papel predefinido. Por exemplo, para atribuir o papel de visualizador de projetos, defina o papel como IAMRole/project-viewer.
  • ROLE_NAMESPACE: o namespace da função a ser vinculada à conta, que não seja o namespace do projeto.
  • NAME: o nome da conta de identidade de serviço a ser usada.

Autenticar e usar uma identidade de serviço

Para configurar o gdcloud e outras ferramentas para operar como uma identidade de serviço, primeiro autentique-se no gdcloud usando o arquivo de chave da identidade de serviço. Depois de autenticado, você pode usar as credenciais da identidade do serviço para gerar tokens ou arquivos kubeconfig.

Autorizar uma identidade de serviço usando uma chave

Observação: as chaves de identidade de serviço podem causar problemas de segurança se não forem gerenciadas com cuidado. Consulte Proteger chaves de conta de serviço para informações sobre práticas recomendadas para gerenciar, usar e proteger chaves de identidade de serviço.

O comando gdcloud auth activate-service-account autentica a CLI gdcloud com uma identidade de serviço. Isso permite que você execute ações em recursos do Distributed Cloud usando as permissões da conta de identidade do serviço em vez de uma conta de usuário.

Autorize uma identidade de serviço usando uma chave:

1. Crie um arquivo de chave de credencial, se você ainda não tiver um.

2. Ative a identidade de serviço executando o seguinte comando:

   gdcloud auth activate-service-account --key-file=KEY_FILE
   

   Substitua KEY_FILE pelo caminho para o arquivo de chave de credencial, geralmente no formato JSON.

   Após a ativação, o gdcloud usa as credenciais da identidade do serviço em vez das suas.

Imprimir um token de identidade para a identidade de serviço

Depois de autorizar uma identidade de serviço, é possível imprimir um token de identidade para ela. É possível usar esse token como um token do portador para autenticar solicitações HTTP. Isso significa que o token concede a qualquer parte em posse dele acesso aos serviços definidos no parâmetro AUDIENCES.

Imprima um token de identidade para a conta de identidade de serviço especificada:

gdcloud auth print-identity-token --audiences=AUDIENCES

Substitua AUDIENCES pelo destinatário ou serviço a que o token se destina. Só é possível especificar um público-alvo.

Gerar o arquivo kubeconfig

Depois de autorizar uma identidade de serviço, é possível gerar um arquivo kubeconfig para autenticar em clusters.

1. Defina a propriedade core/organization_console_url do gdcloud:

   gdcloud config set core/organization_console_url
   https://GDC_URL
   

   Substitua GDC_URL pelo URL da sua organização.

2. Gere o arquivo kubeconfig para acessar um cluster usando a identidade de serviço ativa:

   • Para um cluster zonal:

     export KUBECONFIG=KUBECONFIG_PATH
     gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
     

     Substitua:

     • KUBECONFIG_PATH: o caminho em que você quer salvar o arquivo kubeconfig gerado.

     • CLUSTER_NAME: o nome do cluster zonal.

       Observação: a lista de nomes de clusters está disponível no URL de configuração de login:
       https://GDC_URL/.well-known/login-config.

     • ZONE: o nome da zona em que o cluster está localizado.

   • Para o servidor de API global:

     export KUBECONFIG=KUBECONFIG_PATH
     gdcloud clusters get-credentials global-api
     

     Substitua KUBECONFIG_PATH pelo caminho em que você quer salvar o arquivo kubeconfig gerado.

Um arquivo kubeconfig é gerado e configurado para autenticar como a identidade do serviço. Confira um exemplo de arquivo YAML:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <REDACTED>
    server: <REDACTED>
  name: cluster-name
contexts:
- context:
    cluster: cluster-name
    user: gdch_console-<REDACTED>_cluster-name
  name: cluster-name-gdch_console-<REDACTED>_cluster-name
current-context: cluster-name-gdch_console-gdc1-staging-gpcdemolabs-com_cluster-name
kind: Config
preferences: {}
users:
- name: gdch_console-<REDACTED>_cluster-name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - --audience=<REDACTED>
      command: gdcloud-k8s-auth-plugin
      env: null
      installHint: Run 'gdcloud components install gdcloud-k8s-auth-plugin' to use
        plugin
      interactiveMode: Never
      provideClusterInfo: false

Excluir uma identidade de serviço

Importante: quando você exclui uma identidade de serviço, as vinculações de função associadas não são removidas automaticamente. Se você criar uma nova identidade de serviço com o mesmo nome, ela vai herdar automaticamente as permissões da identidade de serviço excluída anteriormente. Para evitar permissões órfãs que podem persistir de uma identidade de serviço excluída, primeiro remova todas as vinculações de função atuais associadas à identidade de serviço antes de excluir a própria identidade de serviço.

Depois de excluir uma identidade de serviço, o ProjectServiceAccount e as chaves públicas associadas são excluídos, as chaves privadas atuais ficam inválidas, e os aplicativos não têm mais acesso aos recursos do projeto por essa identidade de serviço.

Para excluir uma identidade de serviço, use o console do GDC ou a CLI gdcloud.

Console

1. Faça login no console do GDC.
2. No menu de navegação, selecione Identidade e acesso > Identidades de serviço.
3. Marque a caixa de seleção da identidade de serviço que você quer excluir.
4. Clique em Excluir.
5. A caixa de diálogo de confirmação aparece. No campo Confirme digitando o seguinte abaixo, insira remove.
6. Clique em Excluir.

gdcloud

Execute o comando a seguir para excluir uma identidade de serviço:

gdcloud iam service-accounts delete NAME \
    --project=PROJECT

Substitua:

• NAME: o nome da conta de identidade de serviço a ser excluída.
• PROJECT: o ID do projeto;

Excluir credenciais

Se você quiser desativar um par de chaves específico sem excluir toda a conta de identidade de serviço, exclua a chave pública da conta de identidade de serviço. Essa ação invalida a chave privada correspondente.

Observação: a exclusão da chave pública não revoga as credenciais de curta duração que são emitidas usando a chave privada correspondente.

Para excluir a chave pública, use o console do GDC ou a CLI gdcloud.

Console

1. Faça login no console do GDC.
2. No menu de navegação, selecione Identidade e acesso > Identidades de serviço.
3. Clique no nome da identidade de serviço que tem a chave a ser excluída.
4. Clique em Excluir.
5. Na caixa de diálogo de confirmação, clique em Excluir.

gdcloud

Remova a chave pública com o ID da chave de uma conta de identidade de serviço no projeto:

gdcloud iam service-accounts keys delete KEY_ID \
    --project=PROJECT \
    --iam-account=NAME

Substitua:

• KEY_ID: o identificador exclusivo da chave.
• PROJECT: o ID do projeto;
• NAME: o nome da conta de identidade de serviço.