GitHub Actions con OIDC: cómo desplegar sin guardar una clave permanente en secrets

OIDC en GitHub Actions permite desplegar sin mantener una clave permanente de acceso a la nube en secrets. En lugar de recuperar una credencial estática, el job solicita a GitHub un token OIDC firmado, el proveedor de nube valida la identidad y las condiciones incluidas en ese token y, si la política de confianza lo permite, entrega una credencial de corta duración. El beneficio principal es reducir la exposición de claves de larga vida, pero la seguridad depende de qué tan limitada esté la relación de confianza.

El flujo recomendado combina cuatro controles: limitar quién puede solicitar el token OIDC, restringir qué identidades de GitHub acepta el proveedor, conceder al rol de nube solo los permisos necesarios y proteger el camino de despliegue dentro del repositorio. La documentación de GitHub destaca que el proveedor debe aplicar condiciones para impedir que repositorios no confiables obtengan acceso a los recursos de nube. Consulta la guía oficial de OIDC para proveedores de nube.

Qué cambia cuando sustituyes una clave permanente por OIDC

Con una clave estática, el workflow suele leer un par de credenciales desde un secret y presentarlo directamente al proveedor. Ese valor sigue siendo válido hasta que caduque o sea revocado, incluso fuera de la ejecución que originalmente lo necesitaba. Con OIDC, GitHub emite un JWT vinculado al contexto de la ejecución. El JWT contiene claims como issuer, audience, subject, repositorio, referencia Git y, en algunos casos, environment y otros atributos.

El proveedor no debe confiar en un token solo porque haya sido emitido por GitHub. Debe comparar los claims con una política de confianza. Si la política acepta únicamente el repositorio, la branch, el environment u otro contexto esperado, el token puede intercambiarse por una credencial temporal. Si los valores no coinciden, el intercambio debe fallar. Esa verificación es la que convierte OIDC en una frontera de autorización útil.

1. Configura la confianza en el proveedor antes de cambiar el workflow

El issuer de GitHub Actions es https://token.actions.githubusercontent.com. Los pasos siguientes dependen del proveedor, pero el modelo es el mismo: registrar GitHub como proveedor OIDC y crear una política que acepte únicamente las identidades previstas.

Los dos claims más habituales para esta decisión son aud y sub. La audience varía según el proveedor y la acción de login. El subject representa el contexto del workflow y puede incluir repositorio, branch, tag o environment. Un ejemplo tradicional para una branch es repo:ORG/REPO:ref:refs/heads/main. Cuando un job usa un environment, el subject puede reflejar el nombre de ese ambiente. La referencia oficial también enumera claims adicionales como repository_id, repository_visibility, workflow_ref y job_workflow_ref, que pueden permitir políticas más granulares cuando el proveedor puede evaluarlos. Consulta la referencia de claims OIDC.

Existe un cambio importante de 2026 para políticas de confianza nuevas. Los repositorios creados después del 15 de julio de 2026 usan por defecto un subject inmutable que incluye los ID del propietario y del repositorio. Los cambios de nombre y las transferencias posteriores a esa fecha también pasan al formato inmutable. Los repositorios anteriores conservan el formato previo salvo que opten por el formato inmutable. Antes de copiar una condición de sub desde un ejemplo antiguo, inspecciona el claim real emitido para tu repositorio y haz que la política del proveedor coincida con él.

Limita la confianza al contexto mínimo que representa el despliegue

• Prefiere un repositorio específico en lugar de toda la organización cuando el rol solo atiende a un proyecto.
• Para producción, usa un environment dedicado y exige el contexto de producción en la confianza de nube siempre que el proveedor lo permita.
• Si el despliegue solo sale de main, no dejes el mismo rol disponible para cualquier branch.
• Si la arquitectura usa un workflow reutilizable central para desplegar, evalúa condiciones vinculadas al workflow de llamada o a job_workflow_ref, según el soporte del proveedor.
• Evita comodines amplios en el subject. Un patrón demasiado cómodo puede convertir el compromiso de un repositorio en un camino hacia recursos que deberían estar aislados.

2. Concede id-token: write solo al job que necesita autenticarse

En GitHub Actions, id-token: write es el permiso necesario para solicitar el JWT OIDC. Por sí mismo, no concede permisos de escritura sobre recursos de nube ni sobre el repositorio. Su efecto es permitir que el job obtenga el token que después presentará a un proveedor externo. La documentación de GitHub también muestra contents: read cuando el workflow hace checkout del contenido del repositorio.

Cuando sea posible, configura el permiso a nivel del job de despliegue en lugar de concederlo a todos los jobs del workflow. Así se reduce la cantidad de pasos que pueden solicitar un token OIDC.

El fragmento anterior es una plantilla, no un workflow listo para copiar. Sustituye la acción y las entradas por los valores documentados por tu proveedor. Para acciones de terceros, GitHub recomienda fijar la referencia a un SHA completo de commit cuando necesitas una versión inmutable. Consulta la guía de uso seguro de GitHub Actions.

3. Intercambia el JWT por una credencial temporal mediante la integración del proveedor

El workflow no usa directamente el JWT de GitHub para administrar la nube. El paso de autenticación lo presenta al servicio de identidad del proveedor, que verifica firma, issuer, audience, subject y demás condiciones. Si coinciden, el proveedor devuelve una credencial temporal asociada al rol o identidad permitida.

