Autenticar com contas de serviço

As contas de serviço são as contas que cargas de trabalho ou serviços usam para consumir recursos e acessar microsserviços de maneira programática e segura. Elas são um tipo especial de identidade usada por um aplicativo ou carga de trabalho, em vez de uma pessoa. Assim como uma conta de usuário, as contas de serviço podem receber permissões e papéis, mas não podem fazer login como um usuário humano.

As contas de serviço são úteis para gerenciar a infraestrutura isolada do Google Distributed Cloud (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 contas 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 contas 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 contas 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ários gerenciados pelos clientes.

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

Antes de começar

Só é possível criar contas de serviço em um projeto. Para mais informações sobre como criar um projeto, consulte Criar um projeto.

Criar uma identidade de serviço

Para receber as permissões necessárias para criar contas de serviço, peça ao administrador do IAM do projeto para conceder a você o papel de administrador do IAM do projeto (project-iam-admin).

Os usuários com acesso a contas de serviço podem acessar todas as contas de serviço em um projeto.

Para criar contas 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. 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 identidade de serviço:

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: 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.
    • KEY: a chave pública codificada em base64 para verificação.
    • 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.

Ver identidades de serviço

Para conferir uma lista de contas 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 contas de serviço do projeto.

gdcloud

Listar as contas de serviço em um projeto:

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

Atribuir uma vinculação de função à identidade de serviço

Para atribuir uma vinculação de função, é preciso ter as permissões adequadas. Para receber as permissões necessárias para atribuir papéis, peça ao administrador do IAM do projeto para conceder a você o papel de administrador do IAM do projeto (project-iam-admin).

Use o console do GDC ou a CLI gdcloud para atribuir uma vinculação de função.

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 é exibida.
  5. Selecione Identidade de serviço na lista Tipo de membro.
  6. Na lista Identidade de serviço, selecione a identidade de serviço 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

Esse comando cria e nomeia a vinculação de papel do projeto para vincular o papel especificado com o ProjectServiceAccount no servidor da API Management:

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

Substitua os seguintes valores:

  • 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 ao ProjectServiceAccount. 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 com a conta de serviço. Isso só se aplica se o universo tiver várias zonas.
  • NAME: o nome da identidade de serviço a ser usada.

Excluir uma identidade de serviço

Para excluir contas 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. 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

Criar e adicionar pares de chaves

Para criar e adicionar pares de chaves em um projeto, 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 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

Esse comando cria o arquivo JSON de credenciais padrão do aplicativo e os pares 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, você poderá omitir 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 ProjectServiceAccount chaves usadas para verificar os JSON Web Tokens (JWTs) que a chave privada assina. 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 RSA PRIVATE KEY-----\nETC\n-----END RSA PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "service_identity_name",
"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 gerada pela CLI.
  • name: o nome da identidade de serviço.
  • token_uri: o endereço do endpoint de autenticação.

Listar credenciais para contas de serviço

Liste as chaves públicas de um ProjectServiceAccount específico no projeto:

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

Excluir credenciais

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 do ProjectServiceAccount específico no projeto:

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