Autentique com identidades de serviço

Uma identidade de serviço no Google Distributed Cloud (GDC) isolado oferece uma identidade dedicada para cargas de trabalho ou serviços para aceder programaticamente a recursos e microsserviços em segurança. Estas são identidades especiais usadas por aplicações ou cargas de trabalho, em vez de por uma pessoa, e não podem ser usadas para o início de sessão por humanos. Semelhante às contas de utilizador, concede autorizações e funções a uma identidade de serviço para definir o que está autorizado a aceder.

Pode reparar que são usados dois termos para este conceito. A consola da GDC usa principalmente o termo identidade de serviço, enquanto os comandos e as interações da API gdcloud usam frequentemente o termo conta de serviço. Este último reflete o nome do recurso personalizado do Kubernetes subjacente, ProjectServiceAccount. Ambos os termos referem-se à mesma coisa: a identidade não humana para as suas cargas de trabalho. Este documento usa a identidade do serviço como o termo principal.

As identidades de serviço são úteis para gerir a infraestrutura da 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 identidades 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 identidades de serviço podem gerir uma aplicação externa ao 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 identidades 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 para identidades de serviço através da consola do GDC, da CLI gdcloud ou da API. Com a CLI gdcloud, a funcionalidade de identidade do serviço é criada com base na API global ProjectServiceAccount. Uma vez que os recursos ProjectServiceAccount são configurados globalmente, funcionam em todas as zonas do seu universo gdcloud.

Antes de começar

Só pode criar uma identidade de serviço num projeto. Para saber como criar um projeto, consulte o artigo Crie um projeto.

A gestão de identidades de serviços envolve a identidade de serviço (representada por um recurso ProjectServiceAccount) e as respetivas credenciais associadas (pares de chaves públicas e privadas). Para receber as autorizações necessárias para gerir identidades de serviço e as respetivas credenciais, peça ao administrador de IAM da organização ou ao administrador de IAM do projeto para lhe atribuir a função de administrador de IAM do projeto (project-iam-admin) nesse projeto.

Nota: os utilizadores com a função de administrador da IAM do projeto podem aceder a todas as identidades de serviço no projeto. Isto inclui a gestão dos recursos ProjectServiceAccount e das respetivas chaves públicas associadas.

Crie uma identidade de serviço

A criação de uma identidade de serviço inclui a criação de uma conta e das respetivas credenciais associadas.

Criar conta

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

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

Criar uma conta:

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 ficheiro YAML de ProjectServiceAccountrecurso personalizado, comomy-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 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.

Crie credenciais

Para permitir que uma carga de trabalho ou uma aplicação se autentique como a identidade do serviço (representada pela conta que criou), tem de gerar credenciais. A criação de credenciais envolve a geração de um par de chaves criptográficas privadas e públicas e a associação da chave pública à identidade do serviço.

Para criar credenciais para uma identidade de serviço, 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 um ficheiro JSON de credenciais predefinidas da aplicação e um par 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": "/path/to/ca.crt",
"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.
• ca_cert_path: o caminho para o certificado da autoridade de certificação (AC) que é usado para validar o ponto final de autenticação.
• token_uri: o endereço do ponto final de autenticação.

API

1. Gere o par de chaves pública e privada. Os seguintes comandos usam o comando 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 ficheiro YAML de recursos personalizados, incluindo as informações da chave geradas no passo anterior:ProjectServiceAccount

   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.

Para ver detalhes sobre como usar o ficheiro de chave gerado para autenticar a CLI gdcloud como esta identidade de serviço, consulte a secção Autorize uma identidade de serviço com uma chave.

Veja identidades de serviço

Esta secção descreve como ver as suas identidades de serviço e as respetivas chaves públicas associadas.

Veja uma lista de identidades de serviço

Para ver uma lista de identidades de serviço num projeto, use a consola 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 identidades de serviço do projeto.

gdcloud

Apresente as contas de identidade de serviço num projeto:

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

Substitua PROJECT pelo ID do projeto.

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

Apresente as chaves públicas registadas numa conta de identidade de serviço no projeto:

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

Substitua o seguinte:

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

Conceda autorizações para identidades de serviço

Para conceder autorizações a uma identidade de serviço, atribua-lhe uma ou mais funções através da criação de associações de funções com 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, 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

Pode associar a conta de identidade do serviço a funções no espaço de nomes do projeto ou a funções num espaço de nomes diferente.

Nota: os flags --project e --role-namespace são mutuamente exclusivos, o que significa que só pode usar um ou outro num único comando e não ambos.

