Add documentation on running a Spring Boot application in PCF using PCC as a specific, assigned user.
Resolves gh-44.
This commit is contained in:
John Blum
@@ -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-cloudcache-multi-instance-target,above>>.
|
||||
|
||||
|
||||
[[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
|
||||
|
||||
|
||||
@@ -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 <<cloudfoundry,Pivotal Cloud Foundry>> chapter for additional details on user authentication and authorization.
|
||||
|
||||
See the <<cloudfoundry,chapter on 'Pivotal CloudFoundry'> 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.
|
||||
|
||||
Reference in New Issue
Block a user