Autentique com contas de serviço

As contas de serviço são as contas que as cargas de trabalho ou os serviços usam para consumir recursos e aceder a microsserviços de forma segura por programação. São um tipo especial de identidade usado por uma aplicação ou uma carga de trabalho, em vez de por uma pessoa. Semelhantes a uma conta de utilizador, as contas de serviço podem receber autorizações e funções, mas não podem iniciar sessão como um utilizador humano.

As contas de serviço são úteis para gerir a infraestrutura isolada do Google Distributed Cloud (GDC), como:

  • Serviços e cargas de trabalho da Distributed Cloud internos para acederem em segurança à interface de programação de aplicações (API) do plano de controlo da Distributed Cloud. Por exemplo, os serviços de base de dados que interagem com as APIs Kubernetes para criar e eliminar bases de dados.
  • Cargas de trabalho do cliente no Distributed Cloud para aceder aos serviços do Distributed Cloud e fazer chamadas autorizadas da interface de programação de aplicações (API). Por exemplo, as contas de serviço podem gerir um cliente através de um bloco de notas do Vertex AI Workbench para transcrever ficheiros de áudio com a API Speech-to-Text.
  • Fluxos de trabalho externos para federar com o Distributed Cloud. Por exemplo, as contas de serviço podem gerir uma aplicação externa à Distributed Cloud que digitaliza documentos, mas quer usar a API Optical Character Recognition (OCR) para substituir o respetivo motor de OCR atual.
  • Serviços ou controladores de sistemas da Distributed Cloud para acederem em segurança aos recursos dos clientes ou aos clusters de utilizadores. Por exemplo, as contas de serviço podem gerir fluxos de trabalho de autenticação e autorização em que os controladores de serviço executados em clusters de administrador têm de executar cargas de trabalho nos clusters de utilizador geridos pelos clientes.

Pode gerir contas através da consola do GDC, da CLI do gdcloud ou da API. Com a CLI gdcloud, a funcionalidade de identidade do serviço é criada com base na API ProjectServiceAccount global. Uma vez que as contas de serviço são configuradas globalmente, funcionam em todas as zonas no seu universo gdcloud.

Antes de começar

Só pode criar contas de serviço num projeto. Para mais informações sobre como criar um projeto, consulte Crie um projeto.

Crie uma identidade de serviço

Para receber as autorizações necessárias para criar contas de serviço, peça ao administrador do IAM do projeto que lhe conceda a função de administrador do IAM do projeto (project-iam-admin).

Os utilizadores com acesso a contas de serviço podem aceder a todas as contas de serviço num projeto.

Para criar contas de serviço num projeto, use a consola do GDC, a CLI gdcloud ou a API.

Consola

  1. Inicie sessão na consola do GDC.
  2. No menu de navegação, selecione Identidade e acesso > Identidades de serviço.
  3. Clique em Criar identidade do serviço. É apresentada a página Detalhes da identidade do serviço.
  4. No campo Nome da identidade do serviço, introduza um nome para a identidade do 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 tem de ser exclusivo no espaço de nomes do projeto.
  • PROJECT: o projeto no qual criar a identidade do serviço. Se gdcloud init já estiver definido, omita a flag --project.

Este comando cria um ProjectServiceAccount no espaço de nomes do projeto no servidor da API Management.

API

  1. Crie um ProjectServiceAccountficheiro YAML de recursos personalizadosmy-project-sa.yaml, como:

    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 tem de ser exclusivo no espaço de nomes do projeto.
    • PROJECT: o projeto no qual criar a identidade do serviço.
    • ALGORITHM: o algoritmo da chave. Apenas são suportadas chaves ES256.
    • KEY_ID: o identificador exclusivo da chave. O ID é usado para determinar a chave a validar.
    • BASE64_ENCODED_KEY: a chave pública codificada em base64 no formato PEM para validação. A chave privada usada para gerar esta chave pública é esperada no formato PEM ECDSA P256.
    • START_TIME: a hora de início em que a chave se torna válida, como 2025-02-07T00:59:34Z.
    • EXPIRATION_TIME: a hora de expiração 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 ficheiro kubeconfig do servidor da API global.

Veja identidades de serviço

Para ver uma lista de contas de serviço num projeto, use a consola do GDC ou a CLI gdcloud.

Consola

  1. Inicie sessão na consola do GDC.
  2. Selecione um projeto.
  3. No menu de navegação, clique em Identidade e acesso > Identidades de serviço para ver a lista de contas de serviço do projeto.

gdcloud

Apresente as contas de serviço num projeto:

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

Atribua uma associação de funções à identidade de serviço

Para atribuir uma associação de funções, tem de ter as autorizações adequadas. Para receber as autorizações necessárias para atribuir funções, peça ao administrador de IAM do projeto para lhe conceder a função de administrador de IAM do projeto (project-iam-admin).

Use a consola GDC ou a CLI gdcloud para atribuir uma associação de funções.

Consola

  1. Inicie sessão na consola 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. É apresentada a página Utilizadores e funções.
  5. Selecione Identidade do serviço na lista Tipo de membro.
  6. Na lista Identidade do serviço, selecione a identidade do serviço à qual quer atribuir uma associação de funções.
  7. Na lista Função, selecione a função que quer atribuir à identidade do serviço, como Criador de cópias de segurança.
  8. Opcional: para adicionar outra função, clique em Adicionar outra função. Selecione a função adicional.
  9. Clique em Adicionar.

