クイックスタート

このセクションでは、Vault および Spring Cloud Vault の使用を開始する方法について説明します。

前提条件

Vault とこのガイドの使用を開始するには、以下を提供する *NIX のようなオペレーティングシステムが必要です。

wget、openssl、unzip
少なくとも Java 8 と適切に構成された JAVA_HOME 環境変数

このガイドでは、統合テストのための Spring Cloud Vault の観点から Vault のセットアップについて説明します。スタートガイドは、Vault プロジェクトサイト (learn.hashicorp.com/vault (英語) ) で直接見つけることができます。

Vault をインストールする

$ wget https://releases.hashicorp.com/vault/${vault_version}/vault_${vault_version}_${platform}.zip
$ unzip vault_${vault_version}_${platform}.zip

これらの手順は、install_vault.sh [GitHub] (英語) をダウンロードして実行することで実行できます。

Vault の SSL 証明書を作成する

次に、一連の証明書を生成する必要があります。

ルート CA
Vault 証明書 (復号化されたキー work/ca/private/localhost.decrypted.key.pem と証明書 work/ca/certs/localhost.cert.pem)

ルート証明書を Java 準拠のトラストストアにインポートしてください。

これを実現する最も簡単な方法は、OpenSSL を使用することです。

create_certificates.sh [GitHub] (英語) は、work/ca および JKS トラストストア work/keystore.jks に証明書を作成します。このクイックスタートガイドを使用して Spring Cloud Vault を実行する場合は、トラストストアの spring.cloud.vault.ssl.trust-store プロパティを file:work/keystore.jks に構成する必要があります。

Vault サーバーを起動する

次に、次の行に沿って構成ファイルを作成します。

backend "inmem" {
}

listener "tcp" {
  address = "0.0.0.0:8200"
  tls_cert_file = "work/ca/certs/localhost.cert.pem"
  tls_key_file = "work/ca/private/localhost.decrypted.key.pem"
}

disable_mlock = true

設定ファイルの例は vault.conf [GitHub] (英語) にあります。

$ vault server -config=vault.conf

Vault は、inmem ストレージと https を使用して 0.0.0.0:8200 での listen を開始します。Vault は封印されており、起動時に初期化されません。

テストを実行する場合は、Vault を初期化しないままにしておきます。テストでは Vault を初期化し、ルートトークン 00000000-0000-0000-0000-000000000000 を作成します。

Vault をアプリケーションに使用したい場合、または試してみたい場合は、まず初期化する必要があります。

$ export VAULT_ADDR="https://localhost:8200"
$ export VAULT_SKIP_VERIFY=true # Don't do this for production
$ vault operator init

次のようなものが表示されるはずです。

Key 1: 7149c6a2e16b8833f6eb1e76df03e47f6113a3288b3093faf5033d44f0e70fe701
Key 2: 901c534c7988c18c20435a85213c683bdcf0efcd82e38e2893779f152978c18c02
Key 3: 03ff3948575b1165a20c20ee7c3e6edf04f4cdbe0e82dbff5be49c63f98bc03a03
Key 4: 216ae5cc3ddaf93ceb8e1d15bb9fc3176653f5b738f5f3d1ee00cd7dccbe926e04
Key 5: b2898fc8130929d569c1677ee69dc5f3be57d7c4b494a6062693ce0b1c4d93d805
Initial Root Token: 19aefa97-cccc-bbbb-aaaa-225940e63d76

Vault initialized with 5 keys and a key threshold of 3. Please
securely distribute the above keys. When the Vault is re-sealed,
restarted, or stopped, you must provide at least 3 of these keys
to unseal it again.

Vault does not store the master key. Without at least 3 keys,
your Vault will remain permanently sealed.

Vault は初期化して、一連の開封キーとルートトークンを返します。3 つのキーを選択し、Vault の封印を解除します。Vault トークンを VAULT_TOKEN 環境変数に保存します。

$ vault operator unseal (Key 1)
$ vault operator unseal (Key 2)
$ vault operator unseal (Key 3)
$ export VAULT_TOKEN=(Root token)
# Required to run Spring Cloud Vault tests after manual initialization
$ vault token create -id="00000000-0000-0000-0000-000000000000" -policy="root"

