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

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 y admitidas por el proveedor de OIDC de GitHub, consulta 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 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, consulte 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 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 trabajo único, 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 necesites especificar permisos adicionales aquí, dependiendo de los requisitos de tu 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 más información, consulta Reutilización de flujos de trabajo.

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.

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

Información adicional

• Utilizar OpenID Connect con flujos de trabajo reutilizables
• Referencia de ejecutores autohospedados