Configurar la federación de identidades de cargas de trabajo con certificados X.509

En esta guía se describe cómo usar la federación de identidades de carga de trabajo con certificados X.509 emitidos por tu autoridad de certificación (CA) para autenticarte y acceder a recursos de Trusted Cloud Trusted Cloud .

Si tus cargas de trabajo tienen un certificado de cliente mTLS, puedes autenticarte enTrusted Cloud registrando una o varias CAs en la federación de Workload Identity como anclas de confianza. También puedes registrar CAs intermedias.

Si usas la federación de identidades de cargas de trabajo, puedes permitir que estas cargas de trabajo obtengan credenciales de corta duración a través de una conexión TLS mutua (mTLS). Trusted Cloud Las cargas de trabajo pueden usar estas credenciales de corta duración para acceder a las APIs deTrusted Cloud .

Conceptos

Los conceptos de federación basados en certificados X.509 incluyen lo siguiente:

• Una ancla de confianza es un certificado de CA que se considera la raíz de confianza. Las cadenas de certificados de cliente deben estar encadenadas a una de las anclas de confianza.

• Una CA intermedia es un certificado de autoridad de certificación opcional que ayuda a crear la cadena de certificados de cliente.

• Un almacén de confianza contiene los certificados de ancla de confianza y los certificados de AC intermedios que se usan para validar la cadena de certificados de cliente. Una CA emite certificados de confianza para el cliente.

  Puede subir los siguientes tipos de certificados de cliente al almacén de confianza:

  • Certificados emitidos por ACs de terceros de tu elección
  • Certificados emitidos por tus AC privadas
  • Certificados firmados, tal como se describe en Crear certificados autofirmados

Antes de empezar

Para empezar a configurar la federación de identidades de cargas de trabajo, haz lo siguiente:

1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

   Go to project selector

Te recomendamos que uses un proyecto específico para gestionar los grupos y proveedores de Workload Identity.

2. Verify that billing is enabled for your Trusted Cloud project.

3. Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

   Enable the APIs

Roles obligatorios

Para obtener los permisos que necesitas para configurar la federación de identidades de carga de trabajo, pide a tu administrador que te conceda los siguientes roles de gestión de identidades y acceso en el proyecto:

• Administrador de grupos de Workload Identity (roles/iam.workloadIdentityPoolAdmin)
• Administrador de cuentas de servicio (roles/iam.serviceAccountAdmin)

Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

También puedes usar el rol básico Propietario de IAM (roles/owner), que incluye permisos para configurar la federación de identidades. No debes conceder roles básicos en un entorno de producción, pero sí puedes hacerlo en un entorno de desarrollo o de pruebas.

Crear un almacén de confianza

En esta sección se explica cómo crear un almacén de confianza. Estos son los pasos que debe seguir para hacerlo:

• Generar certificados autofirmados
• Formatear los certificados
• Crear el almacén de confianza

Generar certificados autofirmados

En esta sección se explica cómo generar claves y crear certificados firmados. Si ya has creado certificados, puedes saltarte esta sección y continuar con Dar formato a los certificados.

En esta sección se usan comandos de openssl para crear certificados raíz e intermedios.

Para generar un certificado raíz y un certificado intermedio firmado con campos keyUsage y extendedKeyUsage válidos, haz lo siguiente:

1. Crea un archivo de configuración openssl para crear tus certificados de firma. Como mínimo, el archivo será similar al siguiente, pero puedes definir campos adicionales según sea necesario.

   cat > example.cnf << EOF
   [req]
   distinguished_name = empty_distinguished_name
   [empty_distinguished_name]
   # Kept empty to allow setting via -subj command-line argument.
   [ca_exts]
   basicConstraints=critical,CA:TRUE
   keyUsage=keyCertSign
   extendedKeyUsage=clientAuth
   [leaf_exts]
   keyUsage=critical,Digital Signature, Key Encipherment
   basicConstraints=critical, CA:FALSE
   EOF
   

2. Crea el certificado raíz.

   openssl req -x509 \
       -new -sha256 -newkey rsa:2048 -nodes \
       -days 3650 -subj '/CN=root' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout root.key -out root.cert
   

3. Crea la solicitud de firma del certificado intermedio.

   openssl req \
       -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=int' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout int.key -out int.req
   

4. Crea el certificado intermedio.

   openssl x509 -req \
       -CAkey root.key -CA root.cert \
       -set_serial 1 \
       -days 3650 \
       -extfile example.cnf \
       -extensions ca_exts \
       -in int.req -out int.cert
   

