Saltar al contenido

¿Qué es OIDC en GitHub Actions?

Última actualización

OIDC (OpenID Connect) en GitHub Actions es una forma de que un workflow demuestre su identidad ante un proveedor de nube y reciba credenciales de corta duración, de modo que no necesita guardar claves de acceso de larga duración como secretos del repositorio.

Cómo funciona

Cada job puede solicitar a GitHub un JSON Web Token (JWT) firmado. El token contiene declaraciones sobre la ejecución: el repositorio, la rama o etiqueta, el entorno, el workflow y más. Usted configura su nube (AWS, Google Cloud, Azure y otras) para que confíe en el emisor de tokens de GitHub y para que acepte los tokens solo cuando sus declaraciones coincidan con las reglas que establece, por ejemplo, "el repositorio es acme/api y la rama es main".

En tiempo de ejecución, el job intercambia el token por credenciales temporales, normalmente válidas durante una hora o menos. Caducan por sí solas, así que una línea de registro filtrada resulta mucho menos peligrosa que una clave permanente filtrada.

El job necesita permiso para solicitar el token, por eso los workflows que usan OIDC establecen id-token: write.

Ejemplo

permissions:
  id-token: write   # allow requesting the OIDC token
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-deploy
          aws-region: us-east-1
      - run: aws sts get-caller-identity

La política de confianza del rol determina qué repositorios y ramas pueden asumirlo. Una configuración paso a paso está en OIDC de GitHub Actions con AWS.

Por qué usarlo

  • No hay secretos que rotar ni que filtrar.
  • Las credenciales se limitan a una única ejecución.
  • Las reglas de acceso pueden vincularse a la rama, a la etiqueta o al entorno.
  • Los registros de auditoría de la nube muestran qué workflow asumió qué rol.

Errores comunes

  • Olvidar id-token: write. Sin él, la solicitud del token falla con un error de permisos.
  • Política de confianza demasiado amplia. Una regla que coincida con repo:acme/* permite que cualquier repositorio de la organización asuma el rol. Fije el repositorio y, idealmente, la rama o el entorno.
  • Definir permissions al inicio y omitir contents: read. Una vez que enumera algún permiso, los que no aparecen en la lista quedan sin acceso por defecto.
  • Esperar que funcione en pull requests desde forks. Por defecto, los workflows de forks no reciben tokens con permisos de escritura ni secretos.
  • Tratar el token como un almacén de secretos. Solo demuestra identidad. La autorización sigue dependiendo de las políticas de su nube.

OIDC funciona en cualquier runner, incluido un self-hosted runner, ya que el token procede de GitHub y no de la máquina. Más consejos de refuerzo de seguridad están en cómo proteger GitHub Actions.

Preguntas frecuentes

¿OIDC reemplaza todos los secretos?

No. Reemplaza las claves de acceso a la nube. Los tokens de API de servicios de terceros que no admiten OIDC siguen necesitando secretos.

¿Qué nubes admiten OIDC de GitHub?

AWS, Google Cloud y Azure lo documentan, al igual que HashiCorp Vault y muchas otras herramientas. Consulte la documentación de su proveedor para la configuración exacta.

¿Es seguro para pull requests?

Restrinja las políticas de confianza a ramas o entornos específicos para que el código de los pull requests no pueda asumir roles de despliegue.