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

En esta guía, se describe cómo usar la federación de identidades para cargas de trabajo con certificados X.509 que emite tu autoridad certificadora (AC) para autenticarte en Cloud de Confiance y acceder a Cloud de Confiance recursos.

Si tus cargas de trabajo tienen un certificado de cliente mTLS, puedes registrar una o más AC con la federación de identidades para cargas de trabajo como entidades de confianza para autenticarte enCloud de Confiance . También puedes registrar AC intermedias.

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

Conceptos

Los conceptos de la integración basada en certificados X.509 incluyen los siguientes:

• Un ancla de confianza es un certificado de AC que se considera la raíz de confianza. Cualquier cadena de certificados de cliente debe estar vinculada a una de las anclas de confianza.

• Una CA intermedia es un certificado de la AC opcional que ayuda a compilar la cadena de certificados del cliente.

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

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

  • Los certificados emitidos por CA de terceros que elijas
  • Certificados emitidos por tus AC privadas
  • Certificados firmados, como se describe en Crea certificados autofirmados

Antes de comenzar

Para comenzar a configurar la federación de Workload Identity, haz lo siguiente:

1. En la consola de Cloud de Confiance , en la página del selector de proyectos, selecciona o crea un proyecto de Cloud de Confiance .

   Roles necesarios para seleccionar o crear un proyecto

   • Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
   • Crear un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.

   Ir al selector de proyectos

Te recomendamos que uses un proyecto dedicado para administrar grupos y proveedores de Workload Identity.

2. Verifica que la facturación esté habilitada para tu proyecto de Cloud de Confiance .

Habilita las APIs de IAM, Resource Manager, Service Account Credentials y Security Token Service.

Roles necesarios para habilitar las APIs

Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtener este permiso a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

Habilitar las API

Roles obligatorios

Para obtener los permisos que necesitas para configurar la federación de Workload Identity, pídele a tu administrador que te otorgue los siguientes roles de IAM en el proyecto:

• Administrador de grupos de identidades para cargas de trabajo (roles/iam.workloadIdentityPoolAdmin)
• Administrador de cuenta de servicio (roles/iam.serviceAccountAdmin)

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

De manera alternativa, el rol básico de propietario de IAM (roles/owner) también incluye permisos para configurar la federación de identidades. No deberías otorgar funciones básicas en un entorno de producción, pero puedes otorgarlas en un entorno de desarrollo o de prueba.

Crea un almacén de confianza

En esta sección, se muestra cómo crear un almacén de confianza. A grandes rasgos, los pasos son los siguientes:

• Genera certificados autofirmados
• Da formato a los certificados
• Crea el almacén de confianza

Genera certificados autofirmados

En esta sección, se muestra cómo generar claves y crear certificados firmados. Si ya creaste certificados, puedes omitir esta sección y continuar con Da formato a los certificados.

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

Para generar un certificado raíz y un certificado intermedio firmado con los 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 es similar al siguiente, pero puedes establecer 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 para el 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 para el 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 certificado 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
   

Da formato a los certificados

Para incluir certificados nuevos o existentes en un almacén de confianza, debes dar formato a los certificados en una cadena de una sola línea y almacenarlos 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 sola 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')
   

Crea el almacén de confianza

En esta sección, crearás un almacén de confianza con un archivo con formato YAML que contenga tus anclas de confianza y AC intermedias.

Este archivo contiene el contenido del certificado de las variables de entorno que creaste en Da formato a los certificados. Para agregar anclas de confianza adicionales, agrega entradas trustAnchors adicionales en trustStore. Para agregar certificados de la AC intermedios adicionales, agrega entradas intermediateCas adicionales en trustStore.

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

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

Define una condición y la asignación de atributos

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

De manera opcional, puedes mapear atributos adicionales. Luego, puedes hacer referencia a estos atributos adicionales cuando otorgues acceso a los recursos.

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

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

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

