Skip to main content

Configuring OpenID Connect in HashiCorp Vault

Use OpenID Connect within your workflows to authenticate with HashiCorp Vault.

概要

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.

必要な環境

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

Configure the vault to accept JSON Web Tokens (JWT) for authentication:

GitHub Actions ワークフローを更新する

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:

  • GitHub OIDCプロバイダーからトークンをフェッチする権限の付与:
    • The workflow needs permissions: settings with the id-token value set to write. これによって、ワークフロー中のすべてのジョブからODICトークンをフェッチできるようになります。
  • 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と設定すると、JWTはGitHubのOIDCプロバイダから以下のいずれかのアプローチを使ってリクエストできます。

  • ランナー上の環境変数を使う(ACTIONS_ID_TOKEN_REQUEST_URL及びACTIONS_ID_TOKEN_REQUEST_TOKEN)。
  • ActionsツールキットからgetIDToken()を使う。

1つのジョブのためにOIDCトークンをフェッチしなければならないだけなら、この権限はそのジョブ内で設定できます。 例:

YAML
permissions:
  id-token: write

ワークフローの必要に応じて、ここで追加の権限を指定する必要があるかもしれません。

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 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.
  • <Role name>: Replace this with the role you've set in the HashiCorp Vault trust relationship.
  • <Audience>: Replace this with the audience you've defined 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/ci npmToken.
YAML
jobs:
    retrieve-secret:
        steps:
            - name: Retrieve secret from Vault
              uses: hashicorp/vault-action@v2.4.0
              with:
                url: <Vault URL>
                role: <Role name>
                method: jwt
                jwtGithubAudience: <Audience>
                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.