# Spring Credhub
Spring Credhub 提供了客户端支持,用于从运行在Cloud Foundry (opens new window)平台中的CredHub (opens new window)服务器中存储、检索和删除凭据。
Credhub 提供HTTP API (opens new window)来安全地存储、生成、检索和删除各种类型的凭据。 Spring Credhub 为 Credhub API 提供了一个 Java 绑定,使得将 Spring 应用程序与 Credhub 集成起来变得很容易。
# 1.开始
Spring CredHub 支持 CredHub Server1.x 和 2.x 版本。该库旨在提供对 Credhub API 的完整覆盖--对所有凭据类型的所有操作。
Spring Credhub 已经进行了优化,以便与 Spring 引导应用程序一起工作。要在 Spring 引导应用程序中包含 Spring CredHub,请向项目构建文件中添加一些依赖项。
# 1.1. Maven Dependencies
将 Spring credhub 启动器添加到构建文件的dependencies
部分:
<dependencies>
<dependency>
<groupId>org.springframework.credhub</groupId>
<artifactId>spring-credhub-starter</artifactId>
<version>2.2.0</version>
</dependency>
</dependencies>
要在 Spring Credhub 中启用反应性支持,请将以下Spring WebFlux (opens new window)依赖项添加到构建文件中:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
<version>5.3.13</version>
</dependency>
</dependencies>
要对 Credhub 使用 OAuth2 身份验证,请将以下Spring Security (opens new window)依赖项添加到构建文件中:
<dependencies>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-config</artifactId>
<version>5.5.3</version>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-client</artifactId>
<version>5.5.3</version>
</dependency>
</dependencies>
# 1.2. Gradle Dependencies
将 Spring credhub 启动器添加到构建文件的dependencies
部分:
dependencies {
compile('org.springframework.credhub:spring-credhub-starter:2.2.0')
}
要在 Spring Credhub 中启用反应性支持,请在构建文件中添加以下Spring WebFlux (opens new window)依赖项:
dependencies {
compile("org.springframework.boot:spring-boot-starter-webflux:5.3.13")
}
要对 Credhub 使用 OAuth2 身份验证,请将以下Spring Security (opens new window)依赖项添加到构建文件中:
dependencies {
compile("org.springframework.security:spring-security-config:5.5.3")
compile("org.springframework.security:spring-security-oauth2-client:5.5.3")
}
# 2. Spring Boot Configuration
当使用 Spring Credhub Starter 依赖项时, Spring Credhub 可以配置为Spring Boot application properties (opens new window)。有了适当的配置属性, Spring Credhub 将自动配置到 Credhub 服务器的连接。
# 2.1.双向 TLS 认证
在 Cloud Foundry 上运行的应用程序可以使用共同的 TLS 对部署在同一平台上的 CredHub 服务器进行身份验证。当不提供其他身份验证凭据时,Mutual TLS 是默认的身份验证方案。要对 Credhub 服务器使用共同的 TLS 身份验证,只需提供 Credhub 服务器的 URL 作为应用程序属性:
spring:
credhub:
url: [CredHub server URL]
有关双向 TLS 身份验证的更多信息,请参见CredHub 文档 (opens new window)。
在 Cloud Foundry 上运行的应用程序可以使用内部地址[https://credhub.service.cf.internal:8844](https://credhub.service.cf.internal:8844)
与部署到同一平台的 CredHub 服务器通信。
# 2.2.OAuth2 身份验证
OAuth2 可用于通过对任何 Credhub 服务器的 UAA 进行身份验证。 Spring Credhub 支持使用以下 Spring Credhub 和 Spring 安全配置进行身份验证的客户端凭据授予令牌:
spring:
credhub:
url: [CredHub server URL]
oauth2:
registration-id: credhub-client
security:
oauth2:
client:
registration:
credhub-client:
provider: uaa
client-id: [OAuth2 client ID]
client-secret: [OAuth2 client secret]
authorization-grant-type: client_credentials
provider:
uaa:
token-uri: [UAA token server endpoint]
在spring.credhub.oauth2.registration-id
中提供的 ID 必须引用在spring.security.oauth2.client.registration
下配置的客户端。有关 Spring Boot OAuth2 客户端配置的更多信息,请参见Spring Boot documentation (opens new window)。
Spring 安全客户端注册中指定的 OAuth2 客户端必须具有像credhub.read
或credhub.write
这样的 Credhub 作用域,才能执行大多数操作。有关使用 UAA 进行 OAuth2 身份验证的更多信息,请参见CredHub 文档 (opens new window)。
# 2.2.1. Auto-configuration of Spring Security OAuth2
当spring.credhub.oauth2
属性被设置并且 Spring 安全性在应用程序 Classpath 上时, Spring Credhub 将自动配置 OAuth2 身份验证所需的 Spring 安全性 bean。 Spring 应用程序可以提供所需的安全性 OAuth2bean,以便在必要时覆盖自动配置。
# Servlet and Non-reactive Applications
Spring Credhub 需要以下类型的 bean,由 Spring Security 提供,以便使用 OAuth2 进行身份验证。
Required Bean Type | 自动配置类型 |
---|---|
ClientRegistrationRepository (opens new window) | [InMemoryClientRegistrationRepository ](https://DOCS. Spring.io/ Spring-security/site/DOCS/5.5.3/api/org/springframework/security/oAuth2/client/registration/inmemoryclientregistrationrepository.html) |
OAuth2AuthorizedClientRepository (opens new window) | [AuthenticatedPrincipalOAuth2AuthorizedClientRepository ](https://DOCS. Spring.io/ Spring-security/site/DOCS/5.5.3/api/org/springframework/security/oAuth2/client/web/authenticatedprincipalouth2authorizedclientrepository.html) |
OAuth2AuthorizedClientManager (opens new window) | [DefaultOAuth2AuthorizedClientManager ](https://DOCS. Spring.io/ Spring-security/site/DOCS/5.5.3/api/org/springframework/security/oAuth2/client/web\defaultoth2authorizedclientmanager.html) |
自动配置的DefaultOAuth2AuthorizedClientManager
假设应用程序在 Servlet 容器中运行,并且具有活动的HttpServletRequest
。应用程序可能需要提供OAuth2AuthorizedClientManager
Bean 的替代实现,例如[AuthorizedClientServiceOAuth2AuthorizedClientManager
](https://DOCS. Spring.io/ Spring-security/site/DOCS/5.5.3/api/org/springframework/security/outh2/client/authorizedclientserviceouth2authorizedclientmanager.html),以处理<gtr="60"/>以外的请求,如以下示例所示:
/*
* Copyright 2016-2020 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.example.credhub;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.client.AuthorizedClientServiceOAuth2AuthorizedClientManager;
import org.springframework.security.oauth2.client.ClientCredentialsOAuth2AuthorizedClientProvider;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
@Configuration
public class CredHubSecurityConfiguration {
@Bean
public AuthorizedClientServiceOAuth2AuthorizedClientManager reactiveClientManager(
ClientRegistrationRepository clientRegistrationRepository,
OAuth2AuthorizedClientService authorizedClientService) {
AuthorizedClientServiceOAuth2AuthorizedClientManager clientManager = new AuthorizedClientServiceOAuth2AuthorizedClientManager(
clientRegistrationRepository, authorizedClientService);
clientManager.setAuthorizedClientProvider(new ClientCredentialsOAuth2AuthorizedClientProvider());
return clientManager;
}
}
有关更多信息和配置其他 bean 的示例,请参见Spring Security documentation (opens new window)。
# 反应性应用
Spring Credhub 需要以下类型的 bean,由 Spring Security 提供,以便使用 OAuth2 进行身份验证。
Required Bean Type | 自动配置类型 |
---|---|
ReactiveClientRegistrationRepository (opens new window) | [InMemoryReactiveClientRegistrationRepository ](https://DOCS. Spring.io/ Spring-security/site/DOCS/5.5.3/api/org/springframework/security/oAuth2/client/registration/inmemoryreactiveClientRegistrationRepository.html) |
ServerOAuth2AuthorizedClientRepository (opens new window) | [UnAuthenticatedServerOAuth2AuthorizedClientRepository ](https://DOCS. Spring.io/ Spring-security/site/DOCS/5.5.3/api/org/springframework/security/oAuth2/client/web/server/unauthenticatedserveroauth2authorizedclientrepository.html) |
ReactiveOAuth2AuthorizedClientManager (opens new window) | [DefaultReactiveOAuth2AuthorizedClientManager ](https://DOCS. Spring.io/ Spring-security/site/DOCS/5.5.3/api/org/springframework/security/oAuth2/client/web/defaultreactiveoAuth2authorizedclientmanager.html) |
自动配置的DefaultReactiveOAuth2AuthorizedClientManager
需要活动的ServerHttpRequest
上下文。应用程序可能需要提供ReactiveOAuth2AuthorizedClientManager
Bean 的替代实现,例如[AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager
](https://DOCS. Spring.io/ Spring-security/site/DOCS/5.5.3/api/org/springframework/security/oauth2/client/authorizedclientservicerereactiveoauth2authorizedclientmanager.html),以处理<gtr="71"/>以外的请求,如以下示例所示:
/*
* Copyright 2016-2020 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.example.credhub;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.oauth2.client.AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager;
import org.springframework.security.oauth2.client.ClientCredentialsReactiveOAuth2AuthorizedClientProvider;
import org.springframework.security.oauth2.client.ReactiveOAuth2AuthorizedClientService;
import org.springframework.security.oauth2.client.registration.ReactiveClientRegistrationRepository;
@Configuration
public class CredHubReactiveSecurityConfiguration {
@Bean
public AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager reactiveClientManager(
ReactiveClientRegistrationRepository clientRegistrationRepository,
ReactiveOAuth2AuthorizedClientService authorizedClientService) {
AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager clientManager = new AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager(
clientRegistrationRepository, authorizedClientService);
clientManager.setAuthorizedClientProvider(new ClientCredentialsReactiveOAuth2AuthorizedClientProvider());
return clientManager;
}
}
有关配置其他 bean 的更多信息和示例,请参见Spring Security documentation (opens new window)。
# 3.CredHubOperations 简介
接口org.springframework.credhub.core.CredHubOperations
和实现org.springframework.credhub.core.CredHubTemplate
是 Spring Credhub 中的中心类。CredHubOperations
提供了对模拟完整 Credhub API 的附加操作接口的访问:
/**
* Get the operations for saving, retrieving, and deleting credentials.
*/
CredHubCredentialOperations credentials();
/**
* Get the operations for adding, retrieving, and deleting credential permissions.
*/
CredHubPermissionOperations permissions();
/**
* Get the operations for adding, retrieving, and deleting credential permissions.
*/
CredHubPermissionV2Operations permissionsV2();
/**
* Get the operations for retrieving, regenerating, and updating certificates.
*/
CredHubCertificateOperations certificates();
/**
* Get the operations for interpolating service binding credentials.
*/
CredHubInterpolationOperations interpolation();
/**
* Get the operations for retrieving CredHub server information.
*/
CredHubInfoOperations info();
# 3.1.映射到 credhub API
Operations
接口的每个方法都直接映射到 credhub HTTP API 的一个端点。下表显示了 credhub API 和相应的 Spring credhubOperations
接口之间的映射。
# 3.2.CredHubOperations 自动配置
当应用程序属性被正确配置时,使用 Spring 引导自动配置来创建CredHubOperations
Spring Bean。 Bean 应用程序类可以自动连接此实例,以与 Credhub 服务器进行交互。
/*
* Copyright 2016-2020 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.example.credhub;
import org.springframework.credhub.core.CredHubOperations;
import org.springframework.credhub.support.CredentialDetails;
import org.springframework.credhub.support.SimpleCredentialName;
import org.springframework.credhub.support.password.PasswordCredential;
import org.springframework.credhub.support.password.PasswordParameters;
import org.springframework.credhub.support.password.PasswordParametersRequest;
import org.springframework.stereotype.Component;
@Component
public class CredHubService {
private final CredHubOperations credHubOperations;
private final SimpleCredentialName credentialName;
public CredHubService(CredHubOperations credHubOperations) {
this.credHubOperations = credHubOperations;
this.credentialName = new SimpleCredentialName("example", "password");
}
public String generatePassword() {
PasswordParameters parameters = PasswordParameters.builder().length(12).excludeLower(false).excludeUpper(false)
.excludeNumber(false).includeSpecial(true).build();
CredentialDetails<PasswordCredential> password = this.credHubOperations.credentials()
.generate(PasswordParametersRequest.builder().name(this.credentialName).parameters(parameters).build());
return password.getValue().getPassword();
}
public String getPassword() {
CredentialDetails<PasswordCredential> password = this.credHubOperations.credentials()
.getByName(this.credentialName, PasswordCredential.class);
return password.getValue().getPassword();
}
}
# 4.重新激活的硬件操作介绍
接口org.springframework.credhub.core.ReactiveCredHubOperations
和实现org.springframework.credhub.core.ReactiveCredHubTemplate
是 Spring Credhub Reactive Support 中的中心类。ReactiveCredHubOperations
提供了对其他操作接口的访问,这些操作接口为完整的 Credhub API 建模:
/**
* Get the operations for saving, retrieving, and deleting credentials.
*/
ReactiveCredHubCredentialOperations credentials();
/**
* Get the operations for adding, retrieving, and deleting credential permissions.
*/
ReactiveCredHubPermissionOperations permissions();
/**
* Get the operations for adding, retrieving, and deleting credential permissions.
*/
ReactiveCredHubPermissionV2Operations permissionsV2();
/**
* Get the operations for retrieving, regenerating, and updating certificates.
*/
ReactiveCredHubCertificateOperations certificates();
/**
* Get the operations for interpolating service binding credentials.
*/
ReactiveCredHubInterpolationOperations interpolation();
/**
* Get the operations for retrieving CredHub server information.
*/
ReactiveCredHubInfoOperations info();
# 4.1.映射到 credhub API
Reactive…Operations
接口的每个方法都直接映射到 credhub HTTP API 的一个端点。下表显示了 credhub API 与相应的 Spring credhubReactive…Operations
接口之间的映射。
# 4.2.重新激活和操作自动配置
当应用程序属性被正确配置并且 Spring WebFlux 库在 Classpath 上时,使用 Spring 引导自动配置来创建ReactiveCredHubOperations
Spring Bean。 Bean 应用程序类可以自动连接此实例以与 Credhub 服务器交互。
/*
* Copyright 2016-2020 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.example.credhub;
import reactor.core.publisher.Mono;
import org.springframework.credhub.core.ReactiveCredHubOperations;
import org.springframework.credhub.support.SimpleCredentialName;
import org.springframework.credhub.support.password.PasswordCredential;
import org.springframework.credhub.support.password.PasswordParameters;
import org.springframework.credhub.support.password.PasswordParametersRequest;
import org.springframework.stereotype.Component;
@Component
public class ReactiveCredHubService {
private final ReactiveCredHubOperations credHubOperations;
private final SimpleCredentialName credentialName;
public ReactiveCredHubService(ReactiveCredHubOperations credHubOperations) {
this.credHubOperations = credHubOperations;
this.credentialName = new SimpleCredentialName("example", "password");
}
public Mono<String> generatePassword() {
PasswordParameters parameters = PasswordParameters.builder().length(12).excludeLower(false).excludeUpper(false)
.excludeNumber(false).includeSpecial(true).build();
return this.credHubOperations.credentials()
.generate(PasswordParametersRequest.builder().name(this.credentialName).parameters(parameters).build(),
PasswordCredential.class)
.map((password) -> password.getValue().getPassword());
}
public Mono<String> getPassword() {
return this.credHubOperations.credentials().getByName(this.credentialName, PasswordCredential.class)
.map((password) -> password.getValue().getPassword());
}
}
# 5.HTTP 客户端支持
Spring CredhubCredHubOperations
支持多个 HTTP 客户库与 Credhub API 通信。支持以下库:
Java 的内置
HttpURLConnection
(默认)
Classpath 选择特定的客户端库需要在应用程序上可用的适当的依赖关系。 Classpath 将按照上面列出的顺序检查每个客户库的应用程序。
Spring CredhubReactiveCredHubOperations
只支持 Netty HTTP 客户端库。
# 5.1. Apache HttpComponents
要使用 Apache HttpComponents 与 CredHub 通信,请向应用程序添加以下依赖项:
<dependency>
<groupId>org.apache.httpcomponents</groupId>
<artifactId>httpclient</artifactId>
</dependency>
Apache 可以通过日志配置启用 HttpClient 的电汇测井 (opens new window)。确保不会意外地启用有线日志,因为日志可能会以纯文本形式暴露应用程序和 Credhub 之间的流量(包括令牌和秘密)。 |
---|
# 5.2.OKHTTP3
要使用 OKHTTP3 与 Credhub 通信,请向应用程序添加以下依赖项:
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp</artifactId>
</dependency>
# 5.3. Netty
要使用 Netty 与 Credhub 通信,请向应用程序添加以下依赖项:
<dependency>
<groupId>io.netty</groupId>
<artifactId>netty-all</artifactId>
</dependency>