OpenID Connect

Información general de OpenID Connect (OIDC)

          GitHub Actions Los flujos de trabajo a menudo están diseñados para acceder a un proveedor de nube (como AWS, Azure, GCP, HashiCorp Vault y otros) con el fin de implementar software o usar los servicios de la nube. Antes de que un flujo de trabajo pueda acceder a estos recursos, este suministrará credenciales, tales como contraseña o token, al proveedor de servicios en la nube. Estas credenciales normalmente se almacenan como un secreto en GitHuby el flujo de trabajo presenta este secreto al proveedor de nube cada vez que se ejecuta.

Sin embargo, el uso de secretos codificados requiere crear credenciales en el proveedor de nube y luego duplicarlas en GitHub como un secreto.

Después de establecer una conexión de confianza con un proveedor de nube que admita OIDC, puedes configurar el flujo de trabajo para solicitar un token de acceso de corta duración directamente al proveedor de nube.

Beneficios de utilizar OIDC

Al actualizar tus flujos de trabajo para que utilicen tokens de OIDC, puedes adoptar las siguientes buenas prácticas de seguridad:

        **Sin secretos en la nube:** No tendrá que duplicar sus credenciales de la nube como secretos permanentes GitHub. En vez de esto, puedes configurar la confianza de OIDC en tu proveedor de servicios en la nube y luego actualizar tus flujos de trabajo para que soliciten un token de acceso de vida corta desde dicho proveedor mediante OIDC.

        **Administración de la autenticación y la autorización:** tiene un control más preciso sobre cómo los flujos de trabajo pueden usar las credenciales, mediante las herramientas de autenticación (authN) y autorización (authZ) del proveedor de servicios en la nube para controlar el acceso a los recursos de nube.

        **Rotación de credenciales**: con OIDC, el proveedor de servicios en la nube emite un token de acceso de duración breve que solo es válido para un trabajo y después expira de forma automática.

Cómo se integra OIDC con GitHub Actions

En el diagrama siguiente se proporciona información general sobre cómo GitHubse integra el proveedor OIDC con los flujos de trabajo y el proveedor de nube:

Diagrama de cómo se integra un proveedor de nube con GitHub Actions a través de tokens de acceso e identificadores de rol de nube de token web JSON.

Establece una relación de confianza de OIDC en el proveedor de nube, lo que permite que flujos de trabajo específicos GitHub soliciten tokens de acceso a la nube en nombre de un rol de nube definido.
Cada vez que se ejecuta el trabajo, el proveedor de OIDC GitHub genera automáticamente un token de OIDC. Este token contiene notificaciones múltiples para establecer una identidad verificable y fortalecida en seguridad sobre el flujo de trabajo específico que está tratando de autenticar.
Un paso o una acción en el proceso de trabajo puede solicitar un token del proveedor OIDC de GitHub, que luego se puede presentar al proveedor de la nube como prueba de la identidad del flujo de trabajo.
Una vez que el proveedor de identidad valide con éxito las notificaciones que se presentan en el token, este proporciona un token de acceso a la nube de vida corta que está disponible únicamente por la duración del job.

Entender el token de OIDC

Cada trabajo solicita un token OIDC del GitHub proveedor OIDC, que responde con un token web JSON (JWT) generado automáticamente que es único para cada tarea del flujo de trabajo donde se genera. Cuando se ejecuta el job, el token de OIDC se presenta al proveedor de servicios en la nube. Para validar el token, el proveedor de servicios en la nube verifica si el asunto del token de OIDC y otros reclamos empatan con las condiciones que se preconfiguraron en la definición de confianza de OIDC del rol en la nube.

El siguiente token de OIDC de ejemplo usa un asunto (sub) que hace referencia a un entorno de trabajo denominado prod en el repositorio octo-org/octo-repo.

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "example-thumbprint",
  "kid": "example-key-id"
}
{
  "jti": "example-id",
  "sub": "repo:octo-org/octo-repo:environment:prod",
  "environment": "prod",
  "aud": "https://github.com/octo-org",
  "ref": "refs/heads/main",
  "sha": "example-sha",
  "repository": "octo-org/octo-repo",
  "repository_owner": "octo-org",
  "actor_id": "12",
  "repository_visibility": "private",
  "repository_id": "74",
  "repository_owner_id": "65",
  "run_id": "example-run-id",
  "run_number": "10",
  "run_attempt": "2",
  "runner_environment": "github-hosted",
  "actor": "octocat",
  "workflow": "example-workflow",
  "head_ref": "",
  "base_ref": "",
  "event_name": "workflow_dispatch",
  "repo_property_workspace_id": "ws-abc123",
  "ref_type": "branch",
  "job_workflow_ref": "octo-org/octo-automation/.github/workflows/oidc.yml@refs/heads/main",
  "iss": "https://token.actions.githubusercontent.com",
  "nbf": 1632492967,
  "exp": 1632493867,
  "iat": 1632493567
}

Autenticación de acciones personalizadas mediante OIDC

Las acciones personalizadas usan el método getIDToken() del kit de herramientas de Actions o un comando curl para autenticarse mediante OIDC.

Para más información, consulta Referencia de OpenID Connect.

Actualizar tus flujos de trabajo para OIDC

          GitHub Actions los flujos de trabajo pueden usar tokens de OIDC en lugar de secretos para autenticarse con proveedores de nube. Muchos proveedores de nube conocidos ofrecen acciones oficiales de inicio de sesión que simplifican el proceso de uso de OIDC en tus flujos de trabajo. Para más información sobre cómo actualizar tus flujos de trabajo con proveedores de nube específicos, consulta [AUTOTITLE](/actions/how-tos/security-for-github-actions/security-hardening-your-deployments).

