Skip to main content
Publicamos actualizaciones para la documentación con frecuencia y es posible que aún se esté traduciendo esta página. Para obtener la información más reciente, consulta la documentación en inglés.

Configurar OpenID Connect en HashiCorp Vault

En este artículo

Utiliza OpenID Connect dentro de tus flujos de trabajo para autenticarte con HashiCorp Vault.

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 obtener información sobre los conceptos básicos de cómo GitHub usa OpenID Connect (OIDC), su arquitectura y sus ventajas, consulte "Acerca del fortalecimiento de la 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 más información, vea "Configuración de la confianza de OIDC con la nube".

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:

  1. Habilita el método auth de JWT y usa write para aplicar la configuración al almacén. Para las parámetros oidc_discovery_url y bound_issuer, usa https://token.actions.githubusercontent.com. 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
    Shell
    vault write auth/jwt/config \
  bound_issuer="https://token.actions.githubusercontent.com" \
  oidc_discovery_url="https://token.actions.githubusercontent.com"

  2. 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

  3. 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
  • 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ámetros bound_subject y bound_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 repositorio repo-name propiedad de la cuenta user-or-org-name.
  • Para ver todas las notificaciones disponibles compatibles con el proveedor de OIDC de GitHub, consulta "Configuración de la confianza de OIDC con la nube".

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:

  1. Agregar ajustes de permisos para el token.
  2. Use la acción hashicorp/vault-action para intercambiar el token de OIDC (JWT) por un token de acceso a la nube.

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 valor id-token establecido en write. Esto te permite recuperar el token de OIDC desde cualquier job en el flujo de trabajo.
  • Solicita el JWT desde el proveedor de OIDC de GitHub y preséntalo a HashiCorp Vault para recibir un token de acceso:

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 del trabajo o del flujo de trabajo necesita una configuración permissions con id-token: write. No podrá solicitar el token de identificador JWT de OIDC si el valor permissions de id-token está establecido en read o none.

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 y ACTIONS_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:

YAML
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:

YAML
permissions:
  id-token: write # This is required for requesting the JWT

Puede que necesites especificar permisos adicionales aquí, dependiendo de los requisitos de tu flujo 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.
YAML
jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@v2.4.0
          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:

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.

  1. Establece la opción exportToken en true (valor predeterminado: false). Esto exporta el token de acceso de Vault emitido como una variable de entorno: VAULT_TOKEN.
  2. Agrega un paso para llamar a la API de Vault Revocación de un token (Automática) para revocar el token de acceso.
YAML
jobs:
  retrieve-secret:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - name: Retrieve secret from Vault
        uses: hashicorp/vault-action@v2.4.0
          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