Autenticar con identidades de servicio

Una identidad de servicio en Google Distributed Cloud (GDC) aislado proporciona una identidad dedicada para que las cargas de trabajo o los servicios accedan de forma programática a los recursos y microservicios de forma segura. Se trata de identidades especiales que usan las aplicaciones o las cargas de trabajo, en lugar de las personas, y no se pueden usar para iniciar sesión. Al igual que con las cuentas de usuario, puedes conceder permisos y roles a una identidad de servicio para definir a qué puede acceder.

Puede que observes que se usan dos términos para este concepto. La consola de GDC usa principalmente el término "identidad de servicio", mientras que los comandos de gdcloud y las interacciones con la API suelen usar el término "cuenta de servicio". Este último refleja el nombre del recurso personalizado de Kubernetes subyacente, ProjectServiceAccount. Ambos términos hacen referencia a lo mismo: la identidad no humana de tus cargas de trabajo. En este documento se usa el término "identidad de servicio" como término principal.

Las identidades de servicio son útiles para gestionar la infraestructura de GDC, como:

Servicios y cargas de trabajo internos de Distributed Cloud para acceder de forma segura a la interfaz de programación de aplicaciones (API) del plano de control de Distributed Cloud. Por ejemplo, los servicios de bases de datos interactúan con las APIs de Kubernetes para crear y eliminar bases de datos.
Cargas de trabajo de los clientes en Distributed Cloud para acceder a los servicios de Distributed Cloud y hacer llamadas autorizadas a la interfaz de programación de aplicaciones (API). Por ejemplo, las identidades de servicio pueden gestionar a un cliente mediante un cuaderno de Vertex AI Workbench para transcribir archivos de audio con la API Speech-to-Text.
Cargas de trabajo externas para federar con Distributed Cloud. Por ejemplo, las identidades de servicio pueden gestionar una aplicación externa a Distributed Cloud que digitaliza documentos, pero quiere usar la API de reconocimiento óptico de caracteres (OCR) para sustituir su motor de OCR actual.
Servicios de nube distribuida o controladores del sistema para acceder de forma segura a los recursos de los clientes o a los clústeres de usuarios. Por ejemplo, las identidades de servicio pueden gestionar flujos de trabajo de autenticación y autorización en los que los controladores de servicio que se ejecutan en clústeres de administrador deben ejecutar cargas de trabajo en los clústeres de usuario que gestionan los clientes.

Puedes gestionar las cuentas de identidades de servicio mediante la consola de GDC, la CLI de gdcloud o la API. Con la CLI gdcloud, la función de identidad de servicio se basa en la API global ProjectServiceAccount. Como los recursos de ProjectServiceAccount se configuran de forma global, funcionan en todas las zonas de tu universo de gdcloud.

Antes de empezar

Solo puedes crear una identidad de servicio en un proyecto. Para saber cómo crear un proyecto, consulta el artículo Crear un proyecto.

La gestión de identidades de servicio implica tanto la identidad de servicio (representada por un recurso ProjectServiceAccount) como sus credenciales asociadas (pares de claves públicas y privadas). Para obtener los permisos que necesitas para gestionar identidades de servicio y sus credenciales, pide al administrador de gestión de identidades y accesos de tu organización o proyecto que te conceda el rol Administrador de gestión de identidades y accesos de proyectos (project-iam-admin) en ese proyecto.

Crear una identidad de servicio

Para crear una identidad de servicio, debes crear una cuenta y sus credenciales asociadas.

Crear una cuenta

Para crear una cuenta de una identidad de servicio, usa la consola de GDC, la CLI de gdcloud o la API para crear un recurso ProjectServiceAccount en un proyecto.

Consola

Inicia sesión en la consola de GDC.
En el menú de navegación, selecciona Identidad y acceso > Identidades de servicio.
Haz clic en Crear identidad de servicio. Se abrirá la página Detalles de la identidad de servicio.
En el campo Nombre de identidad de servicio, escribe un nombre para tu identidad de servicio. Por ejemplo: testserviceidentity.
Haz clic en Crear.

