Web y desarrollo

GitHub Actions OIDC: Cómo asegurar tus despliegues sin secretos de larga duración

GitHub Actions OIDC: How to Secure Your Deployments Without Long-Lived Secrets

Aprende cómo fortalecer la seguridad de los despliegues de GitHub Actions con OIDC. Sustituye las credenciales de nube de larga duración por tokens de corta duración, restringe el acceso usando políticas de confianza IAM y protege tus pipelines CI/CD.

GitHub Actions OIDC: Cómo proteger tus despliegues sin utilizar secretos de larga duración

Desplegar una aplicación desde GitHub Actions suele requerir acceso a infraestructura externa. Un flujo de trabajo puede subir archivos a Amazon S3, publicar contenedores o actualizar recursos en la nube. Tradicionalmente, los equipos almacenan una clave de acceso a la nube en los secretos de GitHub. Esto funciona, pero una credencial de larga duración sigue siendo útil para un atacante si un flujo de trabajo, una dependencia o un registro la expone.

OpenID Connect (OIDC) ayuda a fortalecer la seguridad de CI/CD al reemplazar las credenciales cloud de larga duración con un acceso temporal concedido únicamente a identidades de flujo de trabajo autorizadas. Reduce la exposición de credenciales, limita el acceso no autorizado y permite implementaciones en producción más controladas.

Este tutorial explica los beneficios de seguridad, muestra una configuración práctica de AWS e identifica las protecciones que aún necesitas. OIDC no es un interruptor mágico de seguridad: la política de confianza, los permisos de rol y los controles de flujo de trabajo son igual de importantes que el intercambio de tokens.

Por qué la seguridad de los despliegues es importante

Los pipelines de CI/CD son automatizaciones privilegiadas. Pueden ser capaces de reemplazar el código de producción, subir activos, leer configuraciones de despliegue o modificar la infraestructura. Por lo tanto, un pipeline comprometido puede tener un impacto mayor que una estación de trabajo de desarrollador comprometida.

Tres riesgos comunes merecen especial atención:

  • Exposición de credenciales: una clave estática de la nube robada desde un entorno de compilación puede seguir siendo válida hasta que alguien la revoque.
  • Privilegios excesivos: una credencial de despliegue con permisos de administrador puede afectar a servicios no relacionados.
  • Despliegue no autorizado: una rama o flujo de trabajo no confiable podría obtener acceso a la producción si las comprobaciones de identidad son demasiado amplias.

OIDC aborda parte de este problema al vincular la autenticación a una identidad de flujo de trabajo verificable y de corta duración. No reemplaza el principio de privilegios mínimos de IAM, la revisión de código o la protección del entorno.

¿Qué es OIDC en GitHub Actions?

OpenID Connect es una capa de identidad construida sobre OAuth 2.0. GitHub Actions puede solicitar un token JSON Web firmado (JWT) del proveedor de OIDC de GitHub:

https://token.actions.githubusercontent.com

El token contiene reclamaciones que describen la identidad del trabajo y su contexto de ejecución. Un servicio de identidad cloud valida la firma del token, el emisor, el público y las reclamaciones relevantes, y luego decide si emitir credenciales temporales.

El servicio externo debe confiar explícitamente en la identidad del flujo de trabajo de GitHub prevista. Simplemente habilitar OIDC en un archivo YAML no otorga acceso.

Consulta la documentación de OIDC de GitHub.

Credenciales estáticas vs OIDC: comparación de seguridad

Consideración de seguridad Clave de acceso de larga duración Federación OIDC
Credencial cloud permanente en GitHub Comúnmente requerida No requerida para proveedores compatibles
Vida útil de la credencial Hasta su expiración o revocación Sesión temporal
Responsabilidad de rotación El equipo debe gestionar el ciclo de vida de la clave El proveedor cloud emite credenciales de corta duración
Restricciones de identidad Depende del almacenamiento de credenciales y de IAM La política de confianza puede restringir la identidad del flujo de trabajo
Autorización Permisos de IAM Los permisos de IAM siguen siendo necesarios
Riesgo restante Robo y reutilización de una clave estática Flujo de trabajo autorizado comprometido o confianza demasiado amplia

