diff --git a/spring-credhub-docs/build.gradle b/spring-credhub-docs/build.gradle index 06bee00..9cbe76a 100644 --- a/spring-credhub-docs/build.gradle +++ b/spring-credhub-docs/build.gradle @@ -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") } diff --git a/spring-credhub-docs/src/docs/asciidoc/boot-configuration.adoc b/spring-credhub-docs/src/docs/asciidoc/boot-configuration.adoc index 405e6f8..ed2f6f0 100644 --- a/spring-credhub-docs/src/docs/asciidoc/boot-configuration.adoc +++ b/spring-credhub-docs/src/docs/asciidoc/boot-configuration.adoc @@ -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. diff --git a/spring-credhub-docs/src/docs/asciidoc/getting-started.adoc b/spring-credhub-docs/src/docs/asciidoc/getting-started.adoc index 8d116ab..5c27353 100644 --- a/spring-credhub-docs/src/docs/asciidoc/getting-started.adoc +++ b/spring-credhub-docs/src/docs/asciidoc/getting-started.adoc @@ -28,7 +28,7 @@ To enable reactive support in Spring CredHub, add the following {spring-webflux} org.springframework.boot spring-boot-starter-webflux - 5.1.0.RELEASE + 2.2.6.RELEASE @@ -38,12 +38,12 @@ To use OAuth2 authentication to CredHub, add the following {spring-security}[Spr org.springframework.security spring-security-config - 5.2.1.RELEASE + 5.2.2.RELEASE org.springframework.security spring-security-oauth2-client - 5.2.1.RELEASE + 5.2.2.RELEASE @@ -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") } diff --git a/spring-credhub-docs/src/docs/asciidoc/index.adoc b/spring-credhub-docs/src/docs/asciidoc/index.adoc index 83a927e..99808b8 100644 --- a/spring-credhub-docs/src/docs/asciidoc/index.adoc +++ b/spring-credhub-docs/src/docs/asciidoc/index.adoc @@ -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. diff --git a/spring-credhub-docs/src/docs/asciidoc/operations.adoc b/spring-credhub-docs/src/docs/asciidoc/operations.adoc index dad2068..f22d850 100644 --- a/spring-credhub-docs/src/docs/asciidoc/operations.adoc +++ b/spring-credhub-docs/src/docs/asciidoc/operations.adoc @@ -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 diff --git a/spring-credhub-docs/src/docs/asciidoc/reactive-operations.adoc b/spring-credhub-docs/src/docs/asciidoc/reactive-operations.adoc index 2f662d7..e51c827 100644 --- a/spring-credhub-docs/src/docs/asciidoc/reactive-operations.adoc +++ b/spring-credhub-docs/src/docs/asciidoc/reactive-operations.adoc @@ -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 diff --git a/spring-credhub-docs/src/test/java/com/example/credhub/CredHubReactiveSecurityConfiguration.java b/spring-credhub-docs/src/test/java/com/example/credhub/CredHubReactiveSecurityConfiguration.java new file mode 100644 index 0000000..946f119 --- /dev/null +++ b/spring-credhub-docs/src/test/java/com/example/credhub/CredHubReactiveSecurityConfiguration.java @@ -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; + } + +} diff --git a/spring-credhub-docs/src/test/java/com/example/credhub/CredHubSecurityConfiguration.java b/spring-credhub-docs/src/test/java/com/example/credhub/CredHubSecurityConfiguration.java new file mode 100644 index 0000000..b5d3f5f --- /dev/null +++ b/spring-credhub-docs/src/test/java/com/example/credhub/CredHubSecurityConfiguration.java @@ -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; + } + +}