gdcloud

Crea una cuenta:

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

Sustituye los siguientes valores:

NAME: el nombre del ProjectServiceAccount. El nombre debe ser único en el espacio de nombres del proyecto.
PROJECT: el proyecto en el que se va a crear la identidad de servicio. Si gdcloud init ya está definido, omite la marca --project.

Este comando crea un ProjectServiceAccount en el espacio de nombres del proyecto en el servidor de la API Management.

API

Crea un archivo YAML de ProjectServiceAccountrecurso personalizadomy-project-sa.yaml, como el siguiente:
```
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"
```
Sustituye las siguientes variables:
- NAME: nombre del ProjectServiceAccount recurso. El nombre debe ser único en el espacio de nombres del proyecto.
- PROJECT: el proyecto en el que se va a crear la identidad de servicio.
- ALGORITHM: el algoritmo de la clave. Solo se admiten claves ES256.
- KEY_ID: identificador único de la clave. El ID se usa para determinar con qué clave se debe verificar.
- BASE64_ENCODED_KEY: la clave pública codificada en base64 en formato PEM con la que se va a verificar. La clave privada utilizada para generar esta clave pública debe estar en formato PEM ECDSA P256.
- START_TIME: la hora de inicio en la que la clave pasa a ser válida, como 2025-02-07T00:59:34Z.
- EXPIRATION_TIME: la hora de vencimiento de la clave, como 2026-02-07T00:59:34Z.
Aplica el recurso personalizado ProjectServiceAccount al servidor de la API global:
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
Sustituye la variable GLOBAL_API_SERVER_KUBECONFIG por la ruta al archivo kubeconfig del servidor de la API global.

Crear credenciales

Para permitir que una carga de trabajo o una aplicación se autentiquen como la identidad de servicio (representada por la cuenta que has creado), debes generar credenciales. Para crear credenciales, se genera un par de claves criptográficas privadas y públicas, y se asocia la clave pública con la identidad del servicio.

Para crear credenciales de una identidad de servicio, usa la consola de GDC, la CLI de gdcloud o la API.

Consola

Inicia sesión en la consola de GDC.
En el menú de navegación, selecciona Identidad y acceso > Identidades de servicio.
Haga clic en el nombre de la identidad de servicio que quiera añadir a la clave.
Haz clic en Crear clave.
La nueva clave aparece en la lista Claves y un cuadro de diálogo confirma que la has creado correctamente.

gdcloud

El comando gdcloud crea un archivo JSON de credenciales predeterminadas de la aplicación y un par de claves pública y privada:

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

Sustituye los siguientes valores:

APPLICATION_DEFAULT_CREDENTIALS_FILENAME: el nombre del archivo JSON.
PROJECT : selecciona el proyecto para el que se va a crear la clave. Si gdcloud init ya está definido, puedes omitir la marca --project.
NAME: el nombre de la identidad de servicio a la que se va a añadir la clave.
CA_CERTIFICATE_PATH: opcional: la ruta del certificado de la autoridad de certificación (AC) para verificar el endpoint de autenticación. Si no especifica esta ruta, se usarán los certificados de CA del sistema. Debes instalar la CA en los certificados de CA del sistema.

Distributed Cloud añade la clave pública a las ProjectServiceAccount claves que usas para verificar los tokens web JSON (JWT) que firma la clave privada. La clave privada se escribe en el archivo JSON de las credenciales predeterminadas de la aplicación.

En el siguiente ejemplo se muestra el archivo JSON de las credenciales predeterminadas de la aplicación:

{
"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"
}

En este ejemplo se usan los siguientes valores:

project: el espacio de nombres del proyecto en la organización.
private_key_id: el ID asignado a la clave.
private_key: la clave privada ECDSA P256 en formato PEM que genera la CLI.
name: el nombre de la identidad de servicio.
ca_cert_path: la ruta al certificado de la autoridad de certificación (CA) que se utiliza para verificar el endpoint de autenticación.
token_uri: la dirección del endpoint de autenticación.

API

Genera el par de claves pública y privada. En los siguientes comandos se usa openssl como ejemplo, que es una herramienta habitual para este fin.
```
openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
openssl ec -in "key.pem" -pubout > "pub.pem"
```

Codifica en base64 la clave pública y obtén su ID de clave:

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

Crea o actualiza el archivo YAML de ProjectServiceAccountrecurso personalizado, incluida la información de la clave generada en el paso 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"
```
Sustituye las siguientes variables:
- NAME: nombre del ProjectServiceAccount recurso. El nombre debe ser único en el espacio de nombres del proyecto.
- PROJECT: el proyecto en el que vas a crear la clave.
- ALGORITHM: el algoritmo de la clave. Solo se admiten claves ES256.
- KEY_ID: identificador único de la clave. El ID se usa para determinar con qué clave se debe verificar.
- BASE64_ENCODED_KEY: la clave pública codificada en base64 en formato PEM con la que se va a verificar. La clave privada utilizada para generar esta clave pública debe estar en formato PEM ECDSA P256.
- START_TIME: la hora de inicio en la que la clave pasa a ser válida, como 2025-02-07T00:59:34Z.
- EXPIRATION_TIME: la hora de vencimiento de la clave, como 2026-02-07T00:59:34Z.
Aplica el recurso personalizado ProjectServiceAccount al servidor de la API global:
```
kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
```
Sustituye la variable GLOBAL_API_SERVER_KUBECONFIG por la ruta al archivo kubeconfig del servidor de la API global.
Crea el archivo JSON de credenciales de aplicación predeterminadas que contiene la clave privada. Asegúrate de que la variable KEY_ID del archivo JSON tenga el mismo valor que la variable KEY_ID que has usado en la especificación 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
```
Sustituye las siguientes variables:
- NAME: el nombre de la identidad de servicio.
- KEY_ID: identificador único de la clave. El ID se usa para determinar con qué clave se debe verificar y debe coincidir con el valor KEY_ID usado en la especificación ProjectServiceAccount.
- PROJECT: el espacio de nombres del proyecto en la organización.
- AUTH_URL: la dirección del endpoint de autenticación.

Para obtener información sobre cómo usar el archivo de claves generado para autenticar la CLI de gdcloud como esta identidad de servicio, consulta la sección Autorizar una identidad de servicio con una clave.

Ver identidades de servicio

En esta sección se describe cómo ver las identidades de servicio y sus claves públicas asociadas.

Ver una lista de identidades de servicio

Para ver una lista de identidades de servicio de un proyecto, usa la consola de GDC o la CLI de gdcloud.

Consola

Inicia sesión en la consola de GDC.
Selecciona un proyecto.
En el menú de navegación, haz clic en Identidad y acceso > Identidades de servicio para ver la lista de identidades de servicio del proyecto.

gdcloud

Lista de cuentas de identidad de servicio de un proyecto:

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

Sustituye PROJECT por el ID del proyecto.

Ver una lista de claves públicas de una identidad de servicio

Lista de claves públicas registradas en una cuenta de identidad de servicio del proyecto:

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

Haz los cambios siguientes:

PROJECT: el ID del proyecto.
NAME: el nombre de la cuenta de identidad de servicio que se va a usar.

Conceder permisos a identidades de servicio

Para conceder permisos a una identidad de servicio, asígnale uno o varios roles creando enlaces de roles mediante la consola de GDC o la CLI de gdcloud.

Consola

