Accede a los recursos desde un proveedor de identidad de OIDC

En este documento, se muestra cómo usar la federación de identidades para acceder a los recursos de Google Cloud desde un proveedor de identidad que sea compatible con OpenID Connect (OIDC).

En general, las aplicaciones que se ejecutan fuera de Google Cloud usan claves de cuentas de servicio para acceder a los recursos de Google Cloud. Mediante la federación de identidades, puedes permitir que una identidad externa actúe en nombre de una cuenta de servicio. Esto permite que la carga de trabajo acceda a los recursos de Google Cloud directamente mediante un token de acceso de corta duración y quite la carga de seguridad y mantenimiento asociada con las claves de la cuenta de servicio.

Antes de comenzar

  1. Asegúrate de tener la función de administrador de grupo de Workload Identity (roles/iam.workloadIdentityPoolAdmin).

    Como alternativa, las funciones básicas de propietario (roles/owner) y editor (roles/editor) de IAM también incluyen los 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.

  2. Crea una cuenta de servicio de Google Cloud.

  3. Otorga acceso a la cuenta de servicio para llamar a las API de Google Cloud que requiere la carga de trabajo.

Crea un grupo de Workload Identity

Un grupo de Workload Identity es un contenedor para una colección de identidades externas. Los grupos de Workload Identity se aíslan unos de otros, pero un solo grupo puede actuar en nombre de cualquier cantidad de cuentas de servicio. En general, recomendamos crear un grupo nuevo para cada uno de tus entornos, como desarrollo, etapa de pruebas o producción.

Para crear un grupo nuevo de Workload Identity, debes proporcionar un ID. También puedes proporcionar una descripción y un nombre visible opcionales.

gcloud

Ejecuta el comando gcloud beta iam workload-identity-pools create para crear un grupo de Workload Identity:

gcloud beta iam workload-identity-pools create pool-id \
    --location="global" \
    --description="description" \
    --display-name="display-name"

La respuesta es similar a la siguiente:

Created WorkloadIdentityPool [pool-id].

REST

Mediante el método projects.locations.workloadIdentityPools.create, se crea un grupo de Workload Identity.

Método HTTP y URL:

POST https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id

Cuerpo JSON de la solicitud:

{
  "description": "description",
  "display-name": "display-name"
}

Para enviar tu solicitud, expande una de estas opciones:

Mediante este método, se muestra una Operation de larga duración similar a la siguiente:

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/operations/operation-id"
}

Agrega un proveedor de identidad de OIDC

A fin de configurar un proveedor de identidad de OIDC para el grupo de Workload Identity, proporciona al menos lo siguiente:

  • Un ID para el proveedor

  • El ID del grupo de Workload Identity de la sección anterior de este documento

  • El URI de la entidad emisora del proveedor. Por lo general, toma el formato https://example.com. Consulta la documentación de tu proveedor sobre la integración de OIDC para encontrar el URI

  • Una lista de asignaciones de atributos que mapean las reclamaciones de un token externo a los atributos de un token de Google. Usa assertion a fin de hacer referencia a la credencial externa, google para los atributos de Google y attribute para los atributos personalizados.

    Hay dos atributos de Google: google.subject y google.groups. Puedes hacer referencia a estos atributos en las vinculaciones de funciones de IAM. google.subject también aparece en las entradas de registro de Cloud Logging.

    Debes proporcionar una asignación para google.subject. Por lo general, recomendamos asignarla a assertion.sub, que debería proporcionar un identificador estable para usar en vinculaciones de funciones de IAM. La asignación se ve de la siguiente manera:

    google.subject=assertion.sub
    

    Para aserciones más complejas, puedes usar Common Expression Language. Por ejemplo, si tu grupo de Workload Identity contiene varios proveedores de identidad, puedes agregar un prefijo para quitar la ambigüedad entre ellos:

    google.subject="provider-a::" + assertion.sub
    

    El campo google.subject no puede superar los 127 caracteres.

    También puedes especificar atributos personalizados. Por ejemplo, a continuación, se mapea assertion.foo a attribute.bar:

    attribute.bar=assertion.foo
    

    Consulta la documentación de tu proveedor sobre los tokens de acceso para obtener una lista completa de las reclamaciones a las que puedes hacer referencia.

    Para hacer referencia a una parte específica de una reclamación en una expresión, usa la función extract() de CEL, que extrae un valor de una reclamación a partir de una plantilla que proporciones. Para obtener más información sobre extract(), consulta Extrae valores de atributos.

    Para verificar si una credencial contiene una reclamación, usa la función has().

  • Una lista de públicos permitidos que especifican qué valores puede contener el campo aud en la credencial externa. Puedes configurar un máximo de 10 públicos, cada uno de hasta 256 caracteres. Consulta la documentación del proveedor a fin de obtener información sobre sus valores predeterminados para aud.

    De manera alternativa, si tu proveedor de identidad te permite configurar un valor personalizado para aud, puedes dejar el parámetro de públicos permitidos y establecer el valor de aud en el nombre completo de recursos de tu proveedor de Workload Identity. El prefijo HTTP es opcional; por ejemplo:

    //iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id
    https://iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id
    

    En cualquier caso, se rechazan todas las solicitudes de intercambio de tokens que no contengan uno de los valores permitidos.

También puedes proporcionar varios parámetros opcionales:

  • Un nombre visible y una descripción

  • Una condición de atributo que especifica los atributos que debe mostrar el principal. La condición puede aplicarse a las reclamaciones de la credencial externa o a los atributos de la credencial de Google. Se rechaza cualquier solicitud que no cumpla con la condición

    Las condiciones de los atributos tienen el formato de una expresión de CEL que muestra un valor booleano. Por ejemplo, lo siguiente rechaza las solicitudes de cualquier identidad que no sea miembro de un grupo específico:

    group in assertion.groups
    

    Se recomienda el uso de condiciones de atributos si el proveedor de identidad está disponible para el público general. A fin de obtener más información sobre los casos de uso comunes para las condiciones de los atributos, consulta la descripción general de la federación de Workload Identity.