gdcloud

Este comando cria e atribui um nome à associação de funções do projeto para associar a função especificada ao 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 no qual criar a associação de funções. Se gdcloud init já estiver definido, pode omitir a flag --project.
  • ROLE: a função predefinida a atribuir ao ProjectServiceAccount. Especifique funções no formato Role/name, em que Role é o tipo do Kubernetes IAMRole e name é o nome da função predefinida. Por exemplo, para atribuir a função de leitor do projeto, defina a função como IAMRole/project-viewer.
  • ROLE_NAMESPACE: o espaço de nomes da função a associar à conta de serviço. Isto só é aplicável se o seu universo tiver várias zonas.
  • NAME: o nome da identidade do serviço a usar.

Elimine uma identidade de serviço

Para eliminar contas de serviço num projeto, use a consola do GDC ou a CLI gdcloud.

Depois de eliminar uma identidade de serviço, as aplicações não têm acesso aos recursos do projeto através dessa identidade de serviço.

Consola

  1. Inicie sessão na consola do GDC.
  2. No menu de navegação, selecione Identidade e acesso > Identidades de serviço.
  3. Selecione a caixa de verificação da identidade do serviço que quer eliminar.
  4. Clique em Eliminar.
  5. É apresentada a caixa de diálogo de confirmação. No campo Confirme introduzindo o seguinte abaixo, introduza remove.
  6. Clique em Eliminar.

gdcloud

Execute o seguinte comando para eliminar uma identidade de serviço:

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

Crie e adicione pares de chaves

Para criar e adicionar pares de chaves num projeto, use a consola GDC, a CLI gdcloud ou a API.

Consola

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

gdcloud

O comando gdcloud cria o ficheiro JSON das credenciais predefinidas da aplicação e os pares de chaves públicas e privadas:

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 ficheiro JSON.
  • PROJECT : seleciona o projeto para o qual criar a chave. Se gdcloud init já estiver definido, pode omitir a flag --project.
  • NAME: o nome da identidade do serviço à qual adicionar a chave.
  • CA_CERTIFICATE_PATH: Opcional: o caminho do certificado da autoridade de certificação (AC) para validar o ponto final de autenticação. Se não especificar este caminho, são usados os certificados da AC do sistema. Tem de instalar a AC nos certificados da AC do sistema.

A nuvem distribuída adiciona a chave pública às ProjectServiceAccount chaves que usa para validar os tokens Web JSON (JWT) que a chave privada assina. A chave privada é escrita no ficheiro JSON das credenciais predefinidas da aplicação.

O exemplo seguinte mostra o ficheiro JSON de credenciais predefinidas da aplicação:

{
"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 espaço de nomes 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 do serviço.
  • token_uri: o endereço do ponto final de autenticação.

API

  1. Gere o par de chaves pública e privada. Os comandos seguintes usam o openssl como exemplo, que é uma ferramenta comum para este fim.

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

  2. Codifique a chave pública em Base64 e obtenha o respetivo ID da chave:

    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 ProjectServiceAccountficheiro YAML de recursos personalizados, incluindo as informações da chave geradas no passo 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 tem de ser exclusivo no espaço de nomes do projeto.
    • PROJECT: o projeto no qual está a criar a chave.
    • ALGORITHM: o algoritmo da chave. Apenas são suportadas chaves ES256.
    • KEY_ID: o identificador exclusivo da chave. O ID é usado para determinar a chave a validar.
    • BASE64_ENCODED_KEY: a chave pública codificada em base64 no formato PEM para validação. A chave privada usada para gerar esta chave pública é esperada no formato PEM ECDSA P256.
    • START_TIME: a hora de início em que a chave se torna válida, como 2025-02-07T00:59:34Z.
    • EXPIRATION_TIME: a hora de expiração 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 ficheiro kubeconfig do servidor da API global.

  5. Crie o ficheiro JSON de credenciais predefinidas da aplicação que contém a chave privada. Certifique-se de que a variável KEY_ID no ficheiro JSON está definida com o mesmo valor que a variável KEY_ID que usou 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 do serviço.
    • KEY_ID: o identificador exclusivo da chave. O ID é usado para determinar a chave a validar e tem de corresponder ao valor KEY_ID usado na especificação ProjectServiceAccount.
    • PROJECT: o espaço de nomes do projeto na organização.
    • AUTH_URL: o endereço do ponto final 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

Liste as credenciais das 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

Eliminar credenciais

Para eliminar a chave pública, use a consola GDC ou a CLI gdcloud.

Consola

  1. Inicie sessão na consola do GDC.
  2. No menu de navegação, selecione Identidade e acesso > Identidades de serviço.
  3. Clique no nome da identidade do serviço que tem a chave que quer eliminar.
  4. Clique em Eliminar.
  5. Na caixa de diálogo de confirmação, clique em Eliminar.

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

Autorize uma conta de serviço através de uma chave de conta de serviço

Pode usar o comando gdcloud para ativar uma conta de serviço através de uma chave de conta de serviço:

  1. Crie um ficheiro de chave de conta de serviço, se 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 ficheiro de chave da conta de serviço.

    Depois de ativar a conta de serviço, o gdcloud usa as credenciais da conta de serviço para comandos subsequentes, em vez das suas credenciais de utilizador.