De manera opcional, puedes definir una condición de atributo. Las condiciones de los atributos son expresiones CEL que pueden verificar los atributos de aserción y los atributos de destino. Si la condición del atributo 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 para cargas de trabajo para obtener tokens de Cloud de Confiancecorta duración.

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

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

Configura la federación de Workload Identity

En esta sección, se muestra cómo configurar un grupo de identidades para cargas de trabajo y un proveedor de grupos de identidades para cargas de trabajo. Solo debes realizar estos pasos una vez para cada almacén de confianza. Luego, puedes usar el mismo grupo y proveedor de identidades para cargas de trabajo en varias cargas de trabajo y en varios proyectos de Cloud de Confiance .

Crea el proveedor y el grupo de Workload Identity

Configura la aplicación de políticas de acceso adaptado al contexto para la federación de identidades para cargas de trabajo

Puedes reforzar la seguridad de los recursos contra ataques de reproducción de tokens habilitando el acceso adaptado al contexto, que aplica la validación de mTLS para las solicitudes de acceso. En este proceso, una vinculación de mTLS incorpora políticas basadas en el contexto de transporte y usa el estado del certificado del cliente dentro de la sesión de TLS para tomar decisiones de autorización. En el caso de la federación de identidades para cargas de trabajo X.509, una vinculación de mTLS garantiza que todo el flujo de autenticación esté vinculado de forma segura a una carga de trabajo de confianza. Esto mitiga el riesgo de robo de credenciales, ya que la autenticación está vinculada a un extremo específico y de confianza.

Autentica una carga de trabajo

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

Permite que tu carga de trabajo externa acceda a los recursos de Cloud de Confiance

Para proporcionar a tu carga de trabajo acceso a los recursos de Cloud de Confiance , te recomendamos que otorgues acceso directo a los recursos al principal. En este caso, el principal es el usuario federado. Algunos Cloud de Confiance productos tienen limitaciones de las APIs de Google Cloud. Si tu carga de trabajo llama a un extremo de API que tiene una limitación, puedes usar la identidad temporal como cuenta de servicio. En este caso, el principal es la cuenta de servicioCloud de Confiance , que actúa como la identidad. Otorga 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"

Descarga o crea una configuración de credenciales

Las bibliotecas cliente de Cloud y la gcloud CLI pueden obtener credenciales externas de forma automática y usarlas para usar la identidad de una cuenta de servicio. Para permitir que las bibliotecas y las herramientas completen este proceso, debes proporcionar un archivo de configuración de credenciales.

Además, para la integración de certificados X.509, se requiere un archivo de configuración de certificado.

Los archivos de configuración incluyen lo siguiente:

• Credential Configuration: Es un archivo JSON que define cómo la biblioteca cliente interactúa con el servicio de token de seguridad (STS).
• Configuración del certificado: Es un archivo JSON que especifica las rutas de acceso locales para el certificado de cliente y la clave privada en tu carga de trabajo.

Crea archivos de configuración de credenciales y certificados que permitan que la biblioteca obtenga tokens de acceso con certificados X.509.

Usa la configuración de credenciales para acceder a Cloud de Confiance

Para permitir que las herramientas y las bibliotecas 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. Si descargaste un archivo ZIP de la consola de Cloud de Confiance , extráelo en tu carga de trabajo externa.

2. Actualiza el archivo de Configuración del certificado con las rutas de acceso reales a los archivos locales de tu certificado de cliente y la clave privada para los siguientes campos:

   • cert_path: Es la ruta de acceso a tu certificado de cliente.
   • key_path: Es la ruta de acceso a tu clave privada.

3. Inicializa una variable de entorno GOOGLE_APPLICATION_CREDENTIALS y configúrala en el archivo de configuración de credenciales:

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   Reemplaza FILEPATH por la ruta de acceso relativa al archivo de configuración de credenciales.

   PowerShell

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

   Reemplaza FILEPATH por la ruta de acceso relativa al archivo de configuración de credenciales.