OIDC reduce el riesgo y el impacto del robo de credenciales; no elimina todos los secretos. Las aplicaciones pueden seguir necesitando contraseñas de bases de datos, claves de firma o tokens de API de terceros.

Cómo funciona el flujo de autenticación de OIDC

  1. Un trabajo autorizado de GitHub Actions solicita un token de identidad.
  2. GitHub emite un JWT firmado para ese trabajo.
  3. El flujo de trabajo presenta el token al servicio de identidad cloud.
  4. El proveedor cloud valida el token y evalúa sus condiciones de confianza configuradas.
  5. Si la identidad es permitida, el proveedor emite credenciales temporales.
  6. El flujo de trabajo utiliza esas credenciales dentro del alcance permitido del rol.

El proveedor cloud debe rechazar un token cuyo sujeto, público u otras condiciones requeridas no coincidan. Esa validación es el límite entre un despliegue seguro y uno que confía demasiado.

Paso 1: Configurar el proveedor OIDC de GitHub en AWS

AWS IAM soporta proveedores de identidad OpenID Connect. Crea un proveedor de identidad usando:

| Configuración | Valor | |---|---|---| | URL del proveedor | https://token.actions.githubusercontent.com | | Público | sts.amazonaws.com | | Tipo de proveedor | OpenID Connect |

El público identifica al destinatario previsto del token. La acción de credenciales de AWS normalmente usa sts.amazonaws.com.

Consulta la configuración del rol OIDC de AWS IAM.

Paso 2: Restringir quién puede asumir el rol de despliegue

Crea un rol de IAM cuya política de confianza permita sts:AssumeRoleWithWebIdentity solo desde el proveedor de identidad de GitHub y la identidad del flujo de trabajo prevista.

El siguiente ejemplo usa el formato de sujeto tradicional basado en ramas de GitHub:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:example-org/example-app:ref:refs/heads/main"
        }
      }
    }
  ]
}

Reemplaza el número de cuenta de AWS, la organización y el repositorio.

No copies la condición del sujeto ciegamente. GitHub ha introducido un formato de sujeto predeterminado inmutable para los repositorios creados después del 15 de julio de 2026. Comprueba el formato de sujeto real utilizado por tu repositorio y configura AWS para que coincida con él. Los flujos de trabajo basados en entornos también pueden usar una forma de sujeto diferente. Consulta la referencia de tokens OIDC de GitHub.

Una política de confianza restrictiva es una de las formas más importantes de prevenir que flujos de trabajo no autorizados obtengan credenciales de producción. Evita sujetos con comodines que autoricen accidentalmente repositorios o contextos no relacionados.

Paso 3: Limitar lo que el rol puede hacer

La confianza determina quién puede asumir un rol. Los permisos de IAM determinan qué puede hacer el rol después de la autenticación.

Para un despliegue que solo sube archivos a un bucket de S3, una política simplificada es:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject"],
      "Resource": "arn:aws:s3:::example-deploy-bucket/*"
    }
  ]
}
Illustration of the article's main concept

Este ejemplo permite subidas de objetos, no administración de cuentas ni eliminación de buckets. Si tu despliegue también elimina archivos obsoletos o enumera el contenido del bucket, concede solo las operaciones adicionales necesarias, como las protegidas por s3:DeleteObject o s3:ListBucket con alcance limitado.

Nunca concedas AdministratorAccess solo para que un despliegue funcione. Las credenciales temporales con privilegios excesivos pueden causar graves daños.

Paso 4: Solicitar credenciales temporales desde un flujo de trabajo

Un trabajo de despliegue debe estar autorizado para solicitar un token OIDC. El siguiente ejemplo sube un directorio preconstruido dist/ a S3:

name: Deploy website

on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-deploy-role
          aws-region: eu-west-1

      - name: Deploy website
        run: |
          aws s3 cp ./dist/ s3://example-deploy-bucket/ --recursive

