Nota: Actualmente los ejecutores hospedados en GitHub no se admiten en GitHub Enterprise Server. Puede ver más información sobre la compatibilidad futura planeada en GitHub public roadmap.
Información general
OpenID Connect (OIDC) permite que tus flujos de trabajo de GitHub Actions se autentiquen con HashiCorp Vault para recuperar secretos.
En esta guía se proporciona un resumen de cómo configurar HashiCorp Vault para que confíe en el OIDC de GitHub como identidad federada y se muestra cómo usar esta configuración en la acción hashicorp/vault-action para recuperar secretos desde HashiCorp Vault.
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».
Agregar el proveedor de identidad a HashiCorp Vault
Para utilizar OIDC con HashiCorp Vault, necesitarás agregar una configuración de confianza para el proveedor de OIDC de GitHub. Para más información, vea la documentación de HashiCorp Vault.
Para configurar el servidor de Vault a fin de que acepte tokens de JSON Web Token (JWT) para la autenticación, haz lo siguiente:
-
Habilita el método
auth
de JWT y usawrite
para aplicar la configuración al almacén. Para las parámetrosoidc_discovery_url
ybound_issuer
, usahttps://HOSTNAME/_services/token
. Estos parámetros permiten al servidor de Vault comprobar los tokens de JSON Web Token (JWT) recibidos durante el proceso de autenticación.Shell vault auth enable jwt
vault auth enable jwt
Shell vault write auth/jwt/config \ bound_issuer="https://HOSTNAME/_services/token" \ oidc_discovery_url="https://HOSTNAME/_services/token"
vault write auth/jwt/config \ bound_issuer="https://HOSTNAME/_services/token" \ oidc_discovery_url="https://HOSTNAME/_services/token"
-
Configura una directiva que solo conceda acceso a las rutas de acceso específicas que usarán los flujos de trabajo para recuperar secretos. Para obtener directivas más avanzadas, consulta la documentación sobre las directivas de HashiCorp Vault.
Shell vault policy write myproject-production - <<EOF # Read-only permission on 'secret/data/production/*' path path "secret/data/production/*" { capabilities = [ "read" ] } EOF
vault policy write myproject-production - <<EOF # Read-only permission on 'secret/data/production/*' path path "secret/data/production/*" { capabilities = [ "read" ] } EOF
-
Configura roles para agrupar diferentes directivas. Si la autenticación se realiza correctamente, estas directivas se adjuntan al token de acceso de Vault resultante.
Shell vault write auth/jwt/role/myproject-production -<<EOF { "role_type": "jwt", "user_claim": "actor", "bound_claims": { "repository": "user-or-org-name/repo-name" }, "policies": ["myproject-production"], "ttl": "10m" } EOF
vault write auth/jwt/role/myproject-production -<<EOF { "role_type": "jwt", "user_claim": "actor", "bound_claims": { "repository": "user-or-org-name/repo-name" }, "policies": ["myproject-production"], "ttl": "10m" } EOF
ttl
define la validez del token de acceso resultante.- Asegúrate de que el parámetro
bound_claims
está definido para los requisitos de seguridad y que tiene al menos una condición. Opcionalmente, también puedes establecer los parámetrosbound_subject
ybound_audiences
. - Para comprobar las notificaciones arbitrarias en la carga de JWT recibida, el parámetro
bound_claims
contiene un conjunto de notificaciones y sus valores necesarios. En el ejemplo anterior, el rol aceptará todas las solicitudes de autenticación entrantes del repositoriorepo-name
propiedad de la cuentauser-or-org-name
. - Para ver todas las notificaciones disponibles y admitidas por el proveedor de OIDC de GitHub, consulta:"Acerca del fortalecimiento de seguridad con OpenID Connect".
Para más información, vea la documentación de HashiCorp Vault.
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.
- Use la acción
hashicorp/vault-action
para intercambiar el token de OIDC (JWT) por un token de acceso a la nube.
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 obtener más información, vea «Administrar entornos para la implementación».
Para agregar la integración de OIDC con tus flujos de trabajo, la cual les permita acceder a los secretos en la bóveda, necesitarás agregar los siguientes cambios al código:
- Otorga permiso para recuperar el token del proveedor de OIDC de GitHub:
- El flujo de trabajo necesita la configuración
permissions:
con el valorid-token
establecido enwrite
. Esto te permite recuperar el token de OIDC desde cualquier job en el flujo de trabajo.
- El flujo de trabajo necesita la configuración
- Solicita el JWT desde el proveedor de OIDC de GitHub y preséntalo a HashiCorp Vault para recibir un token de acceso:
- Puedes usar la acción
hashicorp/vault-action
para capturar el JWT y recibir el token de acceso de Vault, o bien el kit de herramientas de Acciones para capturar los tokens del trabajo.
- Puedes usar la acción
Este ejemplo demuestra cómo utilizar OIDC con la acción oficial para solicitar un secreto de HashiCorp Vault.
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».
Nota:
Cuando se usa la clave permissions
, todos los permisos no especificados se establecen en Sin acceso, a excepción del ámbito de metadatos, que siempre obtiene acceso de lectura. Como resultado, puede que tengas que agregar otros permisos, como contents: read
. Para obtener más información, consulta "Autenticación de token automática".
Solicitar el token de acceso
La acción hashicorp/vault-action
recibe un JWT del proveedor de OIDC de GitHub y, después, solicita un token de acceso a la instancia de HashiCorp Vault para recuperar los secretos. Para obtener más información, consulta la documentación de Acción de GitHub de HashiCorp Vault.
Este ejemplo demuestra cómo crear un job que solicite un secreto de HashiCorp Vault.
VAULT-URL
: reemplace esto por la dirección URL de HashiCorp Vault.VAULT-NAMESPACE
: reemplaza esto por el espacio de nombres que has establecido en HashiCorp Vault. Por ejemplo:admin
.ROLE-NAME
: reemplace esto por el rol que ha establecido en la relación de confianza de HashiCorp Vault.SECRET-PATH
: reemplace esto por la ruta al secreto que se va a recuperar de HashiCorp Vault. Por ejemplo:secret/data/production/ci npmToken
.
jobs: retrieve-secret: runs-on: ubuntu-latest permissions: id-token: write contents: read steps: - name: Retrieve secret from Vault uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b with: method: jwt url: VAULT-URL namespace: VAULT-NAMESPACE # HCP Vault and Vault Enterprise only role: ROLE-NAME secrets: SECRET-PATH - name: Use secret from Vault run: | # This step has access to the secret retrieved above; see hashicorp/vault-action for more details.
jobs:
retrieve-secret:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- name: Retrieve secret from Vault
uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
with:
method: jwt
url: VAULT-URL
namespace: VAULT-NAMESPACE # HCP Vault and Vault Enterprise only
role: ROLE-NAME
secrets: SECRET-PATH
- name: Use secret from Vault
run: |
# This step has access to the secret retrieved above; see hashicorp/vault-action for more details.
Nota:
- Si el servidor de Vault no es accesible desde la red pública, considera la posibilidad de usar un ejecutor autohospedado con otros métodos de autenticación de Vault disponibles. Para obtener más información, vea «Acerca de los ejecutores autohospedados».
VAULT-NAMESPACE
debe establecerse para una implementación de Vault Enterprise (incluido HCP Vault). Para obtener más información, consulta Espacio de nombres de Vault.
Revocación del token de acceso
De manera predeterminada, el servidor de Vault revocará automáticamente los tokens de acceso cuando expire su TTL, por lo que no tendrás que revocar manualmente los tokens de acceso. Pero si quieres revocar los tokens de acceso inmediatamente después de que el trabajo se haya completado o haya producido un error, puedes revocar manualmente el token emitido mediante la API de Vault.
- Establece la opción
exportToken
entrue
(valor predeterminado:false
). Esto exporta el token de acceso de Vault emitido como una variable de entorno:VAULT_TOKEN
. - Agrega un paso para llamar a la API de Vault Revocación de un token (Automática) para revocar el token de acceso.
jobs: retrieve-secret: runs-on: ubuntu-latest permissions: id-token: write contents: read steps: - name: Retrieve secret from Vault uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b with: exportToken: true method: jwt url: VAULT-URL role: ROLE-NAME secrets: SECRET-PATH - name: Use secret from Vault run: | # This step has access to the secret retrieved above; see hashicorp/vault-action for more details. - name: Revoke token # This step always runs at the end regardless of the previous steps result if: always() run: | curl -X POST -sv -H "X-Vault-Token: ${{ env.VAULT_TOKEN }}" \ VAULT-URL/v1/auth/token/revoke-self
jobs:
retrieve-secret:
runs-on: ubuntu-latest
permissions:
id-token: write
contents: read
steps:
- name: Retrieve secret from Vault
uses: hashicorp/vault-action@9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b
with:
exportToken: true
method: jwt
url: VAULT-URL
role: ROLE-NAME
secrets: SECRET-PATH
- name: Use secret from Vault
run: |
# This step has access to the secret retrieved above; see hashicorp/vault-action for more details.
- name: Revoke token
# This step always runs at the end regardless of the previous steps result
if: always()
run: |
curl -X POST -sv -H "X-Vault-Token: ${{ env.VAULT_TOKEN }}" \
VAULT-URL/v1/auth/token/revoke-self