5. Crea la solicitud de firma del certificado de hoja.

   openssl req -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=example' \
       -config example.cnf \
       -extensions leaf_exts \
       -keyout leaf.key -out leaf.req
   

6. Crea el certificado de hoja emitido por el intermedio.

   openssl x509 -req \
       -CAkey int.key -CA int.cert \
       -set_serial 1 -days 3650 \
       -extfile example.cnf \
       -extensions leaf_exts \
       -in leaf.req -out leaf.cert
   

Dar formato a los certificados

Para incluir certificados nuevos o ya existentes en un almacén de confianza, formatea los certificados en una cadena de una línea y guárdalos en variables de entorno. Los certificados deben estar en formato PEM. Para dar formato a los certificados y almacenarlos en variables de entorno, haz lo siguiente:

1. Guarda el certificado raíz como una cadena de una línea.

   export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

2. Guarda un certificado intermedio como una cadena de una línea.

   export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

Crear el almacén de confianza

En esta sección, creará un almacén de confianza mediante un archivo con formato YAML que contenga sus anclas de confianza y sus CAs intermedias.

Este archivo contiene el contenido del certificado de las variables de entorno que has creado en Formatear los certificados. Para añadir anclas de confianza adicionales, añade entradas trustAnchors adicionales en trustStore. Para añadir más certificados de AC intermedios, añade más entradas intermediateCas en trustStore.

Para crear el archivo del almacén de confianza, ejecuta el siguiente comando:

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

Definir una asignación de atributos y una condición

El certificado X.509 de cliente puede contener varios atributos. Debe seleccionar el atributo que quiera usar como identificador del sujeto asignando google.subject in Trusted Cloud al atributo de su certificado. Por ejemplo, si el atributo del certificado es el nombre común del asunto, la asignación sería la siguiente: google.subject=assertion.subject.dn.cn

Si quiere, puede mapear atributos adicionales. Después, puedes hacer referencia a estos atributos al conceder acceso a los recursos.

Tus asignaciones de atributos pueden usar los atributos del certificado de cliente, incluidos los siguientes:

• serialNumberHex: el número de serie
• subject.dn.cn: el nombre común del asunto
• subject.dn.o: el nombre de la organización en cuestión
• subject.dn.ou: la última unidad organizativa del asunto
• issuer.dn.cn: el nombre común del emisor
• issuer.dn.o: el nombre de la organización emisora
• issuer.dn.ou: la última unidad organizativa de la entidad emisora
• san.dns: el primer nombre de DNS del nombre alternativo del sujeto
• san.uri: la primera URI del nombre alternativo del sujeto
• sha256Fingerprint: hash SHA256 del certificado de hoja (Base64)

Debe asignar uno de estos atributos a google.subject para identificar de forma única al sujeto. Para protegerte frente a las amenazas de suplantación de identidad, elige un atributo con un valor único que no se pueda cambiar. De forma predeterminada, el identificador google.subject se asigna al nombre común del asunto del certificado de cliente, assertion.subject.dn.cn.

También puedes definir una condición de atributo. Las condiciones de los atributos son expresiones CEL que pueden comprobar los atributos de aserción y los atributos de destino. Si el atributo de condición se evalúa como true para una credencial determinada, se acepta la credencial. De lo contrario, se rechaza la credencial.

Puedes usar una condición de atributo para restringir qué sujetos pueden usar la federación de identidades de cargas de trabajo para obtener tokens de corta duración. Trusted Cloud

Por ejemplo, la siguiente condición restringe el acceso a los certificados de cliente que contengan el ID de SPIFFE spiffe://example/path:

assertion.san.uri=="spiffe://example/path"

Configurar la federación de identidades de cargas de trabajo

En esta sección se explica cómo configurar un grupo de identidades de carga de trabajo y un proveedor de grupos de identidades de carga de trabajo. Solo tiene que seguir estos pasos una vez por cada almacén de confianza. Después, puede usar el mismo grupo y proveedor de identidades de carga de trabajo en varias cargas de trabajo y en varios proyectos Trusted Cloud .

Crear el grupo de identidades de carga de trabajo

1. Para crear un grupo de identidades de carga de trabajo, ejecuta el siguiente comando:

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   Haz los cambios siguientes:

   • POOL_ID: ID único del grupo.
   • DISPLAY_NAME: el nombre del grupo.
   • DESCRIPTION: una descripción de la piscina que elijas. Esta descripción aparece cuando concedes acceso a identidades de grupo.