En el siguiente ejemplo, se muestra cómo agregar un proveedor de identidad:

gcloud

Ejecuta el comando gcloud beta iam workload-identity-pools providers create-oidc para agregar un proveedor de identidad:

gcloud beta iam workload-identity-pools providers create-oidc provider-id \
    --workload-identity-pool="pool-id" \
    --issuer-uri="issuer-uri" \
    --location="global" \
    --attribute-mapping="google.subject=assertion.sub"

La respuesta es similar a la siguiente:

Created WorkloadIdentityPoolProvider [provider-id].

REST

Mediante el método projects.locations.workloadIdentityPools.providers.create, se agrega un proveedor de identidad de OIDC.

Método HTTP y URL:

POST https://iam.googleapis.com/v1beta/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id

Cuerpo JSON de la solicitud:

{
  "issuerUrl": "issuer-uri"
}

Para enviar tu solicitud, expande una de estas opciones:

Mediante este método, se muestra una Operation de larga duración similar a la siguiente:

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id/operations/operation-id"
}

Otorga permiso para actuar en nombre de una cuenta de servicio

Las identidades externas no pueden acceder a la mayoría de los recursos de Google Cloud directamente. En su lugar, les otorgas la función de usuario de Workload Identity (roles/iam.workloadIdentityUser) para permitir que actúen en nombre de una cuenta de servicio.

Si deseas agregar esta vinculación de función para una identidad específica, usa el valor que mapeaste a google.subject:

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"

A fin de agregar esta vinculación para todos los miembros de un grupo, ejecuta el siguiente comando:

gcloud iam service-accounts add-iam-policy-binding service-account-email \
    --role roles/iam.workloadIdentityUser \
    --member "principalSet://iam.googleapis.com/project/project-number/workloadIdentityPools/pool-id/groups/group-name"

También puedes otorgar acceso en función de atributos personalizados. Por ejemplo:

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.custom-attribute-name/custom-attribute-value"

Para revocar el acceso, reemplaza add-iam-policy-binding por remove-iam-policy-binding.

También puedes agregar o revocar vinculaciones mediante la API de REST o las bibliotecas cliente. Para obtener más información, consulta Otorga, cambia y revoca el acceso a los recursos.

Intercambia un token externo por un token de Google

Una vez que la identidad externa tenga la capacidad de suplantar una cuenta de servicio, puedes intercambiar sus credenciales por las credenciales de Google.

Para intercambiar credenciales, haz lo siguiente:

  1. Obtén un token de ID de OIDC de tu proveedor de identidad (consulta su documentación para obtener instrucciones detalladas).

  2. Pasa el token de ID de OIDC al método token() del servicio de tokens de seguridad para obtener un token de acceso federado:

    REST

    Mediante el método token, se intercambia un token de terceros por un token de Google.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • project-number: Es el número de tu proyecto de Google Cloud.
    • pool-id: Es el ID del grupo de Workload Identity que creaste con anterioridad en este instructivo.
    • provider-id: Es el ID del proveedor de identidad que configuraste con anterioridad en este instructivo.

    Método HTTP y URL:

    POST https://sts.googleapis.com/v1beta/token

    Cuerpo JSON de la solicitud:

    {
      "audience": "//iam.googleapis.com/projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id",
      "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
      "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
      "scope": "https://www.googleapis.com/auth/cloud-platform",
      "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt",
      "subjectToken": "oidc-id-token"
    }
    

    Para enviar tu solicitud, expande una de estas opciones:

     

    El método muestra un token federado.

  3. Llama a generateAccessToken() para intercambiar el token federado por un token de acceso a una cuenta de servicio. Una cantidad limitada de API de Google Cloud admite tokens federados. Todas las API de Google Cloud admiten tokens de acceso a la cuenta de servicio.

    REST

    Mediante el método serviceAccounts.generateAccessToken de la API de credenciales de la cuenta de servicio, se genera un token de acceso de OAuth 2.0 para una cuenta de servicio.

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • project-id: El ID del proyecto de Google Cloud.
    • sa-id: El ID de la cuenta de servicio. Puede ser la dirección de correo electrónico de la cuenta de servicio con el formato sa-name@project-id.iam.gserviceaccount.com o el ID numérico único de la cuenta de servicio.
    • token: Es el token de acceso federado.

    Método HTTP y URL:

    POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-name@project-id.iam.gserviceaccount.com:generateAccessToken

    Cuerpo JSON de la solicitud:

    {
      "scope": [
        "https://www.googleapis.com/auth/cloud-platform"
      ]
    }
    

    Para enviar tu solicitud, expande una de estas opciones:

    Si la solicitud generateAccessToken tiene éxito, el cuerpo de la respuesta contendrá un token de acceso de OAuth 2.0 y un tiempo de caducidad. El accessToken se puede usar para autenticar una solicitud en nombre de la cuenta de servicio hasta que se haya alcanzado el expireTime.

    {
      "accessToken": "eyJ0eXAi...NiJ9",
      "expireTime": "2020-04-07T15:01:23.045123456Z"
    }
    

Una vez que tengas un token de acceso para una cuenta de servicio, puedes usarlo a fin de llamar a las API de Google Cloud. A tal fin, incluye el token en el encabezado Authorization de las solicitudes:

Authorization: Bearer service-account-access-token

La solicitud está autorizada como la cuenta de servicio.

Próximos pasos