こんにちは。テクマトリックスの橘です。

JenkinsなどのCI/CDツールを、開発支援ツールと連携させる際に、連携させるツールによってはそのツールへのアクセスをするためのID/パスワード、アクセストークンなどの認証情報が必要となるケースがあると思います。Jenkinsではそれらの認証情報をCredentialsとして管理しており、リポジトリへのアクセスや、ツールの実行時にその情報を利用しています。

Jenkins標準の認証情報管理機能を利用するという選択肢は、一見妥当な手段と考えられますが、セキュリティや拡張性の観点から、さらなる強化が求められるケースも増えてきています。

ここで登場するのが、HashiCorp Vaultです。本記事では、このHashiCorp Vaultの概要とJenkinsと連携した場合にどのようなメリットがあるか、そして、具体的な設定方法についてご紹介します。Jenkinsの認証情報の管理にお困りの方は本記事の内容を参考にしていただければと思います。

HashiCorp Vaultとは？

HashiCorp Vault（以下、Vault）は、最近IBMに買収されたことでも話題になった、HashiCorp社が開発したセキュリティツールで、機密情報（シークレット）を安全に管理し、アクセス制御を行うためのツールです。具体的には、パスワード、APIキー、トークン、証明書などの機密情報を暗号化して保管し、必要なときに安全に取り出すことができます。また、動的な資格情報の生成やアクセスログの記録など、セキュリティをさらに強化するためのさまざまな機能も備えています。

Vaultの最大の特徴は、セキュリティと柔軟性を両立していることです。機密情報の管理を一元化することで、開発者が複雑なセキュリティ要件を満たしながら作業を行いやすくなる環境を提供します。

無償版と有償版の違い

Vaultには、コミュニティ版とエンタープライズ版という、大きく分けると2つのエディションがあります。それぞれの特徴と違いを以下にまとめます。

• コミュニティ版（無償版）
  無償版は、Vaultの基本的な機能を利用できるエディションです。たとえば、シークレットの保存、静的および動的な資格情報の管理、暗号化、監査ログの記録といった機能が含まれています。個人や小規模なチーム、あるいはVaultの検証を目的とした利用に適しています。
• エンタープライズ版（有償版）
  エンタープライズ版は、大規模な組織や企業向けに設計されたエディションで、無償版のすべての機能に加えて、より高度なセキュリティ機能やスケーラビリティを実現するための追加機能が含まれています。たとえば、次のような特徴があります：
  • 分散クラスタリング：Vaultを複数ノードで運用し、可用性を高める。
  • Namespace：マルチテナント環境の管理を容易にする。
  • アクセス制御の強化：詳細なポリシー設定やSSO（シングルサインオン）との統合。
  • サポート：HashiCorp社による公式サポートを受けられる。

エンタープライズ版は、セキュリティ要件が厳しい業界や、Vaultを大規模なインフラストラクチャに統合したい企業にとって魅力的な選択肢となります。また、HashiCorp社がホストするVaultを利用するという、SaaS形態の提供もあります。

なぜVaultとJenkinsを連携させるのか？

JenkinsはCI/CDツールとして非常に強力な機能を持っていますが、認証情報の管理については基本的な機能しか提供していません。Jenkins内で認証情報を登録して使用することは可能ですが、その管理にはいくつかの課題があります。また、CI/CDという面から考えると気づかないうちにボトルネックになっていることも考えられます。

CI/CDにおける認証情報管理の課題

1. 複数コントローラ利用時の課題
   Jenkins環境が単一のコントローラーで運用されている場合は比較的管理が容易ですが、コントローラーが複数存在するような環境になると、認証情報の一貫性を保つことが難しくなります。それぞれのJenkinsインスタンスに同じ認証情報を手動で設定する必要があり、設定の漏れやミスが発生するリスクが高くなります。
2. ツール間の認証情報管理の煩雑さ
   CI/CDのパイプラインでは、Jenkins以外にもさまざまなツールが使用されることが一般的です。たとえば、デプロイメントに使用するクラウドサービスや、コード管理に使用するGitリポジトリなどです。これらすべてのツールで同じ認証情報を使う場合、管理が複雑化し、セキュリティリスクが増大します。