El ejemplo usa referencias de acciones de versión principal para mejorar la legibilidad. En producción, revisa las versiones actuales compatibles y prefiere anclar acciones de terceros a SHA de commit completos. El ejemplo asume que el sitio web ya ha sido construido en dist/.

Observa lo que falta: no se almacena ninguna clave de acceso o clave secreta de AWS permanente en el flujo de trabajo.

La acción oficial de credenciales de AWS intercambia el token OIDC por credenciales temporales de AWS.

Paso 5: Entender id-token: write

Este permiso:

permissions:
  id-token: write

permite a un trabajo solicitar un token de identidad OIDC de GitHub. No otorga por sí solo al trabajo permiso para escribir en repositorios de GitHub o acceder a AWS.

El proveedor cloud sigue decidiendo si confiar en la identidad, y el rol de IAM sigue controlando qué operaciones están permitidas.

Concede id-token: write solo a los trabajos que realmente se autentican en la nube. Los trabajos de compilación, linting y testing generalmente no lo necesitan.

Paso 6: Proteger los entornos de producción

OIDC no puede compensar un flujo de trabajo autorizado que ejecuta código malicioso. Si un atacante puede cambiar un flujo de trabajo de despliegue confiable o ejecutar código no revisado en ese contexto, puede ser capaz de obtener credenciales temporales.

Los entornos de GitHub pueden añadir controles como restricciones de rama de despliegue y revisores requeridos, sujetos a la configuración del repositorio y a la disponibilidad del plan.

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production

    permissions:
      contents: read
      id-token: write

Cuando el flujo de trabajo usa un entorno, el sujeto OIDC puede identificar ese entorno en lugar de una rama. Actualiza la política de confianza de IAM para que coincida con las reclamaciones reales y proteja el entorno en sí.

Para la producción, combina identidades restringidas con protección de ramas, revisión de código, permisos de flujo de trabajo limitados y reglas de aprobación de entornos cuando sea apropiado. Así es como OIDC se convierte en parte de una postura de seguridad de despliegue más fuerte, en lugar de solo un reemplazo de credenciales.

Paso 7: Verificar la identidad asumida y probar las denegaciones

Después de configurar la autenticación de AWS, añade un paso de diagnóstico:

- name: Verify AWS identity
  run: aws sts get-caller-identity

Comprueba que la respuesta identifica la cuenta de AWS y el rol de despliegue previstos. El comando no revela la clave secreta de acceso.

También prueba que una rama, repositorio o entorno no autorizado no puede asumir el rol de producción. Un despliegue no autorizado fallido es una prueba de seguridad exitosa.

No registres tokens OIDC crudos ni credenciales temporales durante la depuración.

Errores comunes de seguridad y configuración de OIDC

Falta de id-token: write

El trabajo no puede solicitar un token OIDC a menos que tenga el permiso. Los permisos a nivel de trabajo pueden anular los permisos a nivel de flujo de trabajo.

Technical workflow illustration

AWS devuelve AccessDenied para la asunción de rol

Comprueba el proveedor de identidad, el público, el ARN del rol y la condición del sujeto. En particular, verifica el formato real del sujeto de GitHub en lugar de suponer que todos los repositorios usan el mismo predeterminado.

La autenticación tiene éxito, pero la subida falla

La relación de confianza puede ser correcta mientras que el rol carece de los permisos S3 necesarios. Corrige la política de permisos de IAM de alcance limitado en lugar de ampliar la confianza en la identidad.

El acceso a producción está permitido desde demasiados contextos

Un sujeto con comodín o restricciones de entorno insuficientes pueden hacer que las credenciales de producción estén disponibles para flujos de trabajo que nunca deberían recibirlas. Restringe la política de confianza y prueba los casos no autorizados.

Un pull request no puede desplegar

Los pull requests pueden tener diferentes reclamaciones y código no confiable. No debilites las condiciones de confianza de producción solo para que un pull request asuma el rol de despliegue. Ejecuta la validación por separado de la implementación en producción.

¿Se puede usar OIDC con Azure o Google Cloud?

Sí. El mecanismo de federación es similar, pero la configuración de identidad difiere.

