Overview
How you would recover if that new intern thought he was working in your sandbox tenant and deleted all the roles? Or what if your Active Directory create provisioning policy is obliterated by an errant API call? It is an absolute must to have a configuration management strategy in place to quickly resolve these kinds of situations.
In this walkthrough, we are going to showcase three different approaches to the all important topic of configuration management in Identity Security Cloud (ISC):
- Configuration Hub – Admin interface built into ISC UI
- SailPoint CLI and SP-Config – SailPoint provided tool and APIs
- GitHub Actions – External tool widely used by developer community
Background
Before we explore these approaches, let’s talk about what configuration management is and why it can be challenging with a SaaS product like ISC. Configuration management is the discipline of ensuring that all software and hardware assets that a company owns are known and tracked. This is much easier to do this with an on-prem system because you own all the software and hardware assets. It is much more difficult with a SaaS cloud platform because you don’t own or control hardware assets – those are being managed for you, which is one of the major benefits of a SaaS cloud platform over on-prem. Most of the software assets are being managed for you as well, and your access to data and configurations is limited compared to on-prem. However, there are numerous configurations and customizations that are unique to every ISC implementation that must be managed. Additionally, a process needs to be in place for cross-tenant migration of these objects, such as promotion of new configurations from sandbox to production tenants. (This is an excellent resource that provides guidance about which objects should be considered for configuration management and cross-tenant promotion.) It is critical that your organization follow a controlled configuration, test, and deployment process.
In the past, most ISC configuration management was done manually, which had its obvious challenges. SailPoint released the SaaS Configuration APIs (SP-Config APIs) a few years ago to support configuration management beyond a completely manual process. These APIs provide a way to export and import specific configurations as JSON objects. The SailPoint CLI supports SP-Config functionality, and the CLI spconfig commands can be more easily scripted than the APIs themselves. Due to reference IDs and other issues, only a limited set of exportable object configurations can be imported via API.
At Navigate 2023, SailPoint announced Configuration Hub, a configuration management admin interface in the ISC UI, as a more robust solution. Since then, a multitude of additional features have been added such as tenant connections, granular user levels, uploading configuration JSON files, and cloud storage.
Another option is to integrate ISC configuration management into your existing version control and CI/CD environment. We are going to show how existing SailPoint tools like APIs and the CLI can be combined with GitHub Actions to do just that.
As we walk through each solution these are some questions to consider about ISC configuration management:
- What is your current configuration management process?
- Is it all manual?
- Is it being done by one admin?
- What happens when that admin leaves?
- Is the process documented?
- What rules and transforms have been deployed and where?
- What additional integrations are in place?
- How do you revert to earlier configurations?
- How do you keep track of rolling back configurations?
- How do you automate cross-tenant object promotion?
This guide aims to help you start answering these questions!
Configuration Hub
Backup and Deploy
Let’s explore basic ConfigHub backup and deploy functionality.
Once logged into the tenant, ConfigHub can be found by clicking on the Solutions Center icon 
in the upper-left corner:
The first page we see is the Backups page where we can view existing backups and create new ones. Up to 10 manual backups can be stored in ConfigHub:
We can see all the different object configurations that can be backed up.
Let’s create a a new backup of all available object types by checking the top checkbox:
Once a backup has been made, we can explore the JSON of all the object configurations by clicking the actions menu icon 
and then View Summary:
To restore the object configurations in a backup, a draft needs to be prepared to check for differences between the backup and the current live tenant configuration:
If no changes are detected between the backup and the current live tenant configuration, the draft will not be created:
Imagine an admin mistakenly deletes the assignment criteria from a role:
Now that we have a difference between the backup and the current live tenant configuration, when we prepare a draft for deployment a draft is created and can be viewed under drafts:
When we view the draft, we only see the differences. In this case, Adds to Live is 0 because we are not adding any new objects. Modifies to Live is 1, because there is one role in which a change was detected.
Under the draft edit view, we can explicitly see the changes in the JSON and even make additional changes manually:
We can go ahead and deploy the draft:
The status of the deployment is displayed:
Notice that when we deploy a draft, the draft disappears, but the original backup remains, and an automated backup is created to serve as a snapshot of the live tenant configuration before the draft was deployed:
Additionally, we can see all draft deployments under the Activity Log:
Cross-Tenant Object Promotion
We’ve seen how to restore configurations in the same tenant. Now let’s look at cross-tenant promotion of objects.
We can connect our production tenant to a sandbox tenant and pull backups from the connected sandbox tenant to deploy in the production tenant.
The first thing we need to do to set up the tenant connection is to create a PAT in the sandbox tenant. We don’t need to create the PAT under a user with ORG_ADMIN user level in ISC. ConfigHub has it’s own set of user levels. We will ensure this PAT has the lowest level access necessary by creating the PAT under a user with only the ConfigHub Backup Administrator user level. Additionally, we can increase the security even further by limiting the scope to sp:config:backup-connection.
Create a tenant connection in the production tenant by adding the tenant name and the newly created PAT ID and Secret:
Once the tenant connection is created, it shows up under Backups where we can view all the existing backups on that tenant. Notice that the live tenant we are working in has a green dot next to it so we can easily distinguish between tenants:
To showcase cross-tenant object promotion, we’re going to backup a new cloud rule that has been thoroughly tested in the sandbox tenant and is ready to be deployed to the production tenant. Instead of having to ask SailPoint to review this cloud rule again and deploy it to the production tenant, we can do it ourselves with ConfigHub.
First, we need to create a backup of only that one cloud rule in the sandbox tenant by checking just the RULE object and specifying the name of the rule, which in our case is Generate sAMAccountName:
If we view the the details of the backup, we can see the rule JSON object has two attributes, jwsHeader and jwsSignature. These attributes work as verification to ensure that no modifications are made to the rule after SailPoint approves and deploys it to the original tenant. If any modifications are made to the rule, the deployment to another tenant will fail:
If we return to our production tenant, we can now see the cloud rule backup under the sandbox tenant connection and deploy it from there:
Configuration Uploads
Tenant connections are extremely useful for migrating object configurations between tenants, but the tenants must be in the same AWS region. This works for customers whose sandbox and production tenants are in the same region, but it may not work for partner implementers. They may have tenants in one region with configurations on them that they would like to migrate to customer tenants in other regions. This is where configuration uploads come in.
Instead of setting up a tenant connection, we can export object configurations in a specific JSON format and upload them to any other tenant in any region for deployment, including cloud rules as long as the export is from tenant where they have been previously reviewed and deployed by SailPoint.
Under Uploads, we can create a new upload with
Generate sAMAccountName cloud rule upload.json (4.2 KB), a JSON file
of the same Generate sAMAccountName cloud rule:
Once a configuration upload has been created, it functions just like a backup, and a draft can be prepared for deployment:
The files for configuration uploads can come directly from the SP-Config download API or be manually created by copying JSON objects from the ConfigHub UI. They can even be generated from IdentityIQ object configurations exported from IIQ by customers who are migrating from IIQ to ISC.
Object Mapping
Any or all object types can be included in a backup on one tenant and deployed to another tenant. ConfigHub has a robust set of built in rules to handle differences between tenants. But there will be times when we need to create our own custom substitution rules, which we can do via object mapping. We can even create tenant specific object mappings.
Let’s use a backup of a workflow to illustrate this. There is a workflow called Notify Access Request Decided in the sandbox tenant.
Notify Access Request Decided workflow upload.json (5.7 KB)
An admin named Paul Martin created this workflow, so his name and ID are in the created, owner, and modifiedBy objects in the workflow JSON. If an identity with the same name as Paul Martin (Paul.Martin) existed in the production tenant, a default rule would substitute the correct ID references in the imported workflow JSON. But no Paul.Martin identity exists in the production tenant resulting in reference errors when we try to deploy a draft of the workflow:
We can resolve these reference issues by creating object mappings to handle these attributes in the workflow JSON. We can create these object mappings to apply to draft deployments from specific tenant connections, or we can create default object mappings that will apply to draft deployments of backups from all tenant connections and configuration uploads:
For each object mapping, we choose the Object Type. Then we provide the JSON Path to the attribute we are mapping in the JSON object along with the Original Value and New Value:
The JSON path will always start with $. Finding the JSON path for some attributes is fairly straightforward. If we look at this JSON snippet of the workflow creator object, we see that the JSON path is $.creator.name:
"creator": {
"type": "IDENTITY",
"id": "0ea1eb132d6841a79303877fe949e252",
"name": "Paul.Martin"
}
We can use a website like JSON Path Finder to identity the path in complex JSON objects.
We add all three object mappings and enable them so that they will apply when we deploy the workflow draft:
Now when we prepare a draft for deployment of the workflow, the reference issues have been resolved, and we can see the Rules Substitutions that were applied, including our object mappings. The DEFAULT_RULE we see here is specific to workflows. It sets the enabled attribute to false regardless of the incoming value to ensure that this new workflow is manually enabled in the tenant.
Much of the ConfigHub functionality is also available directly via API.
SailPoint CLI and SP-Config
The SailPoint CLI is a terminal-based tool we can use to interact with ISC tenants. The CLI provides a text-based environment we can use to run operations known as “commands” to interact with the tenants.
We can use the CLI to perform many API functions instead of cURL or Postman. For example, we can use the CLI to call the SP-Config APIs to export and import object configurations, and we can do all this directly on the command line, with minimal setup.
First we need to install the CLI. Instructions can be found in the CLI documentation.
Then we need to configure the CLI to connect and authenticate to the sandbox and production tenants:
Transforms Export and Import
To showcase this, we are going to export all the transforms in the sandbox tenant and import them into the production tenant.
We first switch to the sandbox tenant:
sail env use company5149-poc
Then we export just the transforms:
sail spconfig export --include TRANSFORM --description "Transforms export"
We check the export status and see that it’s complete:
sail spconfig status --export ccb611ef-dabc-4e26-a304-57a92cebd070
By referencing the export job ID, we can download the export to a specific file path by using the --folderPath option:
sail spconfig download --export ccb611ef-dabc-4e26-a304-57a92cebd070 --folderPath CLI/backups
Now we switch to the production tenant:
sail env use devrel-ga-12368
Finally, we import the transforms export download to to the production tenant:
sail spconfig import --filePath CLI/backups/spconfig-export-ccb611ef-dabc-4e26-a304-57a92cebd070.json
Any new transforms in the sandbox tenant will be added to the production tenant, and existing transforms will be updated with any changes.
We can check the import job status:
sail spconfig status --import 95f63847-98a0-4e84-8f8e-029295546fbf
We see that the import is complete, and we can download the results:
sail spconfig download --import 95f63847-98a0-4e84-8f8e-029295546fbf --folderPath CLI/backups
CLI Bash Script
The commands we ran manually to export transforms from the sandbox tenant and import them into the production tenant can be automated with a bash script:
#!/bin/bash
# Use sandbox env
sail env use company5149-poc
# Export transforms from sandbox env
output="$(sail spconfig export --include TRANSFORM --description 'Transforms export' --wait)"
# Get export job ID
export_job_id=$(echo "$output" | grep "Job ID" | awk {'print $3'})
# Construct export file path
export_filepath="spconfig-exports/spconfig-export-"$export_job_id".json"
# Switch to prod env
sail env use devrel-ga-12368
# Import transforms to prod env
sail spconfig import --filePath $export_filepath --wait
Utilizing the --wait option on the export command runs the transforms export from the sandbox tenant, waits for it to complete, and then downloads the results.
We get the export job ID with grep and awk and construct the filepath to the downloaded JSON file.
Then we import the transforms into the production tenant using the --wait option with the import command to wait until the import job has completed, and the results are downloaded:
GitHub Actions
GitHub Actions is a powerful automation platform built directly into GitHub that allows you to automate tasks like building, testing, and deploying code. It operates through workflows, which are YAML configuration files stored in your GitHub repository under the .github/workflows directory. These workflows define a set of automated steps triggered by specific GitHub events, such as pushing code, creating pull requests, or setting up scheduled jobs.
CI/CD Demo: Managing and Versioning Transforms
The CI/CD demo repository demonstrates how GitHub Actions can be leveraged to manage and version transforms within ISC. Included in the repository are sample transforms to guide you through the process of synchronizing changes between your staging and production environments, ensuring your updates are consistently deployed.
This demo showcases how GitHub Actions can automate testing for each push, helping you validate your transforms before they reach production. Additionally, the SailPoint CLI’s transform preview command lets you confidently test changes locally, giving you complete control over the transformation lifecycle, from development to deployment.
Automated Testing with Bats
We use the Bats (Bash Automated Testing System) framework to execute automated tests on the transforms. These tests run the transform preview command through the SailPoint CLI and verify the output, ensuring accuracy across environments. The tests are triggered whenever a pull request is made against the dev or main branches.
The test.bats file contains the necessary commands to validate the transforms based on the environment. For example:
@test "Verify DeriveFirstInitialLastNameInUpper Transform" {
RESULT="$(sail transform preview --profile $IDENTITY_PROFILE --identity $IDENTITY_ID --file transform_files/DeriveFirstInitialLastNameInUpper.json -r)"
[ "$RESULT" = "AKENNEDY" ]
}
Transform
{
"attributes": {
"input": {
"attributes": {
"values": [
{
"attributes": {
"begin": 0,
"end": 1,
"input": {
"attributes": {
"name": "firstname"
},
"type": "identityAttribute"
}
},
"type": "substring"
},
{
"attributes": {
"name": "lastname"
},
"type": "identityAttribute"
}
]
},
"type": "concat"
}
},
"name": "Derive FirstInitial+LastName In Upper",
"type": "upper"
}
Managing Transform Mappings
The repository includes a mapping file, which is dynamically updated with transform IDs as new transforms are created in the Identity Security Cloud. In the dev branch, the IDs correspond to the staging environment, while in the main branch, they align with production.
A GitHub Action ensures that when transforms are merged between branches, the transform IDs are updated correctly without being recorded as actual code changes. This keeps your transforms in sync without introducing noise into your version history.
Conclusion
As we have shown in this walkthrough, a configuration management strategy is a must for every ISC implementation. We explored three different approaches. First, we looked at Configuration Hub, which supports backing up and deploying object configurations as well as cross-tenant promotion right in the ISC admin UI. Next, we looked at how the SailPoint CLI can be harnessed for manual export and import operations with the spconfig commands and easily automated with Bash scripting. Lastly, we showcased a true configuration management CI/CD pipeline using GitHub actions.
Because of the complexity of a identity security solution like ISC, there is no one-size-fits-all configuration management solution, but the approaches we covered offer varying levels of functionality and can be customized for any implementation. Take a dive into the documentation and resources provided to start developing your ISC configuration management strategy!