3. セキュリティの課題
   Jenkins内に認証情報を保存する場合、万が一Jenkinsサーバーが侵害された場合には、保存されている認証情報がすべて流出する危険性があります。また、認証情報の可視化やアクセス制御の柔軟性も限定的です。

Vaultの利用による解決策

Vaultを利用することで、上記の課題を効果的に解決することができます。具体的なメリットは以下のとおりです。

1. 複数コントローラー間での認証情報の一元管理
   Vaultを使用することで、Jenkinsコントローラー間で認証情報を一元的に管理できます。Vaultに保存された認証情報は、必要に応じて各Jenkinsインスタンスから動的に取得されるため、手動で設定を同期する必要がなくなります。
2. CI/CDパイプラインを横断した認証情報の一元管理
   Vaultは、複数のツール間で使用する認証情報を一元的に管理できるだけでなく、動的なシークレットの生成機能を提供します。たとえば、必要なときにだけ短期間有効な認証情報を発行し、使用後に無効化することが可能です。これにより、ツール間の認証情報の管理が簡素化され、パスワードの使い回しや長期間の露出によるセキュリティリスクを大幅に削減できます。
3. Vaultによるセキュリティの向上とアクセス制御の強化
   Vaultは、認証情報を暗号化して保存するため、万が一Jenkinsサーバーが侵害されたとしても、Vault内の認証情報が直接流出するリスクを最小限に抑えられます。また、Vaultでは詳細なアクセス制御ポリシーを設定可能であり、誰がどの認証情報にアクセスできるかを厳密に管理できます。さらに、すべての操作が監査ログに記録されるため、不正アクセスや事故が発生した場合でも追跡可能です。

VaultをJenkinsと連携させることで、認証情報管理の効率化とセキュリティ強化を同時に実現できます。次のセクションでは、VaultとJenkinsを連携させるイメージやユースケースについて説明していきます。

構築する環境の説明

今回の検証環境では、以下のツールを利用します。いずれもOSS版、コミュニティ版を利用します。

Jenkins、Gitea、SonarQubeは同一マシン(Windows)上に構築されており、そのマシン上にdocker-composeを利用して、Vaultを構築します。連携イメージは以下のようになります。

本記事の中で、実現したい連携の内容は以下の二件です。

• VaultにGiteaのIDを登録し、それを利用して、JenkinsにGiteaのリポジトリを認識させる
• VaultにSonarQubeのアクセストークンを登録し、それを利用して、パイプラインからSonarQubeを実行する

それでは、実際に構築手順を見ていきましょう。

構築手順

1. Vaultをコンテナで構築

前述のとおり、docker-composeを利用して、Windowsマシン上のコンテナとしてVaultを起動します。
docker-compose.ymlの例は以下です。

services:
  vault:
    image: hashicorp/vault:latest
    container_name: vault
    ports:
      - "8200:8200"
    environment:
      VAULT_DEV_ROOT_TOKEN_ID: "root"
      VAULT_DEV_LISTEN_ADDRESS: "0.0.0.0:8200"
    cap_add:
      - IPC_LOCK
    command: ["server", "-dev"]
    volumes:
      - ./vault-data:/data

command: ["server", "-dev"]というオプションを設定していますが、今回はVaultを開発モードで起動しているためです。

それでは、Vaultを起動してみましょう。
docker-composeファイルがあるディレクトリに移動し、以下のコマンドでコンテナを起動します。

docker-compose up -d

そして、シークレット登録を行うために、コンテナのコンソールにアクセスします。

docker exec -it vault sh

それでは、Vaultにアクセスして、作業を始めましょう。

2. シークレット登録のための下準備

以下の様な手順で進めていきます。

1. Vault のサーバーアドレスを環境変数に設定
2. Vaultへログインし、AppRoleを有効化
3. Jenkinsとの接続のためのAppRoleを作成
4. シークレット生成エンジンを有効化

まず、Vault CLIが接続するサーバーのアドレスを指定します。

# export VAULT_ADDR='http://localhost:8200/'