Los detalles no son idénticos entre nubes. Por ejemplo, la guía de GitHub para AWS indica que los claims OIDC personalizados no están disponibles en ese camino, mientras que otros proveedores pueden ofrecer formas distintas de mapear o filtrar atributos. Por eso conviene usar la documentación específica del proveedor en lugar de trasladar una trust policy de una nube a otra. Consulta las guías oficiales para AWS, Azure y Google Cloud.

4. OIDC no sustituye el principio de privilegio mínimo en el rol de nube

Eliminar la clave permanente resuelve solo una parte del problema. Si el rol temporal puede administrar toda la cuenta, un workflow comprometido aún puede causar un impacto importante mientras la credencial sea válida. La identidad federada debe asumir un rol diseñado para ese despliegue, con acciones y recursos restringidos.

Para un pipeline que publica un artefacto y actualiza un servicio, el rol no necesita permisos de administrador global. Limita el acceso a los buckets, registries, servicios, proyectos, subscriptions o resource groups realmente utilizados. Cuando el proveedor lo permita, limita también la duración de la sesión y separa roles de producción y no producción.

Este diseño crea dos barreras independientes: la trust policy decide quién puede asumir la identidad; la política de autorización decide qué puede hacer esa identidad. Ambas deben ser mínimas.

5. Usa environments para proteger el camino de producción

Si la política OIDC depende de un environment, protege ese environment en GitHub. Las reglas de protección de despliegue pueden exigir revisión, restringir branches y tags o aplicar otras condiciones antes de que el job continúe. GitHub recomienda reglas de protección adicionales cuando los environments participan en workflows o políticas OIDC. Consulta la documentación de deployments y environments.

Una configuración habitual para producción permite despliegues solo desde branches seleccionadas, exige revisión cuando el riesgo lo justifica e impide que un job de otra branch use el mismo camino de producción. Esto complementa la trust policy: el proveedor valida la identidad que recibe y GitHub controla qué ejecuciones pueden llegar al job protegido.

6. Haz pruebas de denegación, no solo un despliegue que funciona

Una prueba positiva demuestra que la configuración puede autenticarse. No demuestra que la política rechace contextos no deseados. Después del primer despliegue correcto, ejecuta escenarios que deberían fallar y verifica en qué etapa ocurre la denegación.

• Elimina temporalmente id-token: write en una branch de prueba y confirma que el job no puede solicitar el JWT.
• Intenta autenticarte desde una branch que no debería poder asumir el rol.
• Si producción exige un environment, prueba el mismo flujo sin ese environment o con otro nombre.
• Si la política restringe repositorio o workflow, verifica que un contexto diferente no reciba una credencial.
• Confirma que la credencial no pueda ejecutar una operación fuera del alcance necesario para el despliegue.

GitHub también ofrece mecanismos para inspeccionar los claims OIDC antes de terminar la integración con el proveedor. Esto es útil para descubrir el sub real, revisar aud y evitar construir una trust policy basada en suposiciones.

Errores comunes que debilitan el diseño

• Confiar en todo un owner u organización: es cómodo, pero amplía el conjunto de repositorios capaces de llegar al rol de nube.
• Conceder id-token: write globalmente sin necesidad: aumenta la cantidad de jobs capaces de solicitar un token.
• Usar un rol amplio porque la credencial es temporal: la corta duración reduce la ventana, no el poder de la sesión.
• Copiar un subject antiguo: en 2026, los repositorios nuevos pueden usar el formato inmutable con ID, por lo que la confianza debe coincidir con el claim real.
• Dejar acciones críticas en tags móviles sin evaluación: la identidad federada no protege frente a código de acción modificado. Fijar acciones a un SHA completo reduce ese riesgo.
• Proteger la nube y olvidar el environment: si cualquier branch puede llegar al job de producción, el diseño efectivo puede ser más amplio de lo previsto.

Checklist para un despliegue OIDC con acceso limitado

• Registrar https://token.actions.githubusercontent.com como issuer según la documentación del proveedor de nube.
• Definir condiciones explícitas de confianza para repositorio y contexto de despliegue.
• Comprobar el sub real, especialmente en repositorios creados, renombrados o transferidos después del 15 de julio de 2026.
• Conceder id-token: write solo al job que se autentica con la nube.
• Mantener GITHUB_TOKEN y los demás permisos en el nivel mínimo necesario.
• Usar la acción oficial de autenticación del proveedor o una implementación equivalente documentada.
• Restringir el rol de nube a las acciones, recursos y duración de sesión necesarios para el despliegue.
• Proteger el environment de producción con reglas adecuadas al riesgo.
• Fijar acciones críticas a SHA completos de commit cuando se requiera inmutabilidad.
• Ejecutar pruebas de denegación para branch, environment, repositorio y alcance de autorización.

Cuando estas capas están alineadas, OIDC elimina la necesidad de guardar una clave de nube de larga duración en GitHub y convierte cada ejecución en una autenticación contextual. El objetivo no es simplemente cambiar un secret por un token, sino garantizar que solo el workflow correcto, en el contexto correcto y durante el tiempo necesario pueda asumir una identidad con privilegio mínimo.