• Associe a conta a uma função no espaço de nomes do projeto:

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

  Substitua o seguinte:

  • 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 à conta. Especifique funções no formato Role/name, em que Role é o tipo Kubernetes IAMRole e name é o nome da função predefinida. Por exemplo, para atribuir a função Project Viewer, defina a função como IAMRole/project-viewer.
  • NAME: o nome da conta de identidade do serviço a usar.

• Associe a conta a uma função num espaço de nomes diferente:

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

  Substitua o seguinte:

  • ROLE: a função predefinida a atribuir à conta. Especifique funções no formato Role/name, em que Role é o tipo Kubernetes IAMRole e name é o nome da função predefinida. Por exemplo, para atribuir a função Project Viewer, defina a função como IAMRole/project-viewer.
  • ROLE_NAMESPACE: o espaço de nomes da função a associar à conta que não seja o espaço de nomes do projeto.
  • NAME: o nome da conta de identidade do serviço a usar.

Autentique e use uma identidade de serviço

Para configurar o gdcloud e outras ferramentas para funcionarem como uma identidade de serviço, tem de se autenticar primeiro no gdcloud através do ficheiro de chave da identidade de serviço. Depois de se autenticar, pode usar as credenciais da identidade do serviço para gerar tokens ou ficheiros kubeconfig.

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

Nota: as chaves de identidade do serviço representam um risco de segurança se não forem geridas cuidadosamente. Consulte o artigo Proteja as chaves de contas de serviço para ver informações sobre as práticas recomendadas para gerir, usar e proteger as chaves de identidade de serviço.

O comando gdcloud auth activate-service-account autentica a CLI gdcloud com uma identidade de serviço. Isto permite-lhe realizar ações em recursos do Distributed Cloud através das autorizações da conta de identidade de serviço, em vez de uma conta de utilizador.

Autorize uma identidade de serviço através de uma chave:

1. Crie um ficheiro de chave de credenciais, se ainda não tiver um.

2. Ative a identidade do 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 de credenciais, normalmente no formato JSON.

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

Imprima um token de identidade para a identidade do serviço

Depois de autorizar uma identidade de serviço, pode imprimir um token de identidade para a mesma. Pode usar este token como um token de portador para autenticar pedidos HTTP. Isto significa que o token concede a qualquer parte na sua posse 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 pretendido ou pelo serviço para o qual o token se destina. Só é possível especificar um público-alvo.

Gere o ficheiro kubeconfig

Depois de autorizar uma identidade de serviço, pode gerar um ficheiro kubeconfig para se autenticar em clusters.

1. Defina a propriedade core/organization_console_url gdcloud:

   gdcloud config set core/organization_console_url
   https://GDC_URL
   

   Substitua GDC_URL pelo URL da sua organização.

2. Gere o ficheiro kubeconfig para aceder a um cluster através da identidade do serviço ativo:

   • Para um cluster zonal:

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

     Substitua o seguinte:

     • KUBECONFIG_PATH: o caminho onde quer guardar o ficheiro kubeconfig gerado.

     • CLUSTER_NAME: o nome do cluster zonal.

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

     • ZONE: o nome da zona onde 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 onde quer guardar o ficheiro kubeconfig gerado.

É gerado um ficheiro kubeconfig, configurado para autenticar como a identidade do serviço. Segue-se um exemplo de um ficheiro 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

Elimine uma identidade de serviço

Importante: quando elimina uma identidade de serviço, as respetivas associações de funções não são removidas automaticamente. Se criar uma nova identidade do serviço com o mesmo nome, esta herda automaticamente as autorizações da identidade do serviço eliminada anteriormente. Para evitar autorizações órfãs que podem permanecer de uma identidade do serviço eliminada, primeiro remova todas as associações de funções existentes associadas à identidade do serviço antes de eliminar a própria identidade do serviço.

Depois de eliminar uma identidade de serviço, o ProjectServiceAccount e as chaves públicas associadas são eliminados, as chaves privadas existentes tornam-se inválidas e as aplicações deixam de ter acesso aos recursos do projeto através dessa identidade de serviço.

Para eliminar uma identidade de serviço, use a consola do 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. 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

Substitua o seguinte:

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

Eliminar credenciais

Se quiser desativar um par de chaves específico sem eliminar a conta de identidade do serviço completa, pode eliminar a respetiva chave pública da conta de identidade do serviço. Esta ação torna a chave privada correspondente inválida.

Nota: a eliminação da chave pública não revoga as credenciais de curta duração emitidas através da chave privada correspondente.

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 de uma conta de identidade de serviço no projeto:

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

Substitua o seguinte:

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