Crear el proveedor de grupos de identidades de carga de trabajo

1. Para añadir un proveedor de grupos de identidades de carga de trabajo X.509, ejecuta el siguiente comando:

   gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
       --location=global \
       --workload-identity-pool="POOL_ID" \
       --trust-store-config-path="TRUST_STORE_CONFIG" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   Haz los cambios siguientes:

   • PROVIDER_ID: ID único del proveedor de grupos de identidades de carga de trabajo que elijas.
   • POOL_ID: el ID del grupo de identidades de carga de trabajo que has creado anteriormente.
   • TRUST_STORE_CONFIG: el archivo YAML del almacén de confianza.
   • MAPPINGS: lista separada por comas de asignaciones de atributos que has creado anteriormente en esta guía. Por ejemplo, google.subject=assertion.subject.dn.cn.
   • CONDITIONS: opcional. Una condición de atributo que has creado anteriormente en esta guía. Quita el parámetro si no tienes una condición de atributo.

Autenticar una carga de trabajo

Debes seguir estos pasos una vez por cada carga de trabajo.

Permitir que tu carga de trabajo externa acceda a los recursos de Trusted Cloud

Para proporcionar a tu carga de trabajo acceso a los recursos de Trusted Cloud , te recomendamos que concedas acceso directo a los recursos a la entidad principal. En este caso, el principal es el usuario federado. Algunos Trusted Cloud productos tienen limitaciones en la API de Google Cloud. Si tu carga de trabajo llama a un endpoint de API que tiene una limitación, puedes usar la suplantación de identidad de la cuenta de servicio. En este caso, el principal es laTrusted Cloud cuenta de servicio, que actúa como identidad. Concede acceso a la cuenta de servicio en el recurso.

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

Descargar o crear una configuración de credenciales

Las bibliotecas de cliente de Cloud y la CLI de gcloud pueden obtener automáticamente credenciales externas y usarlas para suplantar la identidad de una cuenta de servicio. Para que las bibliotecas y las herramientas puedan completar este proceso, debes proporcionar un archivo de configuración de credenciales. Este archivo proporciona la siguiente información:

• Dónde obtener las credenciales externas
• Qué grupo y proveedor de identidades de carga de trabajo se deben usar
• Cuenta de servicio cuya identidad se va a usar

Además, para la federación de certificados X.509, se necesita un archivo de configuración de certificados. Este archivo contiene las rutas al certificado de cliente X.509 y a los archivos de clave privada.

Crea archivos de configuración de credenciales y certificados que permitan a la biblioteca obtener tokens de acceso mediante certificados X.509.

gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

Usar la configuración de credenciales para acceder a Trusted Cloud

Para permitir que las herramientas y las bibliotecas de cliente usen tu configuración de credenciales, haz lo siguiente. Para obtener más información sobre las credenciales predeterminadas de la aplicación, consulta Cómo funcionan las credenciales predeterminadas de la aplicación.

1. Inicializa una variable de entorno GOOGLE_APPLICATION_CREDENTIALS y asígnale el archivo de configuración de la credencial:

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   Sustituye FILEPATH por la ruta relativa al archivo de configuración de las credenciales.

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   Sustituye FILEPATH por la ruta relativa al archivo de configuración de las credenciales.

2. Asegúrate de que la biblioteca de cliente pueda encontrar el archivo de configuración del certificado. El archivo de configuración del certificado se encuentra en una de las siguientes rutas:

   • Ruta predeterminada de la CLI de gcloud:

     • Linux y macOS: ~/.config/gcloud/certificate_config.json

     • Windows: %APPDATA%\gcloud\certificate_config.json

   • La ruta definida en la variable de entorno GOOGLE_API_CERTIFICATE_CONFIG.

