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 Google Cloud y acceder a Google Cloud 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 enGoogle Cloud . 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 Google Cloud 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 deGoogle Cloud .

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.

• Un AC intermedia es un certificado de autoridad certificadora 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. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

Te recomendamos que uses un proyecto dedicado para administrar grupos de identidades para cargas de trabajo y proveedores.

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

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

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Roles requeridos

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 Google Cloud 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 Workload Identity para obtener tokens de Google Cloudcorta 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 Workload Identity y un proveedor de grupos de Workload Identity. 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 Google Cloud .

Crea el grupo de identidades para cargas de trabajo

1. Para crear un nuevo grupo de Workload Identity, ejecuta el siguiente comando:

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

   Reemplaza lo siguiente:

   • POOL_ID: el ID único para el grupo.
   • DISPLAY_NAME: el nombre del grupo.
   • DESCRIPTION: una descripción del grupo que eliges. Esta descripción aparece cuando otorgas acceso a identidades de grupo.

Crea el proveedor del grupo de identidades para cargas de trabajo

1. Para agregar un proveedor de grupos de identidades para cargas 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"
   

   Reemplaza lo siguiente:

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

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 los 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 Google Cloud

Para proporcionar a tu carga de trabajo acceso a los recursos de Google Cloud , te recomendamos que otorgues acceso directo a los recursos al principal. En este caso, el principal es el usuario federado. Algunos Google Cloud 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 el robo de identidad temporal como cuenta de servicio. En este caso, el principal es la cuenta de servicioGoogle Cloud , 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 gcloud CLI pueden obtener credenciales externas de forma automática y usarlas para actuar en nombre 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. En este archivo, se proporciona la siguiente información:

• Dónde obtener credenciales externas
• Qué grupo y proveedor de identidades para cargas de trabajo usar
• Qué cuenta de servicio actuará en nombre de ella

Además, para la integración de certificados X.509, se requiere un archivo de configuración de certificado. Este archivo contiene rutas de acceso al certificado de cliente X.509 y a los archivos de claves privadas.

Crea archivos de configuración de credenciales y certificados que permitan que la biblioteca obtenga tokens de acceso con 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

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

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. 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.

2. 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 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.

3. 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.

4. Si tu carga de trabajo se ejecuta en macOS, configura CLOUDSDK_PYTHON_SITEPACKAGES=1 para configurar gcloud CLI de modo 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
   

   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 Google Cloud

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 este documento.

   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.googleapis.com/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: 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 Cómo dar formato a los certificados, reemplaza TRUST_CHAIN por '"${TRUST_CHAIN}"'.

2. Usa el token de acceso de portador que se generó en el paso anterior para acceder a los recursos deGoogle Cloud , por ejemplo:

   curl -X GET 'https://storage.googleapis.com/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.