4. Asegúrate de que la biblioteca 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 de acceso en la que extraes el archivo ZIP. (si descargaste la configuración desde la consola de Cloud de Confiance )

   • Ruta de acceso predeterminada de gcloud CLI:

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

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

   • Es la ruta de acceso establecida en la variable de entorno GOOGLE_API_CERTIFICATE_CONFIG.

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

   Go

   Las bibliotecas cliente para Go admiten la federación de identidades para cargas 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 cliente, ejecuta el siguiente comando mientras estés 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 cliente para Python admiten la federación de identidades para cargas de trabajo X.509 si usan la versión 2.39.0 o posterior del paquete google-auth.

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

     pip show google-auth
   

   Si deseas especificar un ID del proyecto para el cliente de autenticación, puedes configurar la variable de entorno GOOGLE_CLOUD_PROJECT o permitir que el cliente busque el ID del proyecto automáticamente. Para encontrar el ID del proyecto de manera automática, la cuenta de servicio en el 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 del usuario del paquete google-auth.

6. Si tu carga de trabajo se ejecuta en macOS, configura CLOUDSDK_PYTHON_SITEPACKAGES=1 para que gcloud CLI use bibliotecas de Python fuera de su directorio de instalación.

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

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

   Reemplaza FILEPATH por la ruta de acceso al archivo de configuración de credenciales.

   La compatibilidad con la federación de identidades para cargas de trabajo X.509 en gcloud CLI está disponible en la versión 538.0 y posteriores de gcloud CLI.

Obtén un token de acceso con una solicitud sin formato para acceder a Cloud de Confiance

Crea la cadena de confianza

En este paso, se muestra cómo crear la cadena de confianza. Pasas la cadena de confianza en el campo subject_token cuando llamas al Servicio de tokens de seguridad en una solicitud simple.

Da formato a los certificados que deben incluirse en la cadena como una lista con formato JSON, según se especifica en RFC 7515. El certificado de hoja que se usa para el protocolo de enlace 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 pasar como subject_token en la llamada al Servicio de tokens de seguridad, más adelante en esta guía.

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

Obtén 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"
   }'
   

   Reemplaza lo siguiente:

   • CLIENT_CERT_KEY: La clave privada del certificado del cliente
   • CLIENT_CERT: El certificado de cliente

   • WORKLOAD_IDENTITY_POOL_URI: Es la URL del proveedor de grupos de identidades para cargas de trabajo en el siguiente formato:

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

   • TRUST_CHAIN: Es la cadena de confianza necesaria para verificar el certificado de hoja. Debe incluir, al menos, CLIENT_CERT como primer elemento. Si seguiste las instrucciones de la sección Da formato a los certificados, reemplaza TRUST_CHAIN por '"${TRUST_CHAIN}"'.

   Para usar extremos regionales del servicio de token de seguridad, reemplaza https://sts.mtls.s3nsapis.fr/v1/token por lo siguiente:

    https://sts.REGION.rep.mtls.s3nsapis.fr/v1/token 

   Reemplaza REGION por una Cloud de Confiance ubicación, por ejemplo, us-central1 o europe-west4.

2. Opcional: Si usas la identidad temporal como cuenta de servicio, llama al método generateAccessToken de la API de Service Account Credentials de IAM con el token del servicio de tokens de seguridad para obtener un token de acceso.

   curl -X POST 'https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken' \
       -H "Content-Type: application/json; charset=utf-8" \
       -H "Authorization: Bearer STS_TOKEN" \
       -d '{"scope": ["https://www.googleapis.com/auth/cloud-platform"]}'
   

   Reemplaza lo siguiente:

   • SERVICE_ACCOUNT_EMAIL: La dirección de correo electrónico de la cuenta de servicio.
   • STS_TOKEN: Es el token de acceso que generó el servicio de tokens de seguridad en el paso anterior.

3. Usa el token de acceso de portador para acceder a los recursos deCloud de Confiance , por ejemplo:

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

Límites

En la siguiente tabla, se enumeran los límites.

¿Qué sigue?

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