Información general
OpenID Connect (OIDC) permite que tus flujos de trabajo de GitHub Actions accedan a los recursos de tu proveedor de servicios en la nube sin tener que almacenar credenciales como secretos de GitHub de larga duración.
Para utilizar OIDC, primero necesitarás configurar tu proveedor de servicios en la nube para confiar en el ODIC de GitHub como una identidad federada y entonces deberás actualizar tus flujos de trabajo para autenticarte utilizando tokens.
Prerrequisitos
- Para conocer los conceptos básicos de cómo GitHub usa OpenID Connect (OIDC) y su arquitectura y ventajas, consulta "Acerca del fortalecimiento de seguridad con OpenID Connect".
-
Antes de proceder, debes planear tu estrategia de seguridad para garantizar que los tokens de acceso solo se asignen de forma predecible. Para controlar la forma en que el proveedor de servicios en la nube emite tokens de acceso, tendrá que definir al menos una condición, para que los repositorios no confiables no puedan solicitar tokens de acceso para los recursos en la nube. Para obtener más información, vea «Acerca del fortalecimiento de seguridad con OpenID Connect».
-
Si sigues esta guía en GHE.com, comprende que debes sustituir determinados valores en la siguiente documentación. Consulte "Acerca del fortalecimiento de seguridad con OpenID Connect".
Actualizar tu flujo de trabajo de GitHub Actions
Para actualizar tus flujos de trabajo para ODIC, necesitarás hacer dos cambios a tu YAML:
- Agregar ajustes de permisos para el token.
- Utiliza la acción oficial desde tu proveedor de servicios en la nube para intercambiar el token de OIDC (JWT) por un token de acceso a la nube.
Si tu proveedor de servicios en la nube aún no ofrece una acción oficial, puedes actualizar tus flujos de trabajo para realizar estos pasos manualmente.
Note
Cuando los entornos se usan en flujos de trabajo o en directivas de OIDC, se recomienda agregar reglas de protección al entorno para mayor seguridad. Por ejemplo, puedes configurar reglas de implementación en un entorno para restringir qué ramas y etiquetas se pueden implementar en el entorno o acceder a secretos del entorno. Para obtener más información, vea «Administrar entornos para la implementación».
Agregar ajustes de permisos
La ejecución de trabajo o flujo de trabajo requiere una configuración de permissions
con id-token: write
para permitir que el proveedor OIDC de GitHub pueda crear un token web JSON para cada ejecución. No podrás solicitar el token de identificador JWT de OIDC si el valor de permissions
para id-token
no está establecido en write
, pero este valor no implica conceder acceso de escritura a ningún recurso, solo poder capturar y establecer el token de OIDC para una acción o paso para habilitar la autenticación con un token de acceso de corta duración. Cualquier configuración de confianza real se define mediante notificaciones de OIDC. Para obtener más información, consulta «Acerca del fortalecimiento de seguridad con OpenID Connect».
El valor id-token: write
permite solicitar JWT desde el proveedor OIDC de GitHub mediante uno de estos enfoques:
- Con variables de entorno en el ejecutor (
ACTIONS_ID_TOKEN_REQUEST_URL
yACTIONS_ID_TOKEN_REQUEST_TOKEN
). - Con
getIDToken()
del kit de herramientas de Acciones.
Si necesita capturar un token de OIDC para un flujo de trabajo, el permiso se puede establecer en el nivel de flujo de trabajo. Por ejemplo:
permissions: id-token: write # This is required for requesting the JWT contents: read # This is required for actions/checkout
permissions:
id-token: write # This is required for requesting the JWT
contents: read # This is required for actions/checkout
Si solo necesitas recuperar un token de OIDC para un solo job, entonces este permiso puede configurarse dentro de dicho job. Por ejemplo:
permissions: id-token: write # This is required for requesting the JWT
permissions:
id-token: write # This is required for requesting the JWT
Puede que necesite especificar permisos adicionales aquí, dependiendo de los requisitos de su flujo de trabajo.
Para flujos de trabajo reutilizables que son propiedad del mismo usuario, organización o empresa que el flujo de trabajo del autor de la llamada, se puede acceder al token de OIDC generado en el flujo de trabajo reutilizable desde el contexto del autor de la llamada.
Para los flujos de trabajo reutilizables fuera de la empresa u organización, la configuración de permissions
para id-token
debe fijarse explícitamente en write
en el nivel del flujo de trabajo del autor de la llamada o en el trabajo específico que llama al flujo de trabajo reutilizable.
Esto garantiza que el token de OIDC generado en el flujo de trabajo reutilizable solo se pueda consumir en los flujos de trabajo de la persona que llama cuando está previsto.
Para obtener más información, vea «Reutilización de flujos de trabajo».
Utilizar acciones oficiales
Si tu proveedor de servicios en la nube creó una acción oficial para utilizar OIDC con GitHub Actions, te permitirá intercambiar fácilmente el token ODIC por un token de acceso. Podrás entonces actualizar tus flujos de trabajo para utilizar este token cuando accedas a los recursos en la nube.
Por ejemplo, Alibaba Cloud creó aliyun/configure-aliyun-credentials-action
para integrarse con el uso de OIDC mediante GitHub.
Utilizar acciones personalizadas
Si tu proveedor de servicios en la nube no tiene una acción oficial o si prefieres crear scripts personalizados, puedes solicitar manualmente el Token Web JSON (JWT) del proveedor de OIDC de GitHub.
Si no estás utilizando una acción oficial, entonces GitHub recomienda que utilices el kit de herramientas nuclear de las acciones. Como alternativa, puede usar las siguientes variables de entorno para recuperar el token: ACTIONS_ID_TOKEN_REQUEST_TOKEN
, ACTIONS_ID_TOKEN_REQUEST_URL
.
Para actualizar tus flujos de trabajo utilizando este enfoque, necesitarás hacer tres cambios a tu YAML:
- Agregar ajustes de permisos para el token.
- Agregar código que solicite el token de OIDC desde el proveedor de OIDC de GitHub.
- Agregar código que intercambie el token de OIDC por un token de acceso con tu proveedor de servicios en la nube.
Solicitar un JTW utilizando el kit de herramientas nuclear de las acciones
En el ejemplo siguiente se muestra cómo usar actions/github-script
con el kit de herramientas core
para solicitar el JWT desde el proveedor de OIDC de GitHub. Para obtener más información, vea «Creación de una acción de JavaScript».
jobs:
job:
environment: Production
runs-on: ubuntu-latest
steps:
- name: Install OIDC Client from Core Package
run: npm install @actions/core@1.6.0 @actions/http-client
- name: Get Id Token
uses: actions/github-script@v6
id: idtoken
with:
script: |
const coredemo = require('@actions/core')
let id_token = await coredemo.getIDToken()
coredemo.setOutput('id_token', id_token)
Solicitar el JWT utilizando variables de ambiente
En el siguiente ejemplo se muestra cómo utilizar variables de entorno para solicitar una instancia de JSON Web Token.
Para el trabajo de implementación, tendrá que definir la configuración del token mediante actions/github-script
con el kit de herramientas core
. Para obtener más información, vea «Creación de una acción de JavaScript».
Por ejemplo:
jobs:
job:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v6
id: script
timeout-minutes: 10
with:
debug: true
script: |
const token = process.env['ACTIONS_RUNTIME_TOKEN']
const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL']
core.setOutput('TOKEN', token.trim())
core.setOutput('IDTOKENURL', runtimeUrl.trim())
Después, puede usar curl
para recuperar un JWT del proveedor de OIDC de GitHub. Por ejemplo:
- run: |
IDTOKEN=$(curl -H "Authorization: bearer ${{steps.script.outputs.TOKEN}}" ${{steps.script.outputs.IDTOKENURL}} -H "Accept: application/json; api-version=2.0" -H "Content-Type: application/json" -d "{}" | jq -r '.value')
echo $IDTOKEN
jwtd() {
if [[ -x $(command -v jq) ]]; then
jq -R 'split(".") | .[0],.[1] | @base64d | fromjson' <<< "${1}"
echo "Signature: $(echo "${1}" | awk -F'.' '{print $3}')"
fi
}
jwtd $IDTOKEN
echo "idToken=${IDTOKEN}" >> $GITHUB_OUTPUT
id: tokenid
Obtener el token de acceso desde el proveedor de servicios en la nube
Necesitarás presentar el token web JSON de OIDC a tu proveedor de servicios en la nube para obtener un token de acceso.
Para cada despliegue, tus flujos de trabajo deben utilizar acciones de inicio de sesión en la nube (o scripts personalizados) que recuperen el token OIDC y lo presenten a tu proveedor de servicios en la nube. Posteriormente, el proveedor validará las reivindicaciones en el token; de tener éxito, proporcionará un token de acceso a la nube que estará disponible solo para esta ejecución de job. Las acciones subsecuentes en el job podrán, entonces, utilizar el token de acceso para conectarse a la nube y desplegar sus recursos.
Los pasos para intercambiar el token de OIDC por un token de acceso variarán para cada proveedor de servicios en la nube.
Acceder a los recursos en tu proveedor de servicios en la nube
Una vez que hayas obtenido el token de acceso, puedes utilizar acciones o scripts específicos en la nube para autenticarte con el proveedor de servicios en la nube y desplegar hacia sus recursos. Estos pasos podrían diferir entre cada proveedor.
Por ejemplo, Alibaba Cloud mantiene sus propias instrucciones para la autenticación de OIDC. Para obtener más información, consulta Introducción al inicio de sesión único basado en OIDC en la documentación de Alibaba Cloud.
Adicionalmente, el tiempo de vencimiento predeterminado para este token de acceso podría variar entre cada nube y podría ser configurable de lado del proveedor de servicios.