Vault CLIの接続に問題がない場合、以下のコマンドでVaultのステータスを確認することができます。
_{※今回構築する環境は再利用の予定がないので、シークレットキーなどは隠さずにそのままお見せします。}

# vault status
Key             Value
---             -----
Seal Type       shamir
Initialized     true
Sealed          false
Total Shares    1
Threshold       1
Version         1.19.0
Build Date      2025-03-04T12:36:40Z
Storage Type    inmem
Cluster Name    vault-cluster-d6f235e0
Cluster ID      d3cf9e5b-d1a5-d819-148a-03c0adcb88f9
HA Enabled      false

問題なく起動していることが分かったので、Vaultにログインします。
ここではdocker-compose.ymlで設定した、
VAULT_DEV_ROOT_TOKEN_ID: "root" を使ってログインしています。

# vault login
Token (will be hidden):
Success! You are now authenticated. The token information displayed below
is already stored in the token helper. You do NOT need to run "vault login"
again. Future Vault requests will automatically use this token.

次に、JenkinsからVaultへのアクセス設定をするのですが、アプリケーションやサービスがVaultに安全にアクセスするための認証方式としてAppRoleを利用することが推奨されています。
まず、このAppRole認証方式を有効にするために以下のコマンドを実施します。

# vault auth enable approle
Success! Enabled approle auth method at: approle/

次に、新しいAppRoleを作成し、その設定を行います。ここではjenkins-roleという名前のAppRoleを作成しています。オプションで、トークンとSecret IDの使用回数を無制限に設定しています。

# vault write auth/approle/role/jenkins-role token_num_uses=0 secret_id_num_uses=0 policies="jenkins"
Success! Data written to: auth/approle/role/jenkins-role

先ほど作成したjenkins-roleのRole IDを取得します。このRole IDは後程利用します。

# vault read auth/approle/role/jenkins-role/role-id
Key        Value
---        -----
role_id    e3a9c311-4ce2-6c76-e160-a3dbcffa9c2d

先ほど作成したjenkins-roleのSecret IDを生成します。このSecret IDも後程利用します。

# vault write -f auth/approle/role/jenkins-role/secret-id
Key                   Value
---                   -----
secret_id             759fce2a-228c-fa1d-5883-c06a02353f9a
secret_id_accessor    e5640324-78ab-7cbb-24d7-254d1585e15f
secret_id_num_uses    0
secret_id_ttl         0s

secretsという名前でKey-Value（KV）型の秘密情報の管理エンジンを有効化します。

# vault secrets enable -path=secrets kv
Success! Enabled the kv secrets engine at: secrets/

ここまでで、Vaultに認証情報を登録するための下準備が完了しました。シークレットの登録を行う前にJenkins側の設定について見ていきましょう。

3. Vault プラグインのインストールと設定

以下の様な手順で進めていきます。

1. JenkinsにVaultプラグインをインストール
2. JenkinsとVaultの接続設定

それでは、JenkinsにVaultプラグインをインストールしましょう。

Jenkinsの画面上から、
Manage Jenkins > Plugins > Available plugins でhashicorp vault と検索し、
表示された項目にチェックを入れ、Install をクリックします。

インストールが完了したら、Manage Jenkins > System を開き、Vault の設定を行います。
以下のようにVaultのURLを指定します。

次に、Vault Credentials の下にある Add ボタンから、先ほど作成したAppRoleを登録します。
設定項目は以下の通りです。

Jenkinsに認証情報を登録出来たら、Vault Credentials の項目に登録した認証情報が表示されますので、これを選択します。

これで、Vaultに登録してあるシークレットにJenkinsがアクセスできるようになりました。
それでは、早速Vaultにシークレットを登録してみましょう。

4. Vaultへのシークレットの登録

以下の様な手順で進めていきます。

1. Giteaの認証情報をVaultに登録
2. 登録した認証情報にアクセスするためのポリシーの作成

以下のコマンドで、Giteaの認証情報（ユーザー名とパスワード）を登録することができます。
^{※後ほど、GUIでの登録についても解説します。}

