Configurar OpenID Connect en 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 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:

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

   Shell

   vault write auth/jwt/config \
     bound_issuer="https://HOSTNAME/_services/token" \
     oidc_discovery_url="https://HOSTNAME/_services/token"
   

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

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:
  • 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.

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:

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

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

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.

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.

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

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

Información adicional

• Utilizar OpenID Connect con flujos de trabajo reutilizables - Acerca de los ejecutores autohospedados