Operational Recipes

Below is a recommended local workspace setup for an operations team member. This setup supports management of multiple security artifacts for different environments. We’ll be using and referencing this setup in the following recipes.

For organizational purposes, we recommend creating a separate working directory for each environment (e.g. Dev,QA, and Production etc…​) to store and generate your security artifacts

The below instructions will outline the steps necessary to prepare each of these working directories to generate and manage the security artifacts for that environment.

In order to generate the correct properties and artifacts that apply to your implementation, you will need to download the correct Security Tool version that is applicable to the starter base and release train versions defined for your project. To find this version you can execute the following Maven Command in the manifest directory of your main Broadleaf project.

Keep note of this version as you’ll need to use this to download the correct tool version.

To download the tool, create a separate working directory for the environment you want to generate security artifacts for (e.g. my-dev.com) and take note of the path to this directory.

Next, cd into the manifest directory of your main Broadleaf project and run the following Maven dependency copy command. Make sure to replace the [replace_with_correct_version] and the [/my/local/path/to/my-dev.com] parts with the appropriate values based on what you noted from the steps above.

Next, you’ll want to copy over the current Manifest JAR built for your project to your environment working directory. You can find this artifact if you cd into your manifest directory of your primary Broadleaf project. Next cd into the target directory. Note: If you do not have a target directory, you can always execute a new build by running ./mvnw clean install which should generate a new target directory with several build artifacts inside. Inside this target directory, you should find a manifest JAR (e.g. microservice-flexpackage-manifest-1.0.0-SNAPSHOT.jar). Copy this file into your environment’s working directory. For example:

You should now have both a security-tool.jar and a manifest.jar in your environment’s working directory (e.g. /my/local/path/to/my-dev.com). With this in place, you are now ready to generate new security artifacts by running the following Java command (replacing the name of the security-tool.jar with the actual name of the JAR file in your directory):

With that command executed, you should now see new security and config folders generated in your current environment working directory.

While this is optional, it is highly recommended that you now store these generated artifacts in the security folder in a shared secure location (i.e. NOT in a source control system) preferably a secrets manager or vault. This allows you (or another operations team member with the appropriate access) to create a shared "source of truth" that correspond with the latest versions of these artifacts - this will help if and when you need to make changes and updates to the properties over time.

It is recommended that you create at least 2 repositories, one for secure encrypted properties and one for general non-secure properties. These repositories can then be configured with the appropriate team access according to your security posture. In our examples and reference, we’ve called the the Git repos, configserver-[ENV]-secure and configserver-[ENV]-insecure.

You will also want to create a READONLY user that has access to pull the properties from these corresponding repos. Take note of the credentials needed for this user as it will be set and injected into the configuration for Broadleaf’s Spring Cloud Config service.

You can pass in one or more backing Git datastore configurations for your properties using ENV properties. If you are using the helm charts that are generated for you using the helm:generate plugin, you will notice that you can configure these properties using the following helm properties (i.e. secrets.environmentRepositoryCreds.keyValuePairs.*) that are overridable in the values.yaml file.

Your overrides, might look something like this:

Many source code repositories allow notification of changes to a repository based on a configured webhook. You can setup webhooks following the directions identified by your code repository provider. For example, GitHub uses a POST to any configured webhooks with a JSON body containing a list of commits. Once the webhook is configured, Spring Cloud Config natively handles the processing and consumption of those events. More details on this can be found on Spring’s official documentation.

The main mechanic for managing secure and encrypted properties within a Broadleaf ecosystem leveraging a Config Server is to manage these properties using the generated credentials-report.env which you will find in the generated security folder for your environment.

If you are adding/updating an existing credentials-report.env that is already applied to an environment, you will need to pull down the original "source" (presumably stored in your Secure Vault/Secrets Manager) in order to update it. You can then add arbitrary properties to this report using a special syntax which will be described below.

Suppose you have a new secure property that you wish to be encrypted and stored in the Config Server (e.g. MY_SECRET_PROPERTY=1234). In order to create the appropriate Spring Application Context property files with the encrypted values (to load into your config server), for example:

You can run the same security-tool.jar as mentioned in the recipe "Generate New Security Artifacts" against the updated credentials-report.env with the new property added.

The key difference is that (since Broadleaf does not have any knowledge of what this property is) you must define this property in your credentials-report.env file with a special syntax that matches the following form:

For example, let’s say the MY_SECRET_PROPERTY that I am trying to add is only applicable to the Auth microservice, in that case, I could add the following new plain-text property in my credentials-report.env

After modifying the security/credentials-report.env with the new secret using the special syntax, run in your current working environments working directory:

After running the encrypt command, you should now have newly encrypted config properties in your config/secure directory for that environment. If you have this pointed to a backing Git repo, you can now check in these changes directly to source control.

To determine the "Profile Keys" that you can use in your property syntax, you can download the component-profiles-map.yml which will give you a file that contains the different profiles the security tool uses when creating the appropriate encrypted configuration files.

Liquibase changelogs are applied once and marked as "run" in a databasechangelog table. This is typically done during initial installation when running the data module (or via the job-data helm chart in kubernetes) for the first time. The initializr required changelogs contain pre-conditions "Mark Ran as Failed" if an existing record already exists in the datastore.

What does this mean? From an operational perspective, if (as an example) you wish to change the master admin password and bcrypt value and you’ve already applied the changelog with a previously set password, then changing credentials in the credentials report and re-generating encrypted values for the config server will have NO IMPACT on the data since that record has already been inserted and applied.

Options to change a "seed data" record if already applied:

Once logged in, you will see the configuration data being served from the Config Server. These are the same property values that all connected Spring Boot applications retrieve at runtime.

To ensure consistency between the configuration server and the database:

Matching values confirm that the Config Server is correctly supplying the expected configuration.

In typical cloud deployments, the Broadleaf gateways are not directly at the 'boundary of trust'. Instead, a cloud ingress configuration (ex: Ingress-Nginx, Azure Application Gateway, Google Cloud Application Load Balancer) sits in front of the Broadleaf gateways as the first entrypoint for untrusted external requests. The ingress does its own processing/setting of X-Forwarded-For/Forwarded headers before forwarding the request to the Broadleaf gateways, which do the same thing before passing it further down to the backend services.

The expectation is generally like so:

In this scenario, the Broadleaf gateways are not directly exposed to the internet, and thus are only expecting requests to come from the trusted ingress. The burden of pruning untrusted headers is on the cloud ingress, and therefore the Broadleaf gateways do not need to be concerned with where the headers came from before deciding whether to honor them.

On the other hand, if the Broadleaf gateways are directly exposed to external untrusted traffic instead of being behind an ingress, then the burden of pruning untrusted headers does fall upon them.

This applies to both the admin and commerce gateways.