3. Usa las siguientes bibliotecas de cliente de Cloud que admiten la federación de identidades de carga de trabajo con certificados X.509.

   Go

   Las bibliotecas de cliente de Go admiten la federación de identidades de carga de trabajo X.509 si usan la versión 0.16.0 o posterior del módulo cloud.google.com/go/auth y la versión 0.189.0 del módulo google.golang.org/api.

   Para comprobar qué versión de estos módulos usa tu biblioteca de cliente, ejecuta el siguiente comando en el directorio que contiene el archivo go.mod de tu módulo:

     go list -m cloud.google.com/go/auth
     go list -m cloud.google.com/api
   

   Python

   Las bibliotecas de cliente de Python admiten la federación de identidades de carga de trabajo X.509 si usan la versión 2.39.0 o posterior del paquete google-auth.

   Para comprobar qué versión de este paquete usa tu biblioteca de cliente, ejecuta el siguiente comando en el entorno en el que está instalado el paquete:

     pip show google-auth
   

   Para especificar un ID de proyecto para el cliente de autenticación, puedes definir la variable de entorno GOOGLE_CLOUD_PROJECT o permitir que el cliente busque el ID de proyecto automáticamente. Para encontrar el ID de proyecto automáticamente, la cuenta de servicio del archivo de configuración debe tener el rol de navegador (roles/browser) o un rol con permisos equivalentes en tu proyecto. Para obtener más información, consulta la guía de usuario del paquete google-auth.

4. Si tu carga de trabajo se ejecuta en macOS, define CLOUDSDK_PYTHON_SITEPACKAGES=1 para configurar la CLI de gcloud de forma que use bibliotecas de Python fuera de su directorio de instalación.

5. Para autenticarte con gcloud CLI, ejecuta el siguiente comando:

   gcloud auth login --cred-file=FILEPATH.json
   

   Sustituye FILEPATH por la ruta del archivo de configuración de credenciales.

   La compatibilidad con la federación de identidades de carga de trabajo X.509 en la CLI de gcloud está disponible en la versión 519.0 y en versiones posteriores de la CLI de gcloud.

Obtener un token de acceso mediante una solicitud simple para acceder a Trusted Cloud

Crear la cadena de confianza

En este paso se explica cómo crear la cadena de confianza. Cuando llamas al servicio de tokens de seguridad en una solicitud sin cifrar, pasas la cadena de confianza en el campo subject_token.

Da formato a los certificados que deban incluirse en la cadena como una lista en formato JSON, tal como se especifica en el RFC 7515. El certificado de hoja que se usa para el handshake mTLS debe especificarse como el primer elemento. Cada certificado del paquete debe ser una cadena codificada en Base64.

1. Guarda el certificado de hoja y el certificado intermedio en cadenas codificadas en Base64.

   export LEAF_CERT=$(openssl x509 -in leaf.cert -out leaf.der -outform DER && cat leaf.der | openssl enc -base64 -A)
   

   export INTERMEDIATE_CERT=$(openssl x509 -in int.cert -out int.der -outform DER && cat int.der | openssl enc -base64 -A)
   

2. Crea una lista de cadenas con formato JSON que se pueda transferir como subject_token en la llamada al servicio de token de seguridad, más adelante en este documento.

   export TRUST_CHAIN="[\\\"${LEAF_CERT}\\\", \\\"${INTERMEDIATE_CERT}\\\"]"
   

Obtener un token de acceso

Para obtener el token de acceso, haz lo siguiente:

1. Realiza el intercambio de tokens con mTLS y el certificado de cliente:

   curl --key CLIENT_CERT_KEY \
   --cert CLIENT_CERT \
   --request POST 'https://sts.mtls.s3nsapis.fr/v1/token' \
   --header "Content-Type: application/json" \
   --data-raw '{
       "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "audience": "WORKLOAD_IDENTITY_POOL_URI",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "https://www.googleapis.com/auth/cloud-platform",
       "subject_token": "TRUST_CHAIN"
   }'
   

   Haz los cambios siguientes:

   • CLIENT_CERT_KEY: la clave privada del certificado de cliente
   • CLIENT_CERT: el certificado de cliente

   • WORKLOAD_IDENTITY_POOL_URI: la URL del proveedor del grupo de identidades de carga de trabajo con el siguiente formato:

     //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

   • TRUST_CHAIN: La cadena de confianza necesaria para verificar el certificado de hoja debe incluir al menos CLIENT_CERT como primer elemento. Si has seguido las instrucciones de la sección Formatear los certificados, sustituye TRUST_CHAIN por '"${TRUST_CHAIN}"'.

2. Usa el token de acceso de portador generado en el paso anterior para acceder a los recursos deTrusted Cloud . Por ejemplo:

   curl -X GET 'https://storage.s3nsapis.fr/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
   

Límites

En la siguiente tabla se indican los límites.

Siguientes pasos

• Consulta más información sobre la federación de identidades de cargas de trabajo.
• Consulta las prácticas recomendadas para usar la federación de identidades de cargas de trabajo.
• Consulta cómo puedes gestionar grupos y proveedores de Workload Identity.