diff --git a/spring-geode-docs/src/docs/asciidoc/cloudfoundry.adoc b/spring-geode-docs/src/docs/asciidoc/cloudfoundry.adoc index 24f3798c..23110b93 100644 --- a/spring-geode-docs/src/docs/asciidoc/cloudfoundry.adoc +++ b/spring-geode-docs/src/docs/asciidoc/cloudfoundry.adoc @@ -2,17 +2,159 @@ == Pivotal CloudFoundry :images-dir: ./images -In most cases, when you deploy (i.e. "_push_") your Spring Boot applications to Pivotal CloudFoundry (PCF) +In most cases, when you "_push_" (i.e. "_deploy_") your Spring Boot applications to Pivotal CloudFoundry (PCF) you will bind your app to 1 or more instances of the Pivotal Cloud Cache (PCC) service. In a nutshell, {pivotal-cloudcache-website}[Pivotal Cloud Cache] is a managed version of {pivotal-gemfire-website}[Pivotal GemFire] running in {pivotal-cloudfoundry-website}[Pivotal CloudFoundry]. -When running in or across cloud environments (e.g. PWS, AWS, Azure or GCP), PCC with PCF offers several advantages +When running in or across cloud environments (e.g. AWS, Azure, GCP or PWS), PCC with PCF offers several advantages over trying to run and manage your own standalone Apache Geode or Pivotal GemFir clusters. It handles many of 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 -[[cloudfoundry-cloudcache-multi-instance-target]] +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. + +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. + +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: + +.Using `@EnableClusterConfiguration` +[source,java] +---- +@SpringBootApplication +@EnableClusterConfiguration(useHttp = true) +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. + +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. + +However... + +> With great power comes great responsibility. - Uncle Ben + +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 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 +application will be bound. + +Configuration metadata for the PCC service instance might appear as follows: + +.Pivotal Cloud Cache configuration metadata +[source,json] +---- +{ + "p-cloudcache":[{ + "credentials": { + "distributed_system_id": "0", + "locators": [ "localhost[55221]" ], + "urls": { + "gfsh": "https://cloudcache-12345.services.cf.pws.com/gemfire/v1", + "pulse": "https://cloudcache-12345.services.cf.pws.com/pulse" + }, + "users": [{ + "password": "*****", + "roles": [ "cluster_operator" ], + "username": "cluster_operator_user" + }, { + "password": "*****", + "roles": [ "developer" ], + "username": "developer_user" + }, + }, { + "password": "*****", + "roles": [ "read-only-user" ], + "username": "guest" + }], + "wan": { + "sender_credentials": { + "active": { + "password": "*****", + "username": "gateway-sender-user" + } + } + } + }, + ... + "name": "jblum-pcc", + "plan": "small", + "tags": [ "gemfire", "cloudcache", "database", "pivotal" ] + }] +} +---- + +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: + +.Configuring a Spring Boot app to run as a specific user +[source,properties] +---- +# Spring Boot application.properties for PCF when using PCC + +spring.data.gemfire.security.username=guest +---- + +TIP: The `spring.data.gemfire.security.username` property corresponds directly to the SDG `@EnableSecurity` annotation, +`securityUsername` attribute. +See the {spring-data-geode-javadoc}/org/springframework/data/gemfire/config/annotation/EnableSecurity.html#securityUsername--[Javadoc] +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. + +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. + +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. + +See the Pivotal Cloud Cache documentation on {pivotal-cloudcache-docs}/security.html[Security] for configuring users +with assigned roles & permissions. + +[[cloudfoundry-cloudcache-security-auth-autoconfiguration-override]] +==== Overriding Authentication Auto-configuration + +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. + +To completely override the _auto-configuration_ of client authentication, simply set both a username and password: + +.Overriding Security Authentication Auto-configuration with explicit username and password +[source,txt] +---- +# Spring Boot application.properties + +spring.data.gemfire.security.username=MyUser +spring.data.gemfire.security.password=MyPassword +---- + +In this case, SBDG's _auto-configuration_ for authentication is effectively disabled and security credentials +will not be extracted from the environment. + +[[cloudfoundry-cloudcache-serviceinstance-targeting]] === Targeting Specific Pivotal Cloud Cache Service Instances It is possible to provision multiple instances of the Pivotal Cloud Cache service in your Pivotal CloudFoundry @@ -27,10 +169,11 @@ multiple instances and want to target a specific PCC service instance to use. To do so, declare the following SBDG property in Spring Boot `application.properties`: -.Spring Boot application.properties targeting a PCC service instance +.Spring Boot application.properties targeting a specific PCC service instance by name [source,properties] ---- # Spring Boot application.properties + spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name=pccServiceInstanceTwo ---- @@ -45,8 +188,7 @@ then SBDG will auto-configure the first PCC service instance it finds by name, a If you did not set the property and no PCC service instance is found, then SBDG will log a warning. - -[[cloudfoundry-cloudcache-multi-instance-using]] +[[cloudfoundry-cloudcache-multiinstance-using]] === Using Multiple Pivotal Cloud Cache Service Instances If you want to use multiple PCC service instances with your Spring Boot application, then you need to configure @@ -117,7 +259,6 @@ and use a single PCC service instance. This may be a targeted PCC service insta `spring.boot.data.gemfire.cloud.cloudfoundry.service.cloudcache.name` property as discussed <>. - [[cloudfoundry-geode]] === Hybrid Pivotal CloudFoundry & Apache Geode Spring Boot Applications @@ -539,7 +680,7 @@ in whatever context your application lands, even if it changes later. If you fo that goal will be realized. [[cloudfoundry-geode-app-run]] -==== Running the Spring Boot app +==== Running the Spring Boot application All that is left to do now is run the app. @@ -607,7 +748,6 @@ Rows : 1 1235432BMF342 | The Torment of Others ---- - [[cloudfoundry-geode-summary]] === Summary diff --git a/spring-geode-docs/src/docs/asciidoc/security.adoc b/spring-geode-docs/src/docs/asciidoc/security.adoc index 377804ed..d667765e 100644 --- a/spring-geode-docs/src/docs/asciidoc/security.adoc +++ b/spring-geode-docs/src/docs/asciidoc/security.adoc @@ -4,27 +4,33 @@ This sections covers Security configuration for Apache Geode & Pivotal GemFire, which includes both Authentication & Authorization (collectively, Auth) as well as Transport Layer Security (TLS) using SSL. +NOTE: Securing Data at Rest is not generally supported by either Apache Geode, Pivotal GemFire +or Pivotal Cloud Cache (PCC) yet. + [[geode-security-auth]] === Authentication & Authorization -Apache Geode & Pivotal GemFire employ Username/Password-based {apache-geode-docs}/managing/security/authentication_overview.html[Authentication] +Apache Geode & Pivotal GemFire employs Username and Password based {apache-geode-docs}/managing/security/authentication_overview.html[Authentication] along with Role-based {apache-geode-docs}/managing/security/authorization_overview.html[Authorization] to secure your client to server data exchanges and operations. Spring Data for Apache Geode & Pivotal GemFire (SDG) provides {spring-data-geode-docs-html}/#bootstrap-annotation-config-security[first-class support] for Apache Geode & Pivotal GemFire's Security framework, which is based on the {apache-geode-javadoc}/org/apache/geode/security/SecurityManager.html[SecurityManager] interface. -Additionally, Apache Geode's Security framework is integrated with Apache Shiro, making the security for servers -an even easier and more familiar task. +Additionally, Apache Geode's Security framework is integrated with https://shiro.apache.org/[Apache Shiro], +making the security for servers an even easier and more familiar task. -When you apply Spring Boot for Apache Geode & Pivotal GemFire (SBDG), which builds on the bits provided in SDG, -it makes short work of enabling Auth in both your clients and servers. +NOTE: Eventually, support and integration with https://spring.io/projects/spring-security[Spring Security] +will be provided by SBDG as well. + +When you use Spring Boot for Apache Geode & Pivotal GemFire (SBDG), which builds on the bits provided in Spring Data +for Apache Geode & Pivotal GemFire (SDG), it makes short work of enabling Auth in both your clients and servers. [[geode-security-auth-servers]] ==== Auth for Servers -The easiest and most standard way to enable Auth in your servers is to simply define 1 or more Apache Shiro -https://shiro.apache.org/realm.html[Realms] as beans in the Spring `ApplicationContext`. +The easiest and most standard way to enable Auth in the servers of your cluster is to simply define 1 or more +Apache Shiro https://shiro.apache.org/realm.html[Realms] as beans in the Spring `ApplicationContext`. For example: @@ -43,15 +49,16 @@ class ApacheGeodeSecurityConfiguration { } ---- -When an Apache Shiro Realm (e.g. `DefaultLdapRealm`) is declared and registered in the Spring `ApplicationContext`, -Spring Boot will automatically detect this Realm bean (or Realm beans if more than 1) and the Apache Geode -& Pivotal GemFire servers in the cluster will automatically be configured with Authentication/Authorization enabled. +When an Apache Shiro Realm (e.g. `DefaultLdapRealm`) is declared and registered in the Spring `ApplicationContext` +as a Spring bean, Spring Boot will automatically detect this `Realm` bean (or `Realm` beans if more than 1 is configured) +and the Apache Geode & Pivotal GemFire servers in the cluster will automatically be configured with +Authentication and Authorization enabled. Alternatively, you can provide an custom, application-specific implementation of Apache Geode & Pivotal GemFire's {apache-geode-javadoc}/org/apache/geode/security/SecurityManager.html[SecurityManager] interface, declared and registered as a bean in the Spring `ApplicationContext`: -.Declaring a custom Apache Geode/Pivotal GemFire `SecurityManager` +.Declaring a custom Apache Geode or Pivotal GemFire `SecurityManager` [source,java] ---- @Configuration @@ -67,10 +74,10 @@ class ApacheGeodeSecurityConfiguration { ---- Spring Boot will discover your custom, application-specific `SecurityManager` implementation and configure -the Apache Geode & Pivotal GemFire servers in the cluster with Authentication/Authorization enabled. +the servers in the Apache Geode or Pivotal GemFire cluster with Authentication and Authorization enabled. TIP: The Spring team recommends that you use Apache Shiro to manage the Authentication & Authorization of your -Apache Geode & Pivotal GemFire servers over implementing Apache Geode or Pivotal GemFire's `SecurityManager` interface. +Apache Geode or Pivotal GemFire servers over implementing Apache Geode or Pivotal GemFire's `SecurityManager` interface. [[geode-security-auth-clients]] ==== Auth for Clients @@ -85,14 +92,15 @@ a managed environment, like Pivotal CloudFoundry (PCF). [[geode-security-auth-clients-non-managed]] ===== Non-Managed Auth for Clients -To enable Auth for clients connecting to a secure Apache Geode or Pivotal GemFire cluster, you simply need to set +To enable Auth for clients connecting to a secure Apache Geode or Pivotal GemFire cluster, you simply only need to set a username and password in your Spring Boot `application.properties` file: [source,txt] ---- # Spring Boot client application.properties + spring.data.gemfire.security.username = jdoe -spring.data.gemfire.security.password = p@55w0rd! +spring.data.gemfire.security.password = p@55w0rd ---- Spring Boot for Apache Geode & Pivotal GemFire (SBDG) will handle the rest. @@ -105,12 +113,24 @@ is even easier. You do not need to do anything! -When your Spring Boot application using PCC is pushed (i.e. deployed) to PCF, Spring Boot for Apache Geode & Pivotal GemFire -(SBDG) is smart enough to extract the necessary Auth credentials from the environment you setup when you provisioned -a PCC service instance in your PCF organization & space. PCC automatically assigns 2 users with roles -"_cluster_operator_" and "_developer_", respectively, to any Spring Boot application bound to the PCC service instance. +When your Spring Boot application uses SBDG and is bound to PCC, then when you push (i.e. deploy) your app to PCF, +Spring Boot for Apache Geode & Pivotal GemFire (SBDG) will extract the required Auth credentials from the environment +that you setup when you provisioned a PCC service instance in your PCF organization & space. PCC automatically assigns +2 users with roles "_cluster_operator_" and "_developer_", respectively, to any Spring Boot application bound to the PCC +service instance. -See the {pivotal-cloudcache-docs}/index.html#security[Pivotal Cloud Cache documentation] for more details. +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 +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 {pivotal-cloudcache-docs}/index.html#security[Pivotal Cloud Cache documentation] for security details +when using PCC and PCF. [[geode-security-ssl]] === Transport Layer Security using SSL @@ -122,11 +142,11 @@ between your clients and servers, nor send sensitive data over those same connec Therefore, both Apache Geode & Pivotal GemFire support SSL between clients & servers, JMX clients (e.g. _Gfsh_) and the _Manager_, HTTP clients when using the Developer REST API or _Pulse_, between peers in the cluster, -and when using the WAN Gateway. +and when using the WAN Gateway to connect multiple sites (i.e. clusters). Spring Data for Apache Geode & Pivotal GemFire (SDG) provides https://docs.spring.io/spring-data/geode/docs/current/reference/html/#bootstrap-annotation-config-ssl[first-class support] -for enabling and configuring SSL as well. Still, Spring Boot makes it even easier to configure and enable SSL, +for configuring and enabling SSL as well. Still, Spring Boot makes it even easier to configure and enable SSL, especially during development. Apache Geode & Pivotal GemFire require certain properties to be configured, which translate to the appropriate @@ -143,7 +163,7 @@ Simply create a `trusted.keystore`, JKS-based `KeyStore` file and place it in 1 3. In your user home directory (as defined by the `user.home` Java System property). When this file is named `trusted.keystore` and is placed in 1 of these 3 well-known locations, Spring Boot -for Apache Geode & Pivotal GemFire (SBDG) can automatically configure your client to use SSL Socket connections. +for Apache Geode & Pivotal GemFire (SBDG) will automatically configure your client to use SSL Socket connections. If you are using Spring Boot to configure and bootstrap an Apache Geode or Pivotal GemFire server: @@ -157,19 +177,19 @@ class SpringBootApacheGeodeCacheServerApplication { } ---- -Then, Spring Boot will apply the same procedure to enable SSL on the servers as well. +Then, Spring Boot will apply the same procedure to enable SSL on the servers, between peers, as well. -TIP: During development it is convenient *not* to set a `trusted.keystore` password when accessing the keys in the file. -However, it is highly recommended that you secure the `trusted.keystore` file when deploying your application to +TIP: During development it is convenient *not* to set a `trusted.keystore` password when accessing the keys in the JKS +file. However, it is highly recommended that you secure the `trusted.keystore` file when deploying your application to a production environment. -If your `trusted.keystore` file is secured with a password, you will need to additionally specify -the following property: +If your `trusted.keystore` file is secured with a password, you will need to additionally specify the following property: .Accessing a secure `trusted.keystore` [source,txt] ---- # Spring Boot application.properties + spring.data.gemfire.security.ssl.keystore.password = p@55w0rd! ---- @@ -180,6 +200,7 @@ in 1 of the default, well-known locations searched by Spring Boot: [source,txt] ---- # Spring Boot application.properties + spring.data.gemfire.security.ssl.keystore = /absolute/file/system/path/to/keystore.jks spring.data.gemfire.security.ssl.keystore.password = keystorePassword spring.data.gemfire.security.ssl.truststore = /absolute/file/system/path/to/truststore.jks @@ -192,8 +213,9 @@ annotation for all the configuration attributes and the corresponding properties [[geode-security-encryption]] === Securing Data at Rest -Currently, neither Apache Geode nor Pivotal GemFire along with Spring Boot/Spring Data for Apache Geode/Pivotal GemFire -offer any support for securing your data while at rest (e.g. when your data has been overflowed or persisted to disk). +Currently, neither Apache Geode nor Pivotal GemFire along with Spring Boot or Spring Data for Apache Geode +and Pivotal GemFire offer any support for securing your data while at rest (e.g. when your data has been overflowed +or persisted to disk). To secure data at rest when using Apache Geode or Pivotal GemFire, with or without Spring, you must employ 3rd party solutions like disk encryption, which is usually highly contextual and technology specific.