- v1.0.0-latest-prod
|
Note
|
This guide is only applicable to Initializr-based projects |
With an Initializr-based project, Broadleaf generates an initial starting point that produces sensible and secure defaults allowing you the implementor to easily dial up the security needs if needed or make a conscious choice to dial down certain security measures when it seems appropriate for your needs.
Running the flex:generate command will create a security folder that contains important
security related files and information needed for your installation that will holistically
tie the system together. Note that the contents of these generated files are cryptographically
unique upon generation.
This guide will outline the different security pieces and configurations that are generated and defaulted for you.
In your security folder you will notice a credentials-report.env. This is a very
important file as it contains all the unencrypted plain-text credentials that were generated
for your project. It contains credentials for your global admin user, your local database,
several OAuth client credential keys and hashes, and finally credentials for
connecting to supporting services like Zookeeper, Solr, and Kafka.
As with all things in the security folder, this report should NOT be checked into source
control. From an operational perspective, these values should be injected either
directly as ENV properties into the relevant service pods of your Kubernetes cluster or ENCRYPTED
and managed as part of a Spring Cloud Config server.
Below are some notable default credentials that are generated and where you might find them:
The initial local datasource password is generated as part of the flex:generate plugin execution
and is referenced in the generated docker-compose.yml file. The generated plaintext values can be
found in your credentials-report.env
The initial master admin user passwords are generated as part of the flex:generate plugin
execution. the BCrypted values are set as part of the initial installation (typically when
running the data module for the first time). These values can be changed using the
SPRING_LIQUIBASE_PARAMETERS_* secure application variables in the configuration of the data
module. The generated plaintext values can be found in your credentials-report.env
Broadleaf comes configured with several OAuth Clients for service-to-service communication.
These auth clients are configured in the Auth microservice. The BCrypted client-secret hash
can be passed in via secure application configuration properties. The generated plaintext values
can be found in your credentials-report.env
Broadleaf’s Auth service signs JWT tokens allowing consuming services to verify that they
have been issued by the Broadleaf Auth service and have not been manipulated by a third-party.
These consist of both a public and private key pair. In addition to this, Initializr-based
projects also support Key rotation which allows additive operational support allowing
you to keep previous keys (if desired) to cover previously issued tokens. In conjunction
with the Config service, this allows for zero-downtime scenarios when you need to rotate these keys
in a production environment. The generated plaintext values can be found in your credentials-report.env
Below are a list of additional public/private keys and encryption keys that are also generated
as part of the flex:generate process. The generated plaintext values can be found in your credentials-report.env
Sandbox Preview Public/Private Keys
Transfer Cart Public/Private Keys
Auth Service Third Party IDP Encryption Key
Given the reference architecture, as a request makes it to either gateway (e.g. the commercegateway
or the admingateway) it then gets routed to the appropriate microservice which may make one or more inter-service calls within the cluster. These calls within the cluster are made with SSL enabled
for all communication using default self-signed certs.
|
Note
|
prior to Initializr, these self-signed certs were generated as part of the build process
using the keytool-maven-plugin and was built along the deployable artifact.
This is no longer the case.
|
With Initializr, you will notice that unique self-signed certs are now generated as part of the
flex-generate process and found in your security folder:
https-keystore.jks
https-truststore.jks
Operationally, these files should be mounted externally and accessible to your deployed Kubernetes pods in your cluster.
|
Note
|
currently https-truststore.jks is only used for flex package ←→ to config server communication only
|
Securing Kafka is a good example of where you can dial up or dial down security configuration and set up based on your needs and business goals. With an Initializr-based project, Broadleaf generates a Kafka setup that focuses on the following security defaults:
Securing connections to the brokers using the SASL_SSL: PLAIN security strategy
Utilizing 2 default Super Users (currently no ACLs in place): kafkabroker and client
An externally mounted JaaS file that holds credential information for the default super users as well as connectivity credentials in order for the brokers to connect to Zookeeper
Below is a snippet of a local docker-compose.yaml file that showcases the applicable kafka
security configuration that is used to bootstrap the Kafka service.
With an Initializr-based project, Broadleaf generates a Solr setup that focuses on the following security defaults:
Securing connections to Solr using the BasicAuthPlugin
Utilizing 4 default Users: admin, indexer, searcher, and k8s
An externally mounted solr-security.json containing encrypted credentials for the default users
Securing connectivity to Zookeeper via SOLR_ARGS ENV vars
-DzkDigestReadonlyUsername=readonly-user -DzkDigestReadonlyPassword=$securityReadOnlyZkPassword
Below is a snippet of the SOLR configuration files and the security configuration applicable to the setup:
With an Initializr-based project, Broadleaf generates a Zookeeper setup that focuses on the following security defaults:
Securing connections to ZK using the SASLAuthenticationProvider
Utilizing 3 default Users: super, kafka, and readonly-user (used by solr)
An externally mounted JaaS file (zk-jaas.conf) containing credentials for the default users
Below is a snippet of a local docker-compose.yaml file that showcases the applicable ZK
security configuration that is used to bootstrap the Zookeeper service.
Given that the supporting services are secured as mentioned above, all the relevant flex package commerce services must be configured appropriately to connect to them. In particular, the following defaults are applied:
To connect to Zookeeper and Kafka, the following JaaS file must be externally mounted:
zk-kafka-client-jaas.conf. This file contains credentials in order to effectively communicate with
ZK and the message broker. The following are applicable application properties:
spring:
cloud:
stream:
kafka:
binder:
configuration:
ssl:
trustore:
password: '{cipher}...'
security:
protocol: SASL_SSL
sasl:
mechanism: PLAIN
broadleaf:
default:
java:
security:
auth:
login:
config: /var/keys/zk-kafka-client-jaas.confTo connect to Zookeeper and Solr, the Broadleaf Search and Index Services (typically part of the processing flex package) must specify encrypted environment properties (if using the Config Server) or ENV variables containing
credentials for connecting to these supporting services. The following are applicable application properties:
broadleaf:
search:
solr:
server:
indexer:
password: '{cipher}...'
searcher:
password: '{cipher}...'
zkAcl:
password: '{cipher}...'
It is highly recommended that you include Broadleaf’s Spring Cloud Config Server into your overall ecosystem. With that said, it is important that any secure or sensitive properties that are stored in the config server backend (e.g. a git repository) is properly encrypted.
The initializr security module produces a file-encryption.jks file that can be externally
mounted into your Config Server instance which will properly encrypt/decrypt the properties
managed by the config service.
With this in place, you will be able to see that properties in the config/secure directory
will include encrypted properties of the format:
broadleaf:
datasource:
password: '{cipher}{key:version_1}...'Below is an image showing which application security module configuration is applicable to this process.
