VaultTemplate の概要
パッケージ org.springframework.vault.core
にあるクラス VaultTemplate
(Javadoc) は、Spring の Vault サポートの中心となるクラスで、Vault と対話するための豊富な機能セットを提供します。このテンプレートは、Vault のデータの読み取り、書き込み、削除を行うための便利な操作を提供し、ドメインオブジェクトと Vault データ間のマッピングを提供します。
一度設定されると、VaultTemplate (Javadoc) はスレッドセーフとなり、複数のインスタンス間で再利用できます。 |
Vault ドキュメントとドメインクラス間のマッピングは、RestTemplate
に委譲することによって行われます。Spring Web サポートは、マッピングインフラストラクチャを提供します。
VaultTemplate
(Javadoc) クラスは、インターフェース VaultOperations
(Javadoc) を実装します。可能な限り、VaultOperations
(Javadoc) のメソッドは、API と CLI に慣れている既存の Vault 開発者に API を馴染みのあるものにするために、Vault API で利用可能なメソッドにちなんで名付けられています。たとえば、"write"、"delete"、"read"、"revoke" などのメソッドがあります。設計ゴールは、Vault API と VaultOperations
の使用をできるだけ簡単に移行できるようにすることでした。2 つの API の主な違いは、VaultOperations
に JSON キーと値のペアではなくドメインオブジェクトを渡すことができることです。
VaultTemplate (Javadoc) インスタンスの操作を参照する推奨方法は、そのインターフェース VaultOperations (Javadoc) を使用することです。 |
VaultTemplate
には、Vault API に直接アクセスして VaultTemplate
によって明示的に公開されていない機能にアクセスする必要がある場合に、一般的なタスクを簡単に実行できる便利なメソッドが多数ありますが、いくつかの実行コールバックメソッドの 1 つを使用して、基になる API にアクセスできます。実行コールバックは、RestOperations
オブジェクトへの参照を提供します。詳細については、セクション実行コールバックを参照してください。
次に、Spring コンテナーのコンテキストで Vault を操作する方法の例を見てみましょう。
Spring Vault Bean の登録と構成
Spring Vault の使用には、Spring コンテキストは必要ありません。ただし、管理対象コンテキスト内に登録された VaultTemplate
および SessionManager
(Javadoc) のインスタンスは、Spring IoC コンテナーによって提供されるライフサイクルイベントに参加します。これは、アプリケーションのシャットダウン時にアクティブな Vault セッションを破棄できます。また、アプリケーション全体で同じ VaultTemplate
インスタンスを再利用することでもメリットがあります。
Spring Vault には、Spring コンテキスト内で使用する Bean 定義を提供するサポート構成クラスが付属しています。アプリケーション構成クラスは通常、AbstractVaultConfiguration
(Javadoc) から拡張され、環境固有の追加の詳細を提供する必要があります。
AbstractVaultConfiguration
(Javadoc) から拡張するには、VaultEndpoint vaultEndpoint()
および ClientAuthentication clientAuthentication()
メソッドを実装する必要があります。
@Configuration
public class AppConfig extends AbstractVaultConfiguration {
/**
* Specify an endpoint for connecting to Vault.
*/
@Override
public VaultEndpoint vaultEndpoint() {
return new VaultEndpoint(); (1)
}
/**
* Configure a client authentication.
* Please consider a more secure authentication method
* for production use.
*/
@Override
public ClientAuthentication clientAuthentication() {
return new TokenAuthentication("…"); (2)
}
}
1 | デフォルトで https://localhost:8200 を指す新しい VaultEndpoint (Javadoc) を作成します。 |
2 | このサンプルでは、すぐに開始できるように TokenAuthentication (Javadoc) を使用します。サポートされている認証方法の詳細については、[vault.core.authentication] を参照してください。 |
@Configuration
public class AppConfig extends AbstractVaultConfiguration {
@Value("${vault.uri}")
URI vaultUri;
/**
* Specify an endpoint that was injected as URI.
*/
@Override
public VaultEndpoint vaultEndpoint() {
return VaultEndpoint.from(vaultUri); (1)
}
/**
* Configure a Client Certificate authentication.
* {@link RestOperations} can be obtained from {@link #restOperations()}.
*/
@Override
public ClientAuthentication clientAuthentication() {
return new ClientCertificateAuthentication(restOperations()); (2)
}
}
1 | VaultEndpoint (Javadoc) は、from(URI uri) や VaultEndpoint.create(String host, int port) などのさまざまなファクトリメソッドを使用して構築できます。 |
2 | ClientAuthentication メソッドの依存関係は、AbstractVaultConfiguration から取得するか、構成によって提供することができます。 |
カスタム構成クラスの作成は、場合によっては面倒な場合があります。既存のプロパティソースのプロパティを使用して構成できる EnvironmentVaultConfiguration (Javadoc) と Spring の Environment を参照してください。詳細については、EnvironmentVaultConfiguration の使用を参照してください。 |
セッション管理
Spring Vault では、Vault にログインしてアクセスするために ClientAuthentication
が必要です。認証に関する詳細については、[vault.core.authentication] を参照してください。Vault ログインは、認証された Vault インタラクションごとに発生するのではなく、セッション全体で再利用する必要があります。この側面は、SessionManager
実装によって処理されます。SessionManager
は、失効と更新について、トークンを取得する頻度を決定します。Spring Vault には 2 つの実装があります。
SimpleSessionManager
(Javadoc) : リフレッシュや取り消しなしで、提供されたClientAuthentication
からトークンを取得するだけですLifecycleAwareSessionManager
(Javadoc) : このSessionManager
は、トークンが更新可能な場合にトークンの更新をスケジュールし、廃棄時にログイントークンを取り消します。更新はAsyncTaskExecutor
で予定されています。AbstractVaultConfiguration
を使用する場合、デフォルトでLifecycleAwareSessionManager
が構成されます。
EnvironmentVaultConfiguration
を使用する
Spring、Vault には、Spring の Environment
と定義済みのプロパティキーのセットから EnvironmentVaultConfiguration
(Javadoc) を構成する Vault クライアントが含まれています。EnvironmentVaultConfiguration
(Javadoc) は、頻繁に適用される構成をサポートします。その他の構成は、最も適切な構成クラスから派生することでサポートされます。@Import(EnvironmentVaultConfiguration.class)
を含む EnvironmentVaultConfiguration
(Javadoc) を既存の Java ベースの構成クラスに含め、Spring の PropertySource
のいずれかを通じて構成プロパティを提供します。
@PropertySource("vault.properties")
@Import(EnvironmentVaultConfiguration.class)
public class MyConfiguration{
}
vault.uri=https://localhost:8200
vault.token=00000000-0000-0000-0000-000000000000
プロパティキー
Vault URI:
vault.uri
SSL 構成
キーストアリソース:
vault.ssl.key-store
(オプション)鍵ストアパスワード:
vault.ssl.key-store-password
(オプション)鍵ストアタイプ:
vault.ssl.key-store-type
(オプション (通常はjks
) はpem
もサポートします)トラストストアリソース:
vault.ssl.trust-store
(オプション)トラストストアのパスワード:
vault.ssl.trust-store-password
(オプション)トラストストアの型:
vault.ssl.trust-store-type
(オプション (通常はjks
) はpem
もサポートします)有効な SSL/TLS プロトコル:
vault.ssl.enabled-protocols
(2.3.2 以降、オプション、カンマで区切られたプロトコル)有効化された SSL/TLS 暗号スイート:
vault.ssl.enabled-cipher-suites
(2.3.2 以降、オプション、カンマで区切られた暗号スイート)
認証方式:
vault.authentication
(デフォルトはTOKEN
、サポートされている認証方法は次のとおりです:TOKEN
、APPID
、APPROLE
、AWS_EC2
、AWS_IAM
、AZURE
、CERT
、CUBBYHOLE
、KUBERNETES
)
認証固有のプロパティキー
Vault トークン:
vault.token
AppId パス:
vault.app-id.app-id-path
(デフォルトはapp-id
)AppId:
vault.app-id.app-id
ユーザー ID:
vault.app-id.user-id
。MAC_ADDRESS
およびIP_ADDRESS
は、それぞれIpAddressUserId
ユーザー ID メカニズムであるMacAddressUserId
を使用します。その他の値はStaticUserId
で使用されます。
AppRole パス:
vault.app-role.app-role-path
(デフォルトはapprole
)RoleId:
vault.app-role.role-id
SecretId:
vault.app-role.secret-id
(オプション)
AWS EC2 パス:
vault.aws-ec2.aws-ec2-path
(デフォルトはaws-ec2
)ロール:
vault.aws-ec2.role
RoleId:
vault.aws-ec2.role-id
( 廃止された : 代わりにvault.aws-ec2.role
を使用してください)身分証明書の URL:
vault.aws-ec2.identity-document
(デフォルトは169.254.169.254/latest/dynamic/instance-identity/pkcs7 (英語)
)
ロール:
vault.aws-iam.role
Azure MSI パス:
vault.azure-msi.azure-path
(デフォルトはazure
)ロール:
vault.azure-msi.role
メタデータサービス URL:
vault.azure-msi.metadata-service
(デフォルトは169.254.169.254/metadata/instance?api-version=2017-08-01 (英語)
)ID TokenService URL:
vault.azure-msi.identity-token-service
(デフォルトは169.254.169.254/metadata/identity/oauth2/token?resource=https://vault.hashicorp.com&api-version=2018-02-01 (英語)
)
構成オプションはありません。
初期 Vault トークン:
vault.token
Kubernetes パス:
vault.kubernetes.kubernetes-path
(デフォルトはkubernetes
)ロール:
vault.kubernetes.role
サービスアカウントトークンファイルへのパス:
vault.kubernetes.service-account-token-file
(デフォルトは/var/run/secrets/kubernetes.io/serviceaccount/token
)
実行コールバック
すべての Spring テンプレートクラスに共通する設計上の特徴の 1 つは、すべての機能がテンプレートの実行コールバックメソッドの 1 つにルーティングされることです。これにより、例外や必要なリソース管理が一貫して実行されるようになります。これは、Vault の場合よりも JDBC や JMS の場合に非常に重要でしたが、それでもアクセスとログ記録を行うための単一の場所を提供します。そのため、実行コールバックを使用することは、VaultTemplate
(Javadoc) のメソッドとして公開していない珍しい操作を実行するために Vault API にアクセスする推奨される方法です。
実行コールバックメソッドのリストを次に示します。
<T> T
doWithVault(RestOperationsCallback<T> callback)
指定されたRestOperationsCallback
を実行し、セッションを必要とせずにRestOperations
を使用して Vault と対話できるようにします。<T> T
doWithSession(RestOperationsCallback<T> callback)
指定されたRestOperationsCallback
を実行し、認証されたセッションで Vault と対話できるようにします。
以下は、ClientCallback
を使用して Vault を初期化する例です。
vaultOperations.doWithVault(new RestOperationsCallback<VaultInitializationResponse>() {
@Override
public VaultInitializationResponse doWithRestOperations(RestOperations restOperations) {
ResponseEntity<VaultInitializationResponse> exchange = restOperations
.exchange("/sys/init", HttpMethod.PUT,
new HttpEntity<Object>(request),
VaultInitializationResponse.class);
return exchange.getBody();
}
});