Nube Mecanismo de federación Acción de GitHub
AWS Proveedor OIDC de IAM y rol aws-actions/configure-aws-credentials
Microsoft Azure Credenciales de identidad federada azure/login
.hero
Google Cloud Federación de identidad laboral google-github-actions/auth

Azure normalmente asocia una credencial federada con una aplicación o identidad gestionada. Google Cloud usa un grupo y proveedor de identidad laboral, con acceso directo a recursos o impersonación de cuenta de servicio dependiendo de la configuración.

Cada plataforma tiene su propio público, coincidencia de sujetos y reglas de autorización. Revisa la documentación oficial actual del proveedor antes de copiar un ejemplo.

¿Qué pasa con los sitios web PHP en alojamientos tradicionales?

No todos los proveedores de alojamiento aceptan identidades OIDC de GitHub. El alojamiento compartido y el alojamiento gestionado de PHP pueden seguir usando claves SSH, credenciales SFTP, webhooks de despliegue o tokens de API del proveedor.

Habilitar OIDC en GitHub Actions no reemplaza automáticamente una clave SSH si el servidor de destino no tiene un mecanismo de federación.

Cuando OIDC no está disponible, usa una cuenta de despliegue dedicada, permisos de alcance limitado, secretos protegidos y rotación de credenciales. Restringe el acceso al sistema de archivos y a los comandos cuando sea posible.

El objetivo de seguridad es el principio de privilegios mínimos y la exposición limitada de credenciales, independientemente de si OIDC está soportado.

Lista de verificación de seguridad de despliegues

Antes de desplegar en producción, verifica que:

  • El emisor y el público de OIDC están configurados correctamente.
  • La política de confianza coincide solo con el repositorio y el contexto de despliegue previstos.
  • La condición del sujeto refleja el formato real del token de GitHub de tu repositorio.
  • El rol de IAM tiene solo los permisos requeridos por el despliegue.
  • Solo los trabajos de despliegue reciben id-token: write.
  • Las ramas y entornos de producción tienen la protección adecuada.
  • Las acciones de terceros están revisadas y, preferiblemente, ancladas a SHA de commit inmutables.
  • Los pull requests no confiables no pueden asumir roles de producción.
  • Las ramas y repositorios no autorizados fallan en la autenticación.
  • Los tokens y credenciales temporales nunca se registran o almacenan innecesariamente.

Preguntas frecuentes

¿Es OIDC más seguro que las claves estáticas de acceso de AWS?

Reduce la exposición al robo de credenciales de larga duración. Las políticas de confianza sólidas, los permisos limitados y los flujos de trabajo protegidos siguen siendo esenciales.

¿Elimina OIDC los GitHub Secrets?

Reemplaza algunas credenciales de autenticación cloud, no todos los secretos de aplicaciones o claves de API.

¿Qué otorga id-token: write?

Permite a un flujo de trabajo solicitar un token de identidad. Los permisos cloud son determinados separadamente por el proveedor.

¿Pueden los pull requests no confiables usar credenciales OIDC de producción?

No deberían. Configura condiciones de confianza restrictivas y mantén los despliegues en producción separados del código no confiable.

¿Funciona OIDC con cualquier proveedor de alojamiento?

No. El servicio de destino o un intermediario de identidad debe soportar y confiar en los tokens OIDC de GitHub.

Conclusión: fortalecer la seguridad, no solo la autenticación

GitHub Actions OIDC es una forma efectiva de aumentar la seguridad de los despliegues para los servicios cloud compatibles. Elimina la necesidad de mantener claves cloud permanentes en GitHub, habilita un acceso de corta duración y permite que las políticas de confianza cloud restrinjan qué flujos de trabajo pueden desplegar.

Pero el diseño más fuerte combina OIDC con el principio de privilegios mínimos de IAM, entornos protegidos, código de flujo de trabajo revisado y pruebas explícitas de que las identidades no autorizadas son rechazadas.

El objetivo no es simplemente reemplazar un secreto. Es asegurar que solo el flujo de trabajo adecuado pueda acceder a los recursos adecuados, con los permisos mínimos y durante el tiempo práctico más corto.

Referencias oficiales