Client support

Spring Vault 支持各种 HTTP 客户端来访问 Vault 的 HTTP API。Spring Vault 使用 {spring-framework-docs}integration.html#rest-resttemplate[RestTemplate] 作为访问 Vault 的主要接口。专用客户端支持源自 customized SSL configuration ，它仅限于 Spring Vault 的客户端组件。

Spring Vault supports various HTTP clients to access Vault’s HTTP API. Spring Vault uses {spring-framework-docs}integration.html#rest-resttemplate[RestTemplate] as primary interface accessing Vault. Dedicated client support originates from vault.client-ssl that is scoped only to Spring Vault’s client components.

Spring Vault 支持以下 HTTP 命令式客户端：

Spring Vault supports following HTTP imperative clients:

  • Java’s builtin HttpURLConnection (default client if no other is available)

  • Apache Http Components

  • OkHttp 3

Spring Vault 的反应式集成支持以下反应式 HTTP 客户端：

Spring Vault’s reactive integration supports the following reactive HTTP clients:

  • Java’s builtin reactive HttpClient (default client if no other is available)

  • Reactor Netty

  • Apache Http Components

  • Jetty

使用特定客户端需要相应的依赖项在类路径中可用，以便 Spring Vault 可以使用可用的客户端与 Vault 通信。

Using a specific client requires the according dependency to be available on the classpath so Spring Vault can use the available client for communicating with Vault.

Java’s builtin HttpURLConnection

Java 的内置 HttpURLConnection 可开箱即用，无需其他配置。使用 HttpURLConnection 时，SSL 配置存在一定限制。Spring Vault 不会应用 customized SSL configuration ，因为它需要对 JVM 进行深度重新配置。此配置将影响所有依赖于默认 SSL 上下文的组件。使用 HttpURLConnection 配置 SSL 设置要求您将这些设置作为系统属性提供。请参阅 Customizing JSSE 以了解更多详情。

Java’s builtin HttpURLConnection is available out-of-the-box without additional configuration. Using HttpURLConnection comes with a limitation regarding SSL configuration. Spring Vault won’t apply vault.client-ssl as it would require a deep reconfiguration of the JVM. This configuration would affect all components relying on the default SSL context. Configuring SSL settings using HttpURLConnection requires you providing these settings as System Properties. See Customizing JSSE for further details.

External Clients

你可以使用外部客户端来访问 Vault 的 API。只需将以下依赖项之一添加到你的项目中。如果你使用 Spring Vault’s Dependency BOM，则可以省略版本号。

You can use external clients to access Vault’s API. Simply add one of the following dependencies to your project. You can omit the version number if using dependencies

Example 1. Apache Http Components Dependency
<dependency>
  <groupId>org.apache.httpcomponents.client5</groupId>
  <artifactId>httpclient5</artifactId>
</dependency>

Apache HttpClient 的 wire logging 可以通过日志记录配置来启用。确保不要意外启用线路记录，因为日志可能会以纯文本形式公开你的应用程序和 Vault 之间的通信（令牌和密钥）。

Apache HttpClient’s wire logging can be enabled through logging configuration. Make sure to not accidentally enable wire logging as logs may expose traffic (tokens and secrets) between your application and Vault in plain text.
Example 2. Square OkHttp 3
<dependency>
  <groupId>com.squareup.okhttp3</groupId>
  <artifactId>okhttp</artifactId>
</dependency>
Example 3. Reactor Netty
<dependency>
  <groupId>io.projectreactor.netty</groupId>
  <artifactId>reactor-netty</artifactId>
</dependency>
Example 4. Apache Http Components Reactive Dependency
<dependency>
  <groupId>org.apache.httpcomponents.core5</groupId>
  <artifactId>httpcore5-reactive</artifactId>
</dependency>
Example 5. Jetty
<dependency>
  <groupId>org.eclipse.jetty</groupId>
  <artifactId>jetty-reactive-httpclient</artifactId>
</dependency>

Vault Client SSL configuration

可以通过设置各种属性来使用 SslConfiguration 配置 SSL。你可以设置 javax.net.ssl.trustStore 来配置 JVM 范围的 SSL 设置，也可以设置 SslConfiguration 来仅为 Spring Vault 设置 SSL 设置。

SSL can be configured using SslConfiguration by setting various properties. You can set either javax.net.ssl.trustStore to configure JVM-wide SSL settings or configure SslConfiguration to set SSL settings only for Spring Vault.

SslConfiguration sslConfiguration = SslConfiguration.create(            1
		new FileSystemResource("client-cert.jks"), "changeit".toCharArray(),
		new FileSystemResource("truststore.jks"), "changeit".toCharArray());

SslConfiguration.forTrustStore(new FileSystemResource("keystore.jks"),  2
                                      "changeit".toCharArray())

SslConfiguration.forKeyStore(new FileSystemResource("keystore.jks"),    3
                                      "changeit".toCharArray())

SslConfiguration.forKeyStore(new FileSystemResource("keystore.jks"),    4
                                      "changeit".toCharArray(),
                                      KeyConfiguration.of("key-password".toCharArray(),
                                      "my-key-alias"))
1 Full configuration.
2 Configuring only trust store settings.
3 Configuring only key store settings.
4 Configuring only key store settings with providing a key-configuration.

请注意，仅当 Apache Http Components 或 OkHttp 客户端在你的类路径中时，才可提供 SslConfiguration。

Please note that providing SslConfiguration can be only applied when either Apache Http Components or the OkHttp client is on your class-path.

SSL 配置还支持 PEM 编码证书，作为 Java 密钥库的替代方法。

The SSL configuration supports also PEM-encoded certificates as alternative to a Java Key Store.

KeyStoreConfiguration keystore = KeyStoreConfiguration
        .of(new ClassPathResource("ca.pem")).withStoreType("PEM");
SslConfiguration configuration = SslConfiguration.forTrustStore(keystore);

PEM 文件可能包含一个或多个证书（-----BEGIN CERTIFICATE----- 和 -----END CERTIFICATE----- 块）。添加到底层 KeyStore 的证书使用完整主题名作为别名。

PEM files may contain one or more certificates (blocks of -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----). Certificates added to the underlying KeyStore use the full subject name as alias.