# vault kv put secrets/creds/gitea-id username=[ユーザー名] password=[パスワード]
Success! Data written to: secrets/creds/gitea-id

Jenkins用のアクセス権限を定義するポリシーファイルを作成します。
ここでは、secrets/creds配下のシークレット へのreadとlist権限を設定しています。

# vi jenkins-policy.hcl

path "secrets/creds/*" {
    capabilities = ["read", "list"]
}

上記で作成したポリシーファイルをVaultに登録し、jenkinsという名前のポリシーを作成します。

# vault policy write jenkins jenkins-policy.hcl
Success! Uploaded policy: jenkins

これでシークレットの登録が完了したので、Jenkins側の作業に移ります。

5. リポジトリアクセスのための認証情報の設定

以下の様な手順で進めていきます。

1. Vault上のGiteaの認証情報をJenkinsに登録
2. Giteaリポジトリアクセスのための設定

先程Vaultに登録したGiteaの認証情報である、gitea-idをJenkinsに登録します。

Manage Jenkins > Credentials > global > Add Credentials と進み、以下の項目を設定します。

KindがVault Username-Password Credentialの場合、Username KeyとPassword Keyはそれぞれ、username、passwordがデフォルト値として設定されていますので、空欄のままでも大丈夫です。

次に、Giteaのリポジトリにアクセスするための設定を行います。
Manage Jenkins > System > Gitea Servers　にて、Credentials に先ほど作成した、gitea-id　を選択。

正常に接続されると、Addボタンの下に、Hook management will be performed as “ユーザー名”と表示されます。

6. SonarQubeのアクセストークン作成とVaultへの登録

以下の様な手順で進めていきます。

1. SonarQubeのアクセストークンを生成
2. SonarQubeのアクセストークンをVaultに登録
3. Vault上のSonarQubeのアクセストークンをJenkinsに登録

次は、SonarQube側の設定です。
※_{^{SonarQubeの初期設定等は本記事の趣旨から外れるので割愛させていただきます。}}

ブラウザからSonarQubeにアクセスし、
My Account > Security > Generate Tokens でトークンを作成します。
今回は、トークン名をjenkins-integrationとします。Generateをクリックすると画面上にトークンが表示れます。

生成されたアクセストークンを、Giteaの認証情報と同様にVaultに登録していきます。
先程は、CLIから認証情報を登録しましたが、今度はVaultにブラウザからアクセスし、アクセストークンを登録してみましょう。

http://localhost:8200/　にアクセスし、Tokenにrootを入力し、Sign inをクリックします。

secrets > creds > Create secret　と進み、以下のように設定し、saveボタンで保存します。

次は、Jenkins側の作業です。
Manage Jenkins > Credentials > global > Add Credentials から以下を登録します。

7. シークレットを使用したJenkinsパイプラインの作成

それでは、Vaultに登録したSonarQubeのアクセストークンを利用し、パイプラインからSonarQubeを実行してみましょう。

Vaultに登録されたシークレットは、Jenkinの認証情報と同じように取り扱うことができるため、
environmentディレクティブ内のcredentials関数から取得することが可能です。

以下にパイプラインの例を示します。

pipeline {
    agent any

    environment {
        SONAR_TOKEN = credentials('sonarqube-token')
    }

    stages {
        stage('Run SonarQube Analysis') {
            steps {
                bat """
                sonar-scanner.bat ^
                -Dsonar.projectKey=my-project ^
                -Dsonar.sources=. ^
                -Dsonar.host.url=http://localhost:9000 ^
                -Dsonar.login=%SONAR_TOKEN%
                """
            }
        }
    }
}

上記のパイプラインを実行した結果がこちらです。ジョブが成功していることが確認できます。

蛇足ではありますが、SonarQubeでは以下のように表示されます。

以上で、JenkinsとVaultの連携環境の構築手順は終わりです。

まとめ

本記事では、JenkinsとHashiCorp Vaultを連携させる方法について解説しました。最後に、VaultをCI/CDに組み込むことで得られる主なメリットを振り返ります。