Uso de propiedades personalizadas del repositorio como atributos de OIDC

Los administradores organizacionales y empresariales pueden incluir propiedades personalizadas del repositorio como reclamaciones en tokens OIDC. Esto habilita las directivas de control de acceso basado en atributos (ABAC) en el proveedor de nube, el registro de artefactos o el administrador de secretos que están controlados por metadatos del repositorio en lugar de listas de permitidos codificadas de forma rígida.

Cómo funcionan las reclamaciones de propiedades personalizadas

El flujo de un extremo a otro para usar propiedades personalizadas como reclamaciones OIDC es el siguiente:

       **Defina propiedades personalizadas.** Un administrador de organización o de empresa crea propiedades personalizadas (por ejemplo, `business_unit`, `data_classification`o `environment_tier`) y asigna valores a los repositorios. Para obtener más información, vea [AUTOTITLE](/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) y [AUTOTITLE](/actions/reference/security/oidc#including-repository-custom-properties-in-oidc-tokens).

       **Habilite las propiedades en tokens de OIDC.** Una organización o administrador de empresa selecciona qué propiedades personalizadas deben incluirse en tokens OIDC, mediante la interfaz de usuario de configuración o la API REST.

       **Las reclamaciones aparecen automáticamente.** Cada ejecución de flujo de trabajo en un repositorio que tenga un valor establecido para una propiedad habilitada incluirá ese valor en su token OIDC, con el prefijo `repo_property_`. No se requieren cambios de configuración de nivel de flujo de trabajo.

       **Actualice las directivas de confianza en la nube.** Las condiciones de confianza de tu proveedor de servicios en la nube se actualizan para evaluar las nuevas `repo_property_*` reivindicaciones, permitiendo tomar decisiones de acceso precisas basadas en atributos.

Dado que esto se basa en GitHubde el modelo de credenciales de corta duración de OIDC existente, no se requieren secretos de larga duración y cada token tiene ámbito, es auditable y se rota automáticamente en cada ejecución de flujo de trabajo.

Prerrequisitos

Las propiedades personalizadas ya deben definirse en el nivel de organización o de empresa. Para más información, consulta Administración de propiedades personalizadas para repositorios de la organización.
Debe ser administrador de la organización o administrador de empresa.

Adición de una propiedad personalizada a las declaraciones del token de OIDC

Para incluir una propiedad personalizada en tokens de OIDC, use la API REST o la interfaz de usuario de configuración de su organización o empresa.

        **Uso de la interfaz de configuración:** vaya a la página de configuración Actions OIDC de la organización o de la empresa para ver y administrar qué propiedades personalizadas se incluyen en los tokens de OIDC.

        **Uso de la API REST:** Envíe una `POST` solicitud al `/orgs/{org}/actions/oidc/customization/properties/repo` endpoint para agregar una propiedad personalizada a las reclamaciones del token de OIDC para su organización. Para obtener parámetros de solicitud y detalles completos, consulte la documentación de la API REST para administrar propiedades personalizadas de OIDC: [AUTOTITLE](/rest/actions/oidc).

Ejemplo de token OIDC con propiedades personalizadas

En el ejemplo siguiente se muestra un token OIDC que incluye dos propiedades personalizadas: una propiedad business_unit de selección única y una propiedad workspace_idde cadena . Cada propiedad personalizada aparece en el token con el repo_property_ prefijo .

{
  "sub": "repo:my-org/my-repo:ref:refs/heads/main",
  "aud": "https://github.com/my-org",
  "repository": "my-org/my-repo",
  "repository_owner": "my-org",
  "ref": "refs/heads/main",
  "repo_property_business_unit": "payments",
  "repo_property_workspace_id": "ws-abc123"
}

Puede usar las repo_property_* declaraciones en las condiciones de confianza del proveedor de nube para crear directivas de control de acceso flexibles basadas en atributos. Para obtener más información sobre el formato de notificación, los tipos de propiedad admitidos y los límites, consulte Referencia de OpenID Connect.

Compatibilidad con OIDC para Dependabot

          Dependabot puede usar OIDC para autenticarse con registros privados, lo que elimina la necesidad de almacenar credenciales de larga duración como secretos de repositorio. Con la autenticación basada en OIDC, los Dependabot trabajos de actualización pueden obtener dinámicamente credenciales de corta duración del proveedor de identidades en la nube.

          Dependabot admite la autenticación OIDC para cualquier tipo de registro que use `username` y `password` autenticación, cuando el registro se hospede en AWS CodeArtifact, Azure DevOps Artifacts o JFrog Artifactory.

Las ventajas de la autenticación OIDC para Dependabot son:

        **Seguridad mejorada:** Elimina las credenciales estáticas y de larga duración de los repositorios.

        **Administración más sencilla:** Habilita el acceso seguro y compatible con directivas a registros privados.

        **Evite la limitación de velocidad:** Las credenciales dinámicas le ayudan a evitar alcanzar los límites de velocidad asociados a tokens estáticos.

Para más información, consulta Configuración del acceso a registros privados para Dependabot.

Pasos siguientes

Para más información sobre la configuración de OIDC, consulta Fortalecer la seguridad de tus despliegues.

Para obtener información de referencia sobre OIDC, consulta Referencia de OpenID Connect.

En este artículo