Spring/spring-credhub
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add Security auto-configuration documentation and examples

Browse Source
This commit is contained in:
Scott Frederick
2020-06-01 18:38:53 -05:00
parent efbedf845f
commit ea402b76ff
8 changed files with 187 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
spring-credhub-docs/build.gradle
View File

@@ -41,6 +41,7 @@ configurations {
dependencies {
compile project(":spring-credhub-core")
compile("io.projectreactor:reactor-core")
compile("org.springframework.boot:spring-boot-autoconfigure")
docs("io.spring.docresources:spring-doc-resources:0.1.2.RELEASE@zip")
}

60
spring-credhub-docs/src/docs/asciidoc/boot-configuration.adoc
View File

@@ -39,6 +39,66 @@ See the {spring-boot-oauth}[Spring Boot documentation] for more information on S
The OAuth2 client specified in the Spring Security client registration must have CredHub scopes such as `credhub.read` or `credhub.write` to perform most operations.
See the {credhub-api-oauth}[CredHub documentation] for more information on OAuth2 authentication with UAA.
==== Auto-configuration of Spring Security OAuth2
When `spring.credhub.oauth2` properties are set and Spring Security is on the application classpath, Spring CredHub will auto-configure the Spring Security beans required for OAuth2 authentication.
An application can provide the required Spring Security OAuth2 beans to override the auto-configuration if necessary.
===== Servlet and Non-reactive Applications
Spring CredHub requires beans of the following types, provided by Spring Security, in order to authenticate using OAuth2.
[%header,cols=2*]
|===
| Required Bean Type
| Auto-configured Type
| {spring-security-apidocs-home}registration/ClientRegistrationRepository.html[`ClientRegistrationRepository`]
| {spring-security-apidocs-home}registration/InMemoryClientRegistrationRepository.html[`InMemoryClientRegistrationRepository`]
| {spring-security-apidocs-home}web/OAuth2AuthorizedClientRepository.html[`OAuth2AuthorizedClientRepository`]
| {spring-security-apidocs-home}web/AuthenticatedPrincipalOAuth2AuthorizedClientRepository.html[`AuthenticatedPrincipalOAuth2AuthorizedClientRepository`]
| {spring-security-apidocs-home}OAuth2AuthorizedClientManager.html[`OAuth2AuthorizedClientManager`]
| {spring-security-apidocs-home}web\DefaultOAuth2AuthorizedClientManager.html[`DefaultOAuth2AuthorizedClientManager`]
|===
The auto-configured `DefaultOAuth2AuthorizedClientManager` assumes the application is running in a servlet container and has an active `HttpServletRequest`.
An application might need to provide an alternate implementation of the `OAuth2AuthorizedClientManager` bean such as {spring-security-apidocs-home}AuthorizedClientServiceOAuth2AuthorizedClientManager.html[`AuthorizedClientServiceOAuth2AuthorizedClientManager`] to process requests outside of an `HttpServletRequest`, as shown in the following example:
[source,properties,%autofit]
----
include::{examples-dir}CredHubSecurityConfiguration.java[]
----
Refer to the {spring-security-ref-home}#oauth2login-override-boot-autoconfig[Spring Security documentation] for more information and examples of configuring other beans.
===== Reactive Applications
Spring CredHub requires beans of the following types, provided by Spring Security, in order to authenticate using OAuth2.
[%header,cols=2*]
|===
| Required Bean Type
| Auto-configured Type
| {spring-security-apidocs-home}registration/ReactiveClientRegistrationRepository.html[`ReactiveClientRegistrationRepository`]
| {spring-security-apidocs-home}registration/InMemoryReactiveClientRegistrationRepository.html[`InMemoryReactiveClientRegistrationRepository`]
| {spring-security-apidocs-home}web/server/ServerOAuth2AuthorizedClientRepository.html[`ServerOAuth2AuthorizedClientRepository`]
| {spring-security-apidocs-home}web/server/UnAuthenticatedServerOAuth2AuthorizedClientRepository.html[`UnAuthenticatedServerOAuth2AuthorizedClientRepository`]
| {spring-security-apidocs-home}ReactiveOAuth2AuthorizedClientManager.html[`ReactiveOAuth2AuthorizedClientManager`]
| {spring-security-apidocs-home}web/DefaultReactiveOAuth2AuthorizedClientManager.html[`DefaultReactiveOAuth2AuthorizedClientManager`]
|===
The auto-configured `DefaultReactiveOAuth2AuthorizedClientManager` requires an active `ServerHttpRequest` context.
An application might need to provide an alternate implementation of the `ReactiveOAuth2AuthorizedClientManager` bean such as {spring-security-apidocs-home}AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager.html[`AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager`] to process requests outside of an `ServerHttpRequest`, as shown in the following example:
[source,properties,%autofit]
----
include::{examples-dir}CredHubReactiveSecurityConfiguration.java[]
----
Refer to the {spring-security-ref-home}#oauth2login-override-boot-autoconfig[Spring Security documentation] for more information and examples of configuring other beans.

12
spring-credhub-docs/src/docs/asciidoc/getting-started.adoc
View File

@@ -28,7 +28,7 @@ To enable reactive support in Spring CredHub, add the following {spring-webflux}
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
<version>5.1.0.RELEASE</version>
<version>2.2.6.RELEASE</version>
</dependency>
</dependencies>
@@ -38,12 +38,12 @@ To use OAuth2 authentication to CredHub, add the following {spring-security}[Spr
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-config</artifactId>
<version>5.2.1.RELEASE</version>
<version>5.2.2.RELEASE</version>
</dependency>
<dependency>
<groupId>org.springframework.security</groupId>
<artifactId>spring-security-oauth2-client</artifactId>
<version>5.2.1.RELEASE</version>
<version>5.2.2.RELEASE</version>
</dependency>
</dependencies>
@@ -58,13 +58,13 @@ Add the Spring CredHub starter to the `dependencies` section of the build file:
To enable reactive support in Spring CredHub, add the following {spring-webflux}[Spring WebFlux] dependency to the build file:
dependencies {
compile("org.springframework.boot:spring-boot-starter-webflux:5.2.1.RELEASE")
compile("org.springframework.boot:spring-boot-starter-webflux:2.2.6.RELEASE")
}
To use OAuth2 authentication to CredHub, add the following {spring-security}[Spring Security] dependencies to the build file:
dependencies {
compile("org.springframework.security:spring-security-config:5.2.1.RELEASE")
compile("org.springframework.security:spring-security-oauth2-client:5.2.1.RELEASE")
compile("org.springframework.security:spring-security-config:5.2.2.RELEASE")
compile("org.springframework.security:spring-security-oauth2-client:5.2.2.RELEASE")
}

3
spring-credhub-docs/src/docs/asciidoc/index.adoc
View File

@@ -19,6 +19,9 @@ Scott Frederick;
:credhub-api-info: {credhub-api-home}version/master/#_info_endpoint
:cloudfoundry-home: https://www.cloudfoundry.org/
:apidocs-home: https://docs.spring.io/spring-credhub/docs/{revnumber}/api/index.html
:spring-security-version: 5.2.2.RELEASE
:spring-security-apidocs-home: https://docs.spring.io/spring-security/site/docs/{spring-security-version}/api/org/springframework/security/oauth2/client/
:spring-security-ref-home: https://docs.spring.io/spring-security/site/docs/{spring-security-version}/reference/html5/
(C) 2017-2018 The original authors.

28
spring-credhub-docs/src/docs/asciidoc/operations.adoc
View File

@@ -49,14 +49,26 @@ CredHubInfoOperations info();
Each method of the `Operations` interfaces maps directly to one endpoint of the CredHub HTTP API.
The following table shows the mapping between the CredHub API and the appropriate Spring CredHub `Operations` interface.
|=======
| {credhub-api-credentials}[CredHub Credentials API] | {apidocs-credentials}[CredHubCredentialOperations]
| {credhub-api-permissions}[CredHub Permissions API] (v1) | {apidocs-permissions}[CredHubPermissionOperations]
| {credhub-api-permissionsV2}[CredHub Permissions API] (v2) | {apidocs-permissionsV2}[CredHubPermissionV2Operations]
| {credhub-api-certificates}[CredHub Certificates API] | {apidocs-certificates}[CredHubCertificateOperations]
| {credhub-api-interpolation}[CredHub Interpolation API] | {apidocs-interpolation}[CredHubInterpolationOperations]
| {credhub-api-info}[CredHub Information API] | {apidocs-info}[CredHubInfoOperations]
|=======
[cols="2"]
|===
| {credhub-api-credentials}[CredHub Credentials API]
| {apidocs-credentials}[CredHubCredentialOperations]
| {credhub-api-permissions}[CredHub Permissions API] (v1)
| {apidocs-permissions}[CredHubPermissionOperations]
| {credhub-api-permissionsV2}[CredHub Permissions API] (v2)
| {apidocs-permissionsV2}[CredHubPermissionV2Operations]
| {credhub-api-certificates}[CredHub Certificates API]
| {apidocs-certificates}[CredHubCertificateOperations]
| {credhub-api-interpolation}[CredHub Interpolation API]
| {apidocs-interpolation}[CredHubInterpolationOperations]
| {credhub-api-info}[CredHub Information API]
| {apidocs-info}[CredHubInfoOperations]
|===
=== CredHubOperations Auto-configuration

26
spring-credhub-docs/src/docs/asciidoc/reactive-operations.adoc
View File

@@ -49,13 +49,25 @@ ReactiveCredHubInfoOperations info();
Each method of the `Reactive...Operations` interfaces maps directly to one endpoint of the CredHub HTTP API.
The following table shows the mapping between the CredHub API and the appropriate Spring CredHub `Reactive...Operations` interface.
|=======
| {credhub-api-credentials}[CredHub Credentials API] | {apidocs-reactive-credentials}[ReactiveCredHubCredentialOperations]
| {credhub-api-permissions}[CredHub Permissions API] (v1) | {apidocs-reactive-permissions}[ReactiveCredHubPermissionOperations]
| {credhub-api-permissionsV2}[CredHub Permissions API] (v2) | {apidocs-reactive-permissionsV2}[ReactiveCredHubPermissionV2Operations]
| {credhub-api-certificates}[CredHub Certificates API] | {apidocs-reactive-certificates}[ReactiveCredHubCertificateOperations]
| {credhub-api-interpolation}[CredHub Interpolation API] | {apidocs-reactive-interpolation}[ReactiveCredHubInterpolationOperations]
| {credhub-api-info}[CredHub Information API] | {apidocs-reactive-info}[CredHubInfoOperations]
[cols="2"]
|===
| {credhub-api-credentials}[CredHub Credentials API]
| {apidocs-reactive-credentials}[ReactiveCredHubCredentialOperations]
| {credhub-api-permissions}[CredHub Permissions API] (v1)
| {apidocs-reactive-permissions}[ReactiveCredHubPermissionOperations]
| {credhub-api-permissionsV2}[CredHub Permissions API] (v2)
| {apidocs-reactive-permissionsV2}[ReactiveCredHubPermissionV2Operations]
| {credhub-api-certificates}[CredHub Certificates API]
| {apidocs-reactive-certificates}[ReactiveCredHubCertificateOperations]
| {credhub-api-interpolation}[CredHub Interpolation API]
| {apidocs-reactive-interpolation}[ReactiveCredHubInterpolationOperations]
| {credhub-api-info}[CredHub Information API]
| {apidocs-reactive-info}[CredHubInfoOperations]
|=======
=== ReactiveCredHubOperations Auto-configuration

39
spring-credhub-docs/src/test/java/com/example/credhub/CredHubReactiveSecurityConfiguration.java Normal file
View File

@@ -0,0 +1,39 @@
/*
* 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;
}
}

39
spring-credhub-docs/src/test/java/com/example/credhub/CredHubSecurityConfiguration.java Normal file
View File

@@ -0,0 +1,39 @@
/*
* 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;
}
}