diff --git a/spring-geode-docs/src/docs/asciidoc/cloudfoundry.adoc b/spring-geode-docs/src/docs/asciidoc/cloudfoundry.adoc index 23110b93..30de6cc7 100644 --- a/spring-geode-docs/src/docs/asciidoc/cloudfoundry.adoc +++ b/spring-geode-docs/src/docs/asciidoc/cloudfoundry.adoc @@ -14,17 +14,20 @@ the infrastructure-related, operational concerns so you do not have to. [[cloudfoundry-cloudcache-security-auth-runtime-user-configuration]] === Running Spring Boot applications as a specific user -By default, your Spring Boot application uses a "_cluster_operator_", Role-based user at runtime when your app -is pushed (i.e. deployed) to Pivotal CloudFoundry (PCC) and bound to a Pivotal Cloud Cache (PCC) service instance. +By default, Spring Boot applications run as a "_cluster_operator_" Role-based user in Pivotal CloudFoundry (PCF) +when the app is bound to a Pivotal Cloud Cache (PCC) service instance. -The "_cluster_operator_" has full system privileges (i.e. Authorization) to do whatever that user wishes to on -the PCC service instance. The "_cluster_operator_" has read/write access to all the data, can modify the schema -(e.g. add/destroy Regions, add/remove an Index, change eviction/expiration policies, etc), start and stop servers -in the PCC cluster, and even modify permissions. +A "_cluster_operator_" has full system privileges (i.e. Authorization) to do whatever that user wishes to involving +the PCC service instance. A "_cluster_operator_" has read/write access to all the data, can modify the schema +(e.g. create/destroy Regions, add/remove Indexes, change eviction or expiration policies, etc), start and stop servers +in the PCC cluster, or even modify permissions. -1 of the reasons Spring Boot apps default to running as a "_cluster_operator_" is to allow configuration metadata to be -sent from the client to the server. Enabling configuration metadata to be sent from the client to the server is as -simple as annotating your `@SpringBootApplication` main class with the `@EnableClusterConfiguration` SDG annotation: +.About _cluster-operator_ as the default user +**** +1 of the reasons why Spring Boot apps default to running as a "_cluster_operator_" is to allow configuration metadata to +be sent from the client to the server. Enabling configuration metadata to be sent from the client to the server is a +useful development-time feature and is as simple as annotating your main `@SpringBootApplication` class with +the `@EnableClusterConfiguration` annotation: .Using `@EnableClusterConfiguration` [source,java] @@ -34,15 +37,16 @@ simple as annotating your `@SpringBootApplication` main class with the `@EnableC class SpringBootApacheGeodeClientCacheApplication { ... } ---- -With `@EnableClusterConfiguration`, a client can send Region and OQL Index configuration metadata to the servers in -the PCC cluster. Apache Geode and Pivotal GemFire (also PCC) expects there to be matching Regions by name, on both -the client and the servers in order for clients to send and receive data to and from the cluster. The SDG -`@EnableClusterConfiguration` annotation makes this coordination simple. +With `@EnableClusterConfiguration`, Region and OQL Index configuration metadata defined on the client can be sent to +servers in the PCC cluster. Apache Geode and Pivotal GemFire requires matching Regions by name on both the client +and servers in order for clients to send and receive data to and from the cluster. -For example, if you declare a Region mapping with the `@Region` mapping annotation on 1 of your application entities, -and you are also using the `@EnableEntityDefinedRegions` annotation, then not only will SBDG create the required client -Region, but it will also send the configuration metadata for this Region up to the servers in the cluster to create -the required and matching peer server Region, where the data for your application entities will be managed. +For example, when you declare the Region where an application entity will be persisted using the `@Region` mapping +annotation and additionally declare the `@EnableEntityDefinedRegions` annotation on the main `@SpringBootApplication` +class in conjunction with the `@EnableClusterConfiguration` annotation, then not only will SBDG create the required +client Region, but it will also send the configuration metadata for this Region to the servers in the cluster to create +the matching, required server Region, where the data for your application entity will be managed. +**** However... @@ -50,10 +54,10 @@ However... Not all Spring Boot applications using PCC will need to change the schema, or even modify data. Rather, certain apps may only need read access. Therefore, it is ideal to be able to configure your Spring Boot applications to run with -a different user at runtime other than the auto-configured, "_cluster_operator_", by default. +a different user at runtime other than the auto-configured "_cluster_operator_", by default. A prerequisite for running a Spring Boot application using PCC with a specific user is to create a user with restricted -permissions using Pivotal CloudFoundry AppsManager when provisioning the PCC service instance to which the Spring Boot +permissions using Pivotal CloudFoundry AppsManager while provisioning the PCC service instance to which the Spring Boot application will be bound. Configuration metadata for the PCC service instance might appear as follows: @@ -101,9 +105,9 @@ Configuration metadata for the PCC service instance might appear as follows: } ---- -In the PCC service instance configuration metadata above, we see a "_guest_" user with the "_read-only-user_" Role -available for use. If the "_read-only-user_" Role is properly configured with "read-only" permissions as the name -implies, then we could configure our Spring Boot application to run as "_guest_" with read-only access using: +In the PCC service instance configuration metadata above, we see a "_guest_" user with the "_read-only-user_" Role. +If the "_read-only-user_" Role is properly configured with "read-only" permissions as the name implies, then we could +configure our Spring Boot application to run as "_guest_" with read-only access using: .Configuring a Spring Boot app to run as a specific user [source,properties] @@ -120,15 +124,15 @@ for more details. The `spring.data.gemfire.security.username` property is the same property used by Spring Data for Apache Geode and Pivotal GemFire (SDG) to configure the runtime user of your Spring Data application when connecting to either -a standalone Apache Geode or Pivotal GemFire cluster. +an externally managed Apache Geode or Pivotal GemFire cluster. In this case, SBDG simply uses the configured username to lookup the authentication credentials of the user to set -the username and password required by the Spring Boot, `ClientCache` app to connect to PCC when running in PCF. +the username and password used by the Spring Boot, `ClientCache` app when connecting to PCC while running in PCF. If the username is not valid, then an `IllegalStateException` is thrown. -By using {spring-boot-docs-html}/#boot-features-profiles[Spring Profiles], it would be a simply matter to configure the Spring Boot application to run with -a different user depending on environment. +By using {spring-boot-docs-html}/#boot-features-profiles[Spring Profiles], it would be a simple matter to configure +the Spring Boot application to run with a different user depending on environment. See the Pivotal Cloud Cache documentation on {pivotal-cloudcache-docs}/security.html[Security] for configuring users with assigned roles & permissions. @@ -138,7 +142,7 @@ with assigned roles & permissions. It should be generally understood that _auto-configuration_ for client authentication is only available for managed environments, like Pivotal CloudFoundry. When running in externally managed environments, you must explicitly set -a username and password to authenticate. +a username and password to authenticate, as described <>. To completely override the _auto-configuration_ of client authentication, simply set both a username and password: diff --git a/spring-geode-docs/src/docs/asciidoc/security.adoc b/spring-geode-docs/src/docs/asciidoc/security.adoc index d667765e..c841f2e5 100644 --- a/spring-geode-docs/src/docs/asciidoc/security.adoc +++ b/spring-geode-docs/src/docs/asciidoc/security.adoc @@ -119,17 +119,17 @@ that you setup when you provisioned a PCC service instance in your PCF organizat 2 users with roles "_cluster_operator_" and "_developer_", respectively, to any Spring Boot application bound to the PCC service instance. -By default, SBDG will auto-configure your Spring Boot app to run with the user having the "_cluster_operator_role_". -This ensures that your Spring Boot app has the necessary privileges (i.e. Authorization) to perform all data access -operations on the cluster of PCC servers, including, for example, pushing cluster configuration meta-data for the client +By default, SBDG will auto-configure your Spring Boot app to run with the user having the "_cluster_operator" Role. +This ensures that your Spring Boot app has the necessary permissions (i.e. Authorization) to perform all data access +operations on the servers in the PCC cluster including, for example, pushing configuration metadata from the client to the servers in the PCC cluster. See the section, <<[cloudfoundry-cloudcache-security-auth-runtime-user-configuration,Running Spring Boot applications as a specific user>>, in the <> chapter for additional details on user authentication and authorization. -See the < for more general details. +See the <> titled '_Pivotal CloudFoundry_' for more general details. -See the {pivotal-cloudcache-docs}/index.html#security[Pivotal Cloud Cache documentation] for security details +See the {pivotal-cloudcache-docs}/security.html[Pivotal Cloud Cache documentation] for security details when using PCC and PCF. [[geode-security-ssl]]