1. 複数コントローラー間での認証情報の一元管理
   Vaultを使用することで、Jenkinsコントローラー間で認証情報を一元的に管理できます。Vaultに保存された認証情報は、必要に応じて各Jenkinsインスタンスから動的に取得されるため、手動で設定を同期する必要がなくなります。
2. CI/CDパイプラインを横断した認証情報の一元管理
   Vaultは、複数のツール間で使用する認証情報を一元的に管理できるだけでなく、動的なシークレットの生成機能を提供します。たとえば、必要なときにだけ短期間有効な認証情報を発行し、使用後に無効化することが可能です。これにより、ツール間の認証情報の管理が簡素化され、パスワードの使い回しや長期間の露出によるセキュリティリスクを大幅に削減できます。
3. Vaultによるセキュリティの向上とアクセス制御の強化
   Vaultは、認証情報を暗号化して保存するため、万が一Jenkinsサーバーが侵害されたとしても、Vault内の認証情報が直接流出するリスクを最小限に抑えられます。また、Vaultでは詳細なアクセス制御ポリシーを設定可能であり、誰がどの認証情報にアクセスできるかを厳密に管理できます。さらに、すべての操作が監査ログに記録されるため、不正アクセスや事故が発生した場合でも追跡可能です。

本記事をきっかけに、ぜひVaultを使った認証情報管理の導入を検討してみてください。

補足：Vaultを実運用するときの注意点

ここまで、Vaultを利用するメリットについてお話してきましたが、Vaultにはそのツールの性質上、適切に運用しないとその効果を十分に発揮できない場合があります。本番環境でVaultを利用する際に注意すべきポイントを以下にまとめます。

1. 本番環境では開発モードで利用しない

冒頭でも説明していますが、今回はVaultを開発モードで実行しています。実は、このモードでは本番環境での利用には適していません。
(ここまで説明しておいてなんだよと思われた方、すみません。。。)

本番環境で運用する際には、開発モードでは起動せず、必ず適切なストレージバックエンドを設定し、データを永続化できる構成で運用してください。
なお、本番環境での構築はVault公式チュートリアルをご参照いただくのがおすすめです。self-managedという構築方法をご覧ください。

2. TLS認証の導入

Vaultを本番環境で運用する際には、TLS（SSL）による通信暗号化が必須です。TLSを設定することで、以下のセキュリティリスクを軽減できます。

• 通信データの盗聴（スニッフィング）
• 中間者攻撃（Man-in-the-Middle Attack）

3. Vaultがダウンした場合の対策

Vaultは機密情報の管理を一元化するためのツールです。そのため、Vaultがダウンすると、認証情報などのシークレットにアクセスできなくなり、システム全体に影響を与える可能性があります。以下の対策を検討してください。

• 高可用性構成の導入: クラスタリングを有効化して複数のノードで運用し、障害時にも他のノードで代替します。
• バックアップと復元計画: 定期的なデータバックアップと、迅速な復元手順を準備します。
• フェールセーフ設計: 必要に応じてシークレットのローカルキャッシュを導入し、Vaultがダウンしても最低限のサービスを維持します。
• 監視とアラートの設定: PrometheusやGrafanaを活用してVaultの稼働状況を監視し、ダウンタイムを最小限に抑えるアラートを設定します。

Vaultを本番環境で安全かつ効率的に運用するためには、これらの注意点を踏まえた設計・設定が必要です。適切なセキュリティ対策と可用性の確保を行い、システム全体の安定性を高めるようにしてください。

最後に

本記事では、JenkinsとHashiCorp Vaultの連携についてご紹介しました。様々なツールと連携できることがJenkinsの強みの一つですが、皆様の開発現場には、Jenkinsと連携したいけどまだ連携できていないツールが実はある、といったことはないでしょうか？
テクマトリックスでは、現在ご利用中のJenkins環境を調査、分析させていただく、アセスメントサービスや、Jenkins環境の改善をご支援するサービスも提供しております。
様々なツールと連携させることで、自動化の範囲を拡大させたり、業務効率を上げ、開発者の負担を減らすことが可能になりますので、Jenkinsのツール連携にお困りごとがございましたら、ぜひテクマトリックスまでお気軽にご相談ください。