Nota:
Actualmente los ejecutores hospedados por GitHub Enterprise Server no se admiten en GitHub.
Información general
OpenID Connect (OIDC) permite que sus GitHub Actions flujos de trabajo accedan a recursos de su proveedor de nube sin tener que almacenar credenciales en forma de secretos de larga duración GitHub.
Para usar OIDC, primero deberá configurar el proveedor de nube para que confíe GitHuben OIDC como identidad federada y, a continuación, debe actualizar los flujos de trabajo para autenticarse mediante tokens.
Prerrequisitos
-
Para obtener información sobre los conceptos básicos sobre cómo GitHub usa OpenID Connect (OIDC) y su arquitectura y ventajas, consulte 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 más información, consulta OpenID Connect.
Actualizando tu GitHub Actions flujo de trabajo
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.
Nota:
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 más información, consulta Administrar entornos para la implementación.
Agregar ajustes de permisos
La ejecución del trabajo o del flujo de trabajo requiere una permissions configuración con id-token: write para permitir que GitHubel proveedor OIDC cree un token web JSON para cada ejecución.
Nota:
La configuración de id-token: write en los permisos del flujo de trabajo no otorga al flujo de trabajo permiso para modificar o escribir sobre ningún recurso. En su lugar, solo permite al flujo de trabajo solicitar (capturar) y usar (establecer) un token OIDC para una acción o paso. A continuación, este token se usa para autenticarse con servicios externos mediante un token de acceso de corta duración.
Para obtener información detallada sobre los permisos necesarios, ejemplos de configuración y escenarios avanzados, consulta Referencia de OpenID Connect.
Utilizar acciones oficiales
Si el proveedor de nube ha creado una acción oficial para usar OIDC con GitHub Actions, le permitirá intercambiar fácilmente el token de OIDC para 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 con GitHub.
Utilizar acciones personalizadas
Si su proveedor de nube no tiene una acción oficial, o si prefiere crear scripts personalizados, puede solicitar manualmente el JSON Web Token (JWT) a GitHubsu proveedor de OIDC.
Si no usa una acción oficial, GitHub recomienda usar el kit de herramientas principal de Actions. 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.
- Agregue código que solicite el token OIDC del 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 el JWT utilizando el kit de herramientas central de Actions
En el ejemplo siguiente se muestra cómo utilizar actions/github-script con el conjunto de herramientas core para solicitar el JWT al proveedor de OIDC de GitHub. Para más información, consulta 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@v8
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 más información, consulta Creación de una acción de JavaScript.
Por ejemplo:
jobs:
job:
runs-on: ubuntu-latest
steps:
- uses: actions/github-script@v8
id: script
timeout-minutes: 10
with:
debug: true
script: |
const token = process.env['ACTIONS_ID_TOKEN_REQUEST_TOKEN']
const runtimeUrl = process.env['ACTIONS_ID_TOKEN_REQUEST_URL']
core.setOutput('TOKEN', token.trim())
core.setOutput('IDTOKENURL', runtimeUrl.trim())
A continuación, puede usar curl para recuperar un JWT del GitHub proveedor OIDC. 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 valida las afirmaciones en el token; si lo valida exitosamente, proporciona un token de acceso a la nube que estará disponible solo para esa ejecución de trabajo. 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 Resumen del SSO 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.