Spring Cloud Vault はさまざまなリソースにアクセスします。デフォルトでは、JSON エンドポイント経由でシークレット構成設定にアクセスするシークレットバックエンドが有効になっています。

HTTP サービスには次の形式のリソースがあります。

/secret/{application}/{profile}
/secret/{application}
/secret/{defaultContext}/{profile}
/secret/{defaultContext}

ここで、「アプリケーション」は SpringApplication に spring.application.name として挿入されます (つまり、通常の Spring Boot アプリでは通常「アプリケーション」となります)。「プロファイル」はアクティブなプロファイル (またはプロパティのカンマ区切りリスト) です。Vault から取得したプロパティは、プロパティ名の接頭辞を追加せずに「そのまま」使用されます。

クライアント側の使用箇所

これらの機能をアプリケーションで使用するには、spring-cloud-vault-config に依存する Spring Boot アプリケーションとしてビルドするだけです (たとえば、テストケースを参照)。Maven 構成の例:

pom.xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>${springBootVersion}</version>
    <relativePath /> <!-- lookup parent from repository -->
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-vault-config</artifactId>
        <version>4.2.0</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

<!-- repositories also needed for snapshots and milestones -->

次に、次の単純な HTTP サーバーのような標準の Spring Boot アプリケーションを作成できます。

@SpringBootApplication
@RestController
public class Application {

    @RequestMapping("/")
    public String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

実行すると、ポート 8200 上のデフォルトのローカル Vault サーバーから外部構成が取得されます (実行中の場合)。起動動作を変更するには、たとえば application.properties を使用して Vault サーバーの場所を変更します。

application.yml

spring.cloud.vault:
    host: localhost
    port: 8200
    scheme: https
    uri: https://localhost:8200
    connection-timeout: 5000
    read-timeout: 15000
spring.config.import: vault://

host は、Vault ホストのホスト名を設定します。ホスト名は SSL 証明書の検証に使用されます
port は Vault ポートを設定します
scheme がスキームを http に設定すると、プレーン HTTP が使用されます。サポートされているスキームは http および https です。
uri は、URI を使用して Vault エンドポイントを構成します。ホスト / ポート / スキーム構成よりも優先されます。
connection-timeout は接続タイムアウトをミリ秒単位で設定します
read-timeout は読み取りタイムアウトをミリ秒単位で設定します
spring.config.import は、有効なすべてのシークレットバックエンドを使用して Vault を PropertySource としてマウントします (デフォルトで有効になっている Key-Value)

さらに統合を有効にするには、追加の依存関係と構成が必要です。Vault の設定方法によっては、SSL や認証などの追加構成が必要になる場合があります。

アプリケーションが spring-boot-starter-actuator プロジェクトをインポートする場合、Vault サーバーのステータスは /health エンドポイント経由で利用可能になります。

ボールトの健全性インジケーターは、プロパティ management.health.vault.enabled (デフォルトは true) によって有効または無効にできます。

Spring Cloud Vault 3.0 および Spring Boot 2.4 では、プロパティソースのブートストラップコンテキスト初期化 (bootstrap.yml、bootstrap.properties) は非推奨になりました。代わりに、Spring Cloud Vault は、Vault から設定をインポートできる Spring Boot の Config Data API を優先します。Spring Boot Config Data アプローチでは、Vault にバインドするために spring.config.import プロパティを設定する必要があります。詳細については、「構成データの場所」セクションを参照してください。ブートストラップコンテキストを有効にするには、構成プロパティ spring.cloud.bootstrap.enabled=true を設定するか、依存関係 org.springframework.cloud:spring-cloud-starter-bootstrap を含めます。

認証

Vault には、クライアントリクエストを承認する (英語) ための認証メカニズム (英語) が必要です。

Spring Cloud Vault は、Vault でアプリケーションを認証するための複数の認証メカニズムをサポートしています。

クイックスタートとして、Vault の初期化によって出力されたルートトークンを使用します。

application.yml

spring.cloud.vault:
    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
spring.config.import: vault://

セキュリティ要件を慎重に検討してください。Vault をすぐに使い始めたい場合は、静的トークン認証でも問題ありませんが、静的トークンはそれ以上保護されません。意図しない当事者への開示により、関連するトークンロールでの Vault の使用が許可されます。