Configuring OpenID Connect in HashiCorp Vault

Overview

OpenID Connect (OIDC) allows your GitHub Actions workflows to authenticate with a HashiCorp Vault to retrieve secrets.

This guide gives an overview of how to configure HashiCorp Vault to trust GitHub's OIDC as a federated identity, and demonstrates how to use this configuration in the hashicorp/vault-action action to retrieve secrets from HashiCorp Vault.

Prerequisites

• Основные понятия о том, как GitHub использует OpenID Connect (OIDC) и его архитектуру и преимущества, см. в разделе Сведения об усилении защиты с помощью OpenID Connect.

• Прежде чем продолжить, необходимо спланировать стратегию безопасности, чтобы обеспечить выдачу маркеров доступа только предсказуемым способом. Чтобы управлять тем, как поставщик облачных служб выдает маркеры доступа, необходимо определить по крайней мере одно условие, запретив недоверенным репозиториям запрашивать маркеры доступа к облачным ресурсам. Дополнительные сведения см. в разделе Сведения об усилении защиты с помощью OpenID Connect.

Adding the identity provider to HashiCorp Vault

To use OIDC with HashiCorp Vault, you will need to add a trust configuration for the GitHub OIDC provider. For more information, see the HashiCorp Vault documentation.

To configure your Vault server to accept JSON Web Tokens (JWT) for authentication:

1. Enable the JWT auth method, and use write to apply the configuration to your Vault. For oidc_discovery_url and bound_issuer parameters, use http://HOSTNAME/_services/token. These parameters allow the Vault server to verify the received JSON Web Tokens (JWT) during the authentication process.

   Shell

   vault auth enable jwt
   

   Shell

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

2. Configure a policy that only grants access to the specific paths your workflows will use to retrieve secrets. For more advanced policies, see the HashiCorp Vault Policies documentation.

   Shell

   vault policy write myproject-production - <<EOF
   # Read-only permission on 'secret/data/production/*' path
   
   path "secret/data/production/*" {
     capabilities = [ "read" ]
   }
   EOF
   

3. Configure roles to group different policies together. If the authentication is successful, these policies are attached to the resulting Vault access token.

   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 defines the validity of the resulting access token.
• Ensure that the bound_claims parameter is defined for your security requirements, and has at least one condition. Optionally, you can also set the bound_subject as well as the bound_audiences parameter.
• To check arbitrary claims in the received JWT payload, the bound_claims parameter contains a set of claims and their required values. In the above example, the role will accept any incoming authentication requests from the repo-name repository owned by the user-or-org-name account.
• To see all the available claims supported by GitHub's OIDC provider, see Сведения об усилении защиты с помощью OpenID Connect.

For more information, see the HashiCorp Vault documentation.

Updating your GitHub Actions workflow

To update your workflows for OIDC, you will need to make two changes to your YAML:

1. Add permissions settings for the token.
2. Use the hashicorp/vault-action action to exchange the OIDC token (JWT) for a cloud access token.

To add OIDC integration to your workflows that allow them to access secrets in Vault, you will need to add the following code changes:

• Grant permission to fetch the token from the GitHub OIDC provider:
  • The workflow needs permissions: settings with the id-token value set to write. This lets you fetch the OIDC token from every job in the workflow.
• Request the JWT from the GitHub OIDC provider, and present it to HashiCorp Vault to receive an access token:
  • You can use the hashicorp/vault-action action to fetch the JWT and receive the access token from Vault, or you could use the Actions toolkit to fetch the tokens for your job.

This example demonstrates how to use OIDC with the official action to request a secret from HashiCorp Vault.

Adding permissions settings

Для выполнения задания или рабочего процесса требуется permissions параметр, позволяющий id-token: write GitHubпоставщика OIDC для создания веб-маркера JSON для каждого запуска. Вы не сможете запросить маркер идентификатора JWT OIDC, если permissions оно id-token не задано write, однако это значение не подразумевает предоставление доступа на запись к любым ресурсам, только возможность получить и задать маркер OIDC для действия или шага, чтобы включить проверку подлинности с помощью маркера доступа с коротким сроком действия. Любой фактический параметр доверия определяется с помощью утверждений OIDC, дополнительные сведения см. в разделе Сведения об усилении защиты с помощью OpenID Connect.

Этот параметр id-token: write позволяет запрашивать JWT у поставщика OIDC GitHub, применяя один из следующих способов:

• использование переменных среды в средстве выполнения (ACTIONS_ID_TOKEN_REQUEST_URL и ACTIONS_ID_TOKEN_REQUEST_TOKEN);
• использование getIDToken() из набора средств Actions.

Если необходимо получить токен OIDC для рабочего процесса, разрешение можно установить на уровне рабочего процесса. Например:

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

Если необходимо получить токен OIDC только для одного задания, такое разрешение можно установить в этом задании. Например:

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

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

В зависимости от требований рабочего процесса, возможно, будет необходимо указать здесь дополнительные разрешения.

Для повторно используемых рабочих процессов, принадлежащих одному и тому же пользователю, организации или предприятиям, что и рабочий процесс вызывающего объекта, маркер OIDC, созданный в повторно используемый рабочий процесс, можно получить из контекста вызывающего объекта. Для повторно используемых рабочих процессов за пределами организации или предприятия параметр id-token должен быть явно задан write на уровне рабочего процесса вызывающего объекта или permissions в конкретном задании, которое вызывает повторно используемый рабочий процесс. Это гарантирует, что маркер OIDC, созданный в повторно используемом рабочем процессе, может использоваться только в рабочих процессах вызывающего объекта.

Дополнительные сведения см. в разделе Reusing workflows.

Requesting the access token

The hashicorp/vault-action action receives a JWT from the GitHub OIDC provider, and then requests an access token from your HashiCorp Vault instance to retrieve secrets. For more information, see the HashiCorp Vault GitHub Action documentation.

This example demonstrates how to create a job that requests a secret from HashiCorp Vault.

• VAULT-URL: Replace this with the URL of your HashiCorp Vault.
• VAULT-NAMESPACE: Replace this with the Namespace you've set in HashiCorp Vault. For example: admin.
• ROLE-NAME: Replace this with the role you've set in the HashiCorp Vault trust relationship.
• SECRET-PATH: Replace this with the path to the secret you're retrieving from HashiCorp Vault. For example: 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.

Revoking the access token

By default, the Vault server will automatically revoke access tokens when their TTL is expired, so you don't have to manually revoke the access tokens. However, if you do want to revoke access tokens immediately after your job has completed or failed, you can manually revoke the issued token using the Vault API.

1. Set the exportToken option to true (default: false). This exports the issued Vault access token as an environment variable: VAULT_TOKEN.
2. Add a step to call the Revoke a Token (Self) Vault API to revoke the access token.

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

Further reading

• Using OpenID Connect with reusable workflows
• Взаимодействие с локальными средствами выполнения