Skip to main content

Configuring OpenID Connect in HashiCorp Vault

Use OpenID Connect within your workflows to authenticate with 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 を使用したセキュリティ強化について」を参照してください。

  • 先に進む前に、アクセス トークンが予測可能な方法でのみ割り当てられるようにセキュリティ戦略を計画する必要があります。 クラウド プロバイダーがアクセス トークンを発行する方法を制御するには、少なくとも 1 つの条件を定義し、信頼できないリポジトリがクラウド リソースにアクセス トークンを要求できないようにする 必要があります。 詳細については、「クラウドを使った OIDC 信頼の構成」を参照してください。

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 https://token.actions.githubusercontent.com. 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="https://token.actions.githubusercontent.com" \
      oidc_discovery_url="https://token.actions.githubusercontent.com"
  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 "Configuring the OIDC trust with the cloud".

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:

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

Adding permissions settings

ジョブまたはワークフローの実行には、id-token: writepermissions 設定が必要です。 id-tokenpermissions 設定が read または none の場合、OIDC JWT ID トークンを要求することはできません。

この id-token: write 設定により、次のいずれかの方法を使用して、GitHub の OIDC プロバイダーから JWT を要求できます。

  • ランナーで環境変数を使用する (ACTIONS_ID_TOKEN_REQUEST_URL および ACTIONS_ID_TOKEN_REQUEST_TOKEN)。
  • アクション ツールキットから getIDToken() を使用する。

ワークフローの OIDC トークンをフェッチする必要がある場合は、ワークフロー レベルでアクセス許可を設定できます。 次に例を示します。

YAML
permissions:
  id-token: write # This is required for requesting the JWT
  contents: read  # This is required for actions/checkout

1 つのジョブに対して OIDC トークンのみをフェッチする必要がある場合は、そのジョブ内でこのアクセス許可を設定できます。 次に例を示します。

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

ワークフローの要件に応じて、ここで追加のアクセス許可を指定する必要がある場合があります。

Note:

When the permissions key is used, all unspecified permissions are set to no access, with the exception of the metadata scope, which always gets read access. As a result, you may need to add other permissions, such as contents: read. See Automatic token authentication for more information.

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

Note:

  • If your Vault server is not accessible from the public network, consider using a self-hosted runner with other available Vault auth methods. For more information, see "About self-hosted runners."
  • <Vault Namespace> must be set for a Vault Enterprise (including HCP Vault) deployment. For more information, see Vault namespace.

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