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, a CLI gdcloud ou a API. 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, 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 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: 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.

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 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

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 papel 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

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

Para excluir contas de serviço em um projeto, use o console do GDC ou a CLI gdcloud.

Depois de excluir uma identidade de serviço, os aplicativos não terão mais acesso aos recursos do projeto por essa identidade.

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, 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 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 PRIVATE KEY-----\nETC\n-----END 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 ECDSA P256 no formato PEM que a CLI gera.
• name: o nome da identidade de serviç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.

6. Adicione o par de chaves ao projeto ativando a conta de serviço:

   gdcloud auth activate-service-account –-key-file=key_file.json
   

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.

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

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

Autorizar uma conta de serviço usando uma chave de conta de serviço

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

É possível usar o comando gdcloud para ativar uma conta de serviço usando uma chave de conta de serviço:

1. Crie um arquivo de chave da conta de serviço, se você ainda não tiver um.

2. Ative a conta 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 da conta de serviço.

   Depois de ativar a conta de serviço, o gdcloud usa as credenciais dela para os comandos subsequentes, em vez das suas credenciais de usuário.