Inicia sesión en la consola de GDC.
Selecciona un proyecto.
En el menú de navegación, selecciona Identidad y acceso > Acceso.
En la lista Miembro, haz clic en Añadir miembro. Se muestra la página Usuarios y roles.
Selecciona Identidad de servicio en la lista Tipo de miembro.
En la lista Identidad de servicio, selecciona la identidad de servicio a la que quieras asignar una vinculación de rol.
En la lista Rol, selecciona el rol que quieras asignar a la identidad de servicio, como Creador de copias de seguridad.
Opcional: Para añadir otro rol, haz clic en Añadir otro rol. Selecciona el rol adicional.
Haz clic en Añadir.

gdcloud

Puedes vincular la cuenta de identidad de servicio a roles del espacio de nombres del proyecto o a roles de otro espacio de nombres.

Vincula la cuenta a un rol en el espacio de nombres del proyecto:
```
gdcloud iam service-accounts add-iam-policy-binding \
    --project=PROJECT \
    --role=ROLE \
    --iam-account=NAME
```
Haz los cambios siguientes:
- PROJECT: el proyecto en el que se va a crear la vinculación de roles. Si gdcloud init ya está configurado, puedes omitir la marca --project.
- ROLE: el rol predefinido que se asignará a la cuenta. Especifica los roles en el formato Role/name, donde Role es el tipo de Kubernetes IAMRole y name es el nombre del rol predefinido. Por ejemplo, para asignar el rol Lector de proyecto, define el rol como IAMRole/project-viewer.
- NAME: el nombre de la cuenta de identidad de servicio que se va a usar.
Vincula la cuenta a un rol en otro espacio de nombres:
```
gdcloud iam service-accounts add-iam-policy-binding \
    --role=ROLE \
    --role-namespace=ROLE_NAMESPACE \
    --iam-account=NAME
```
Haz los cambios siguientes:
- ROLE: el rol predefinido que se asignará a la cuenta. Especifica los roles en el formato Role/name, donde Role es el tipo de Kubernetes IAMRole y name es el nombre del rol predefinido. Por ejemplo, para asignar el rol Lector de proyecto, define el rol como IAMRole/project-viewer.
- ROLE_NAMESPACE: el espacio de nombres del rol que se va a vincular con la cuenta, que no sea el espacio de nombres del proyecto.
- NAME: el nombre de la cuenta de identidad de servicio que se va a usar.

Autenticar y usar una identidad de servicio

Para configurar gdcloud y otras herramientas de forma que funcionen como una identidad de servicio, primero debes autenticarte en gdcloud mediante el archivo de claves de la identidad de servicio. Una vez autenticado, puedes usar las credenciales de la identidad de servicio para generar tokens o archivos kubeconfig.

Autorizar una identidad de servicio mediante una clave

El comando gdcloud auth activate-service-account autentica la CLI de gdcloud con una identidad de servicio. Esto te permite realizar acciones en recursos de Distributed Cloud con los permisos de la cuenta de identidad de servicio en lugar de con una cuenta de usuario.

Autoriza una identidad de servicio mediante una clave:

Crea un archivo de clave de credenciales si aún no tienes uno.
Activa la identidad de servicio ejecutando el siguiente comando:
```
gdcloud auth activate-service-account --key-file=KEY_FILE
```
Sustituye KEY_FILE por la ruta al archivo de clave de credenciales, normalmente en formato JSON.

Una vez que se haya activado correctamente, gdcloud usará las credenciales de la identidad del servicio en lugar de las credenciales de usuario.

Imprimir un token de identidad para la identidad del servicio

Después de autorizar una identidad de servicio, puedes imprimir un token de identidad para ella. Puedes usar este token como token de portador para autenticar solicitudes HTTP. Esto significa que el token concede acceso a los servicios definidos en el parámetro AUDIENCES a cualquier tercero que lo tenga.

Imprime un token de identidad de la cuenta de identidad de servicio especificada:

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

Sustituye AUDIENCES por el destinatario o el servicio al que va dirigido el token. Solo se puede especificar una audiencia.

Generar el archivo kubeconfig

Después de autorizar una identidad de servicio, puedes generar un archivo kubeconfig para autenticarte en los clústeres.

Define la propiedad gdcloud core/organization_console_url:
```
gdcloud config set core/organization_console_url
https://GDC_URL
```
Sustituye GDC_URL por la URL de tu organización.
Genera el archivo kubeconfig para acceder a un clúster con la identidad de servicio activa:
- En el caso de un clúster zonal:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
```
  Haz los cambios siguientes:
  - KUBECONFIG_PATH: la ruta en la que quieres guardar el archivo kubeconfig generado.
  - CLUSTER_NAME: el nombre del clúster zonal.
    
    Nota: La lista de nombres de clústeres está disponible en la URL de configuración de inicio de sesión:
    https://GDC_URL/.well-known/login-config.
  - ZONE: el nombre de la zona en la que se encuentra el clúster.
- Para el servidor de la API global:
```
export KUBECONFIG=KUBECONFIG_PATH
gdcloud clusters get-credentials global-api
```
  Sustituye KUBECONFIG_PATH por la ruta en la que quieras guardar el archivo kubeconfig generado.

Se genera un archivo kubeconfig configurado para autenticarse como la identidad de servicio. A continuación, se muestra un ejemplo de archivo 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

Eliminar una identidad de servicio

Después de eliminar una identidad de servicio, se eliminarán el ProjectServiceAccount y sus claves públicas asociadas, las claves privadas dejarán de ser válidas y las aplicaciones ya no tendrán acceso a los recursos del proyecto a través de esa identidad de servicio.

Para eliminar una identidad de servicio, usa la consola de GDC o la CLI de gdcloud.

Consola

Inicia sesión en la consola de GDC.
En el menú de navegación, selecciona Identidad y acceso > Identidades de servicio.
Marca la casilla de la identidad de servicio que quieras eliminar.
Haz clic en Eliminar.
Aparecerá el cuadro de diálogo de confirmación. En el campo Para confirmar la operación, escribe lo que se indica a continuación, introduce remove.
Haz clic en Eliminar.

gdcloud

Ejecuta el siguiente comando para eliminar una identidad de servicio:

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

Haz los cambios siguientes:

NAME: el nombre de la cuenta de identidad de servicio que se va a eliminar.
PROJECT: el ID del proyecto.

Eliminar credenciales

Si quieres inhabilitar un par de claves específico sin eliminar toda la cuenta de identidad de servicio, puedes eliminar su clave pública de la cuenta de identidad de servicio. Esta acción invalida la clave privada correspondiente.

Para eliminar la clave pública, usa la consola de GDC o la CLI de gdcloud.

Consola

Inicia sesión en la consola de GDC.
En el menú de navegación, selecciona Identidad y acceso > Identidades de servicio.
Haga clic en el nombre de la identidad de servicio que tenga la clave que quiera eliminar.
Haz clic en Eliminar.
En el cuadro de diálogo de confirmación, haz clic en Eliminar.

gdcloud

Elimina la clave pública con el ID de clave de una cuenta de identidad de servicio del proyecto:

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

Haz los cambios siguientes:

KEY_ID: identificador único de la clave.
PROJECT: el ID del proyecto.
NAME: el nombre de la cuenta de identidad de servicio.

Autenticar con identidades de servicio Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Antes de empezar

Crear una identidad de servicio

Crear una cuenta

Consola

gdcloud

API

Crear credenciales

Consola

gdcloud

API

Ver identidades de servicio

Ver una lista de identidades de servicio

Consola

gdcloud

Ver una lista de claves públicas de una identidad de servicio

Conceder permisos a identidades de servicio

Consola

gdcloud

Autenticar y usar una identidad de servicio

Autorizar una identidad de servicio mediante una clave

Imprimir un token de identidad para la identidad del servicio

Generar el archivo kubeconfig

Eliminar una identidad de servicio

Consola

gdcloud

Eliminar credenciales

Consola

gdcloud

Autenticar con identidades de servicio