Environment Files

During an implementation, components are created or modified to contain all of the configuration information for the product. This greatly speeds up the installation and configuration processes needed during an implementation. It also ensures configurations are not missed between development, QA, test, and production environments.

For example, a target system will have an address different in the development environment than the one in production, even if they essentially represent the same integration. Without environment files, we would need to create separate data components for the same target in each environment, to account for these configuration discrepancies. This would make component sets challenging to keep track of, and any common configuration changes made in one environment’s component set would then need to be propagated to all other environment component sets. Tracking configuration changes that need to be applied to individual or all environment component sets becomes difficult to manage and would involve complicated change control procedures.

Environment files provide a solution to install components with the environment-specific configuration values (like target addresses, user class group membership criteria, extdb values, and so on). The specific configuration values applied depend on the environment file (development, QA, test, UAT, production) selected through the manage_components.py command before installing the components.

When an implementor determines that configuration settings must be specified during product installation, they first determine if a component containing those configuration settings exists within the <instance>/component/Default components. As a general rule, if a component does not exist, it is exported as a data component and used in the <instance>/component/Custom/ directory. If the component does exist in /Default/ components, it can be overwritten in the environment file(s) or via creating a "Custom" version of the "Default" component.

For /Default/Functional/ components, use the following guidelines to determine whether to customize the component or use an environment file::

It is possible to create the entire instance configuration directly in an environment file, however, for readability and centralization purposes, environment files use templates for component overrides, variables, and other tricks. This allows implementors to change some data, structure or values in one place and apply them elsewhere.

To create a new environment file:

A good starting point for adding content to the new, currently empty, abc-dev.json environment file is to reference the default.json sample file from the <instance>\component\Default\Scenario\hid_env_default directory and copy/paste needed portions from that sample into your abc-dev.json environment file. If you decide to use the full contents of the default.json sample as your new environment file, it is advised that you make a copy of the default.json sample and rename it to the desired environment name. That way, the original default.json sample remains for future reference.

Bravura Security Fabric default installation configuration captured in components is overridden by declaring entries in the environment’s .json file.

The base of writing an environment file should be a dictionary with three keys: Scenario, Functional, and Data, so the first thing added to an empty environment file is:

{
	"Scenario": {},
	"Functional": {},
	"Data": {}
}

This structure defines three keys with empty dictionaries corresponding to the three product component types.

Keys not being used can be omitted, but all components can be categorized into these three keys, so it is recommended to leave them in the file if future configurations are added.

From here, the component to be overridden needs to be determined, and the ConfigData entries for that component defined.

{
	"Scenario": {},
	"Functional": {},
	"Data": {
		"hid_target_ad": {
		}
	}
}

<filename>files/ad.json</filename>

<filename>files\ad.json</filename>

{
	"Scenario": {},
	"Functional": {},
	"Data": {
		"hid_target_ad": {
			"ad.json": {}
		}
	}
}

"Fields": {
	"address": "{server=demo.local;listNestedGrps=true}",
	"adminclaimhide": true,
	"adminresethide": false,
	"adminunlockhide": false,
	"agenttime": 300,
	...
}

{
	"Scenario": {},
	"Functional": {},
	"Data": {
		"hid_target_ad": {
			"ad.json": {
				"Fields": {
					"agenttime": 600
				}
			}
		}
	}
}

{"+[0]":{1,2,3}}

{"-[1]": {}}

{
"Scenario": {
  "im_corp_loaddb": {
    "data\\global_configuration.csv": {
      "[*]": {
        "value": "@shortID,mail"
      }
    }
  }
},
"Functional": {},
"Data": {}
}

{
"Scenario": {
  "pam_vault_management": {
    "data\\policy_attrval_validation.csv": { 
      "[0]": { 
        "set_visible": "True"
      } 
    }, 
    "data\\policy_attrval_calculation.csv": { 
      "[1]": { 
        "SkipRemaining": "Stage" 
      }, 
      "[2]": { 
        "SkipRemaining": "All" 
      } 
    }
  }
},
"Functional": {},
"Data": {}
}

Environments are managed through the manage_components.py program located in your instance’s \scripts directory. To use the manage_components program:

manage_components.py env load <environment filename>

manage_components.py env load <environment filename> --force

In this use case, a product implementer for ABC company has set up two product server environments, one for development and one for production. Each environment has a different Active Directory (AD) target address.

The following instructions will walk you through the steps required to create and configure the environment files for both the development (dev) and production (prod) environments. When the environment files are loaded into their respective environments, they will install the component to create the AD target and input the correct address for their environment specific AD system within the target configuration.

Environment details

The Active Directory (AD) target address for each environment is:

Creating the dev and prod environment files

The Data.hid_target_ad component provides a base AD target with a sample targeting address. The Data.hid_target_ad component is called upon and installed as a dependency to many other scenario and functional components.

The sample placeholder AD target address that the Data.hid_target_ad component inputs is server=demo.local;listNestedGrps=true. We know the addresses we want the component to set when installed for both the dev and prod environments, so we need to write the files dictating those addresses. We start by creating two environment files, one for dev and one for prod.

To create the environment files:

Identify the component that you want to add the override for

To be able to override configuration data provided by a component, the component you need to override must be identified first. For IDMConfig changes there is no direct way to tell which component is responsible for the configuration information, so there is no definitive way to figure this out. It requires using intuition to guess and then confirm you are correct by searching through the component files. Here are some tips to help identify the component you need to override.

To identify the component:

Using the pointers noted above, it can be deduced that for overriding the AD target addresses, you should be looking at Data components.

Write the override in the environment files

We have identified the component and field we need to provide an override for and will now specify the override in our respective environments, starting with abc-dev.json.

A good starting point for your environment file is to add three keys, one for each component directory (Data, Functional, Scenario) to help visualize how the overrides apply according to the component's directory. This helps when adding many overrides to environment files since it will keep them organized by component type.

To start the dev environment file:

Load the dev environment

The environment files have been successfully written. In order to apply the configuration overrides from the environment file to the product, the environment file needs to be loaded. To do this for the dev environment:

Install the Data.hid_target_ad component

It is important to note that you can install the data component individually or as part of the Scenario or Functional component that has it listed as a dependency. Either way, the data component will be installed with the environment file overrides. In this case we will install the data component directly.

For this use case, a product implementer for XYZ company has set up two product server environments, one for development and one for production. Each environment has different requirements for the method emails are sent, the amount of failed login attempts permitted before user lockout is triggered and the length of the PIN required for multi-factor authentication. These configuration requirements differ from the defaults configured by components.

This configuration example shows how to create dev and prod environment files to capture entry differences within the ExtDB tables for authentication chains and email behavior. Then, it demonstrates how to load the development environment file during an installation on the development environment.

The environment configuration requirements are:

The following steps need to be completed:

Requirements

This use case assumes that:

Click below to view a demonstration.

Identify the component that you want to add the override for

A test instance has been setup with a variety of components installed in order to identify the component that configuration changes need to be made to.

Identifying the component for an External data store override is much easier than identifying one for idmconfig changes (in most cases). If you already have an existing instance, you can generally determine which component provides specific rows to a table by looking at the ComponentOwnerFQN field that is included in all external data store tables.

To identify the component:

Now that we have identified the component to override, the specific component file to override also needs to be determined. For data provided to ExtDB tables, this generally comes from .csv files.

Review default configuration settings for wfemail component

To determine which specific file and fields we need to provide overrides for in the dev environment file:

Create the dev environment file

To create the dev environment file, if it does not already exist:

Override the appropriate CSV rows in the environment file

To write the dev environment file:

Create the prod environment file

Create the prod environment file if it does not already exist:

Override the appropriate CSV rows in the environment file

Following similar steps and logic to the dev environment file, the xyz-prod.json file is written to include an override that ensures email in the prod environment is set to SMTP only and not to file. This means the WriteFile field from the events.csv must be overridden to equal FALSE.

{
	"Scenario": {},
	"Functional": {
		"hid_policy_wfemail": {
			"data\\events.csv": {
				"[0]": {
					"WriteFile": "FALSE"
				}
			}
		}
	},
	"Data": {}
}

Load the dev environment file

This example assumes the development server environment has Bravura Security Fabric installed on the system without the installation of the Functional.hid_policy_wfemail component.

Install Functional.hid_policy_wfemail component

To install the Functional_hid_policy_wfemail component:

Adding multiple pieces of configuration to an environment file

Since environment files are just .json files, adding more configuration is as simple as adding a comma, and defining another item to override. To display this, we will extend our xyz-dev.json to override the LENGTH and TRIES configurable values provided by the Scenario.hid_authchain_emailpin component to GlobalConfiguration to make the email PIN scenario easier to use in development environments.

For reference, the manifest.xml file for the Scenario.hid_authchain_emailpin component has GlobalConfiguration data provided by the \data\ initial_data.csv file. The default values in the \data\ initial_data.csv file consist of:

In this example, an override is added to the xyz-dev.json file so that:

Writing the override into the existing xyz-dev.json file appears as:

{
	"Scenario": {
		"hid_authchain_emailpin": {
			"data\\initial_data.csv": {
				"[2]": {
					"value": "4"
				},
				"[3]": {
					"value": "6"
				}
			}
		}
	},
	"Functional": {
		"hid_policy_wfemail": {
			"data\\events.csv": {
				"[0]": {
					"WriteFile": "FALSE"
				}
			}
		}
	},
	"Data": {}
}

Note that just because the override has been added for the component Scenario.hid_authchain_emailpin to the xyz-dev.json environment file, it does not mean an override needs to be added to other environment files. For example, since the default values being provided by the component suit the needs of the production environment, no further entries need to be added to the xyz-prod.json file. The resulting xyz-prod.json file will still appear as:

{
	"Scenario": {},
	"Functional": {
		"hid_policy_wfemail": {
			"data\\events.csv": {
				"[0]": {
					"WriteFile": "FALSE"
				}
			}
		}
	},
	"Data": {}
}

As environment files get larger and contain multiple user classes, target addresses, and so on, it makes sense to define variables at the top of the file to make the process scalable. Using variables for a small set of environment file configurations is unnecessary, such as only having a single target as seen in the configuration example capturing idmconfig changes, but once you have ten or more targets, creating variables is the optimal approach.

{
"_vars": {
	"ad": {
            "address": "testad.local"
	}
  },

{
"_vars": {
	"ad": {
            "address": "testad.local"
	}
  },
"Scenario": {},
"Functional": {},
"Data": {
	"hid_target_ad": {
		"ad.json": {
			"Fields": {      
				"address": "{server=${_vars.ad.address};nameFormat=NT4;}"
			}
		}
	}
  } 
}

{
"_vars": {
	"ad": [
		{
		 "id": "AD",
		 "name": "AD",
		 "address": "{server=testad.local;nameFormat=NT4;}",
		},
     		{
		 "id": "AD2",
		 "name": "AD2",
		 "address": "{server=testad2.local;nameFormat=NT4;}",
		}
	]
  },

"Scenario": {},
"Functional": {},
"Data": {
	"hid_target_ad": {
		"ad.json": {
			"Fields": {      
				"id": “${_vars.ad.id}",
				"address": “${_vars.ad.address}"
    			}
      	 }
        }
    }
}

A particularly useful use case for environments is inheritance, the ability to define one base environment with many of the overrides in place so environments like: development, production, or stage can easily be set up without needing to repeat entries many times.

One of the most common use cases for this is having different addresses for the AD target depending on the environment you have loaded. For this example company-base.json will be used as the base environment, and both company-dev.json and company-prod.json that inherit from it.

Using a Data.hid_target_ad component override as an example again, the company-base.json file is written as:

{
	"Scenario": {},
	"Functional": {},
	"Data": {
		"hid_target_ad": {
			"ad.json": {
				"Fields": {      
					"address": "{server=${_vars.ad.address};listNestedGrps=true}"
				}
			}
		}
	}
}

Then, other environment files are written similar to this company-dev.json file:

{
	"_inherit" : ["company-base"],
	"_vars": {
		"ad": {
			"address": "development-address.domain"
		}
	}
}

or this company-prod.json :

{
	"_inherit" : ["company-base"],
	"_vars": {
		"ad": {
			"address": "production-address.domain"
		}
	}
}

This would make it so the replacement in the AD target address line depends on which of the two environment files (dev or prod) is loaded, without explicitly overriding the address in both environments. Note that writing your environments like this will make it so company-base.json cannot function independently, which is fine as long as it’s understood in your implementation.