Using ISC ConfigHub to Promote Objects Between Tenants

Bassem_Mohamed · May 6, 2025, 1:17pm

Overview

The SailPoint Identity Security Cloud (ISC) Configuration Hub (ConfigHub) simplifies the management of configuration objects within your SailPoint ISC tenant through backup and deployment operations. With ConfigHub, you can back up essential configurations like Sources and Identity Profiles, restore them in case of errors or data loss, or migrate them between different environments. This document provides best practices for leveraging ConfigHub in tenant migration, particularly when promoting configurations from a source tenant (e.g., sandbox) to a target tenant (e.g., pre-prod or production).

Migration/Promotion Best Practices

When migrating or promoting configurations between tenants, consider these best practices:

Documentation

Document all configuration objects being migrated, including their dependencies and related settings.
Maintain a migration plan and checklist to track progress and ensure consistency.

Version Control

Use ConfigHub’s version control to track changes to configuration objects and enable rollbacks if necessary.

Staged Approach

Migrate configurations in stages, moving from Sandbox/Dev → UAT/Pre-Prod → Production. This approach allows testing at each stage and minimizes potential disruptions in production.

Data Integrity

Validate data integrity before and after migration. Use verification methods, such as data checks and object comparisons, to identify potential issues.

Security

Ensure that security settings and access controls are correctly migrated to the target environment.
Encrypt or mask sensitive data during migration if necessary.

Testing

Perform comprehensive testing in a non-production environment before migrating configurations to production.
Include User Acceptance Testing (UAT) to verify functionality and user experience.

Backup

Always create backups before starting the migration process. This ensures data can be restored in case of errors.

Downtime Minimization

Plan migrations during off-peak hours to minimize service interruptions.
Consider blue-green deployment strategies if possible.

Monitoring

Implement monitoring to quickly detect and address issues during and after migration.

Rollback Plan

Have a clear rollback plan in case of significant issues. This could involve restoring backups or using ConfigHub’s version control.

Compliance

Ensure the migration complies with relevant regulations and internal policies, especially if sensitive data is involved.

Communication

Keep all stakeholders informed throughout the migration process to manage expectations and address concerns.

Post-Migration Validation

Perform post-migration checks to ensure that configurations work as expected in the new tenant.

Multi-Environment Configuration and Its Benefits

A staged environment infrastructure, with proper controls for testing and migrating changes across different environments, is crucial for preventing production outages and minimizing configuration issues. SailPoint recommends the following distinct environments:

Development/Sandbox Tenant: Used by the implementation team for configuration, integration, and testing.
User Acceptance Testing (UAT)/Pre-Prod Tenant*: Dedicated to quality assurance and user acceptance testing.
Production Tenant: The live environment where end users interact with the system.

This multi-environment approach ensures thorough testing at each stage, reducing the likelihood of issues in production and enabling smoother transitions between environments.

*SailPoint Identity Security Cloud is delivered with only a Sandbox and a Production tenant by default. If you require an extra UAT/Pre-Prod tenant, please contact your SailPoint team.

SailPoint ISC ConfigHub Features Highlight

ConfigHub offers several features to streamline configuration management and migration:

Version Control: Enables tracking changes, rolling back configurations if necessary, and maintaining consistency.
Environment-Based Configuration: Supports different environments (e.g., dev, staging, production) to facilitate staged migration and testing.
Export/Import Functionality: Allows exporting configurations as files for cross-tenant migration.
API Access: Provides endpoints for automating configuration migration and object promotion.
Access Control: Limits access to authorized personnel, enhancing security.

These features, while designed primarily for single-tenant management, can be applied to multi-tenant migrations with some manual intervention.

Using SailPoint ISC ConfigHub in Tenant Migration Best Practices

Object Dependencies

Each configuration object has dependencies that must be considered during migration.

Dependencies, including optional ones noted by ( * ), should be addressed to ensure configurations are promoted in the correct order. This prevents issues with missing or incompatible references.

Promotion/Migration Phases

A structured, phased sequence is recommended for promoting configuration objects to ensure dependencies are respected and configurations are introduced in a controlled, organized manner. Below is an overview of the typical phases:

Phase 1: Core configurations and foundational objects are migrated first, such as AUTH_ORG and SOURCE configurations, to establish primary structures and initial access settings in the target tenant.
Phase 2: Configurations that build on Phase 1 objects, such as IDENTITY_PROFILE and LIFECYCLE_STATE, are added next, relying on the foundational elements established in the initial phase.
Phase 3: Dependent objects, including GOVERNANCE_GROUP, are then migrated, following successful completion of Phase 2 to ensure they integrate smoothly within the established structure.
Phase 4: Advanced configurations, like access controls (e.g., ACCESS_PROFILE) and integrations (e.g., SERVICE_DESK_INTEGRATION), are introduced, leveraging the groundwork laid in previous phases for optimal functionality.
Phase 5: Customizations and complex configurations, including CAMPAIGN_FILTER and ROLE definitions, are applied last, adding final layers of functionality after confirming stability in prior phases.

This phased approach is vital for identifying and addressing dependencies and configuration issues ahead of production, enabling more effective control and troubleshooting throughout the migration.

Object	Dependency	Promotion/Migration Phase
ACCESS_PROFILE	IDENTITY_PROFILE, SOURCE	4
ACCESS_REQUEST_CONFIG	None	4
ATTR_SYNC_SOURCE_CONFIG	IDENTITY_OBJECT_CONFIG, IDENTITY_PROFILE, SOURCE	4
AUTH_ORG	None	1
CAMPAIGN_FILTER	SOURCE, ROLE, ACCESS_PROFILE, IDENTITY_PROFILE	5
FORM_DEFINITION	IDENTITY_PROFILE, WORKFLOW, SOURCE, ACCESS_PROFILE	5
GOVERNANCE_GROUP	IDENTITY_PROFILE	3
IDENTITY_OBJECT_CONFIG	None	1
IDENTITY_PROFILE	IDENTITY_OBJECT_CONFIG, TRANSFORM, RULE, SOURCE(Auth Source)	2
LIFECYCLE_STATE	IDENTITY_PROFILE	2
NOTIFICATION_TEMPLATE	IDENTITY_PROFILE	5
PASSWORD_POLICY	None	1
PASSWORD_SYNC_GROUP	SOURCE	4
PUBLIC_IDENTITIES_CONFIG	IDENTITY_OBJECT_CONFIG	2
ROLE	IDENTITY_PROFILE, SOURCE, ACCESS_PROFILE	5
RULE	None	1
SEGMENT	IDENTITY_OBJECT_CONFIG, IDENTITY_PROFILE	5
SERVICE_DESK_INTEGRATION	IDENTITY_PROFILE, SOURCE, RULE	4
SOD_POLICY	IDENTITY_PROFILE, SOURCE, TAG*	N/A
SOURCE	IDENTITY_PROFILE [Fon Non-Auth Sources], PASSWORD_POLICY, PASSWORD_SYNC_GROUP, RULES*	1 (Only Auth Source) 3
TAG	SOD_POLICY, ACCESS_PROFILE, ROLE*	5
TRANSFORM	IDENTITY_OBJECT_CONFIG	1
TRIGGER_SUBSCRIPTION	IDENTITY_PROFILE, FORM_DEFINITION, WORKFLOW*	5
WORKFLOW	IDENTITY_PROFILE, FORM_DEFINITION*	5

NOTE: The objects marked with an asterisks ( * ) are optional dependency.

Partial vs. Full Migration

This guide covers both full tenant migrations (e.g., sandbox to pre-prod) and partial migrations. For full migrations, all configuration objects and their dependencies are migrated, while in partial migrations, only selected configurations and their dependencies are promoted.

Full Migrations: Migrate all configuration objects and their dependencies.
Partial Migrations: Focus on specific configurations and their dependencies as specified in migration documentation or the ConfigHub dependencies table.

Common Object Mappings

ConfigHub relies on precise object mappings to ensure data consistency across environments. Below are some common object mappings for source migrations:

Source	Mapping	C
Source Owner	Temporarily set the Source Owner to a breakglass account during migration. Post-migration, update to the correct HR source owner after aggregating identities.
Authoritative Source	Disable object mapping for $.owner.name to avoid conflicts.
AD Source [IQserver Host and AD Domain Server]	Mappings for $.connectorAttributes.IQServiceHost and `$.connectorAttributes.domainSettings[].servers[].`
JDBC Source	$.connectorAttributes.url
WebService Source	$.connectorAttributes.genericWebServiceBaseUrl

Manual Actions

Certain configurations require manual intervention during migration. Examples include:

VA Cluster Links: Manually link the source to the appropriate cluster if required.
JDBC and Custom Connectors: Manually upload JDBC drivers or provisioning JAR files in the target tenant’s Connector settings. Configure connection strings, re-enter passwords or secrets, test connections, and run aggregations.
Source Aggregation Schedulers: Set up aggregation schedules manually as they are not automatically promoted.
Source Certifications: Upload any required certifications (e.g., AD Certification) manually in secure connections.
Roles: Roles may be promoted in a disabled state. Enable them manually from the ISC UI.
Workflows: Update workflows with hardcoded values or environment-specific data.

Automation

The ConfigHub API (see documentation at ISC API 2025 Configuration Hub) provides endpoints for automating configuration backup, deployment, and promotion. Common automated tasks include:

Programmatic Export and Import: Automate configuration backup and deployment between tenants.
Automated Version Control: Track changes and roll back configurations if necessary.

While automation can handle many aspects of migration, certain dependencies and object mappings still require manual intervention, as detailed above.

Conclusion

By following these best practices and leveraging the robust features of SailPoint ISC ConfigHub, you can ensure a smooth and consistent migration process across your ISC tenants. Key actions like documenting configurations, maintaining a version control strategy, following a staged migration approach, and validating post-migration success all play a crucial role in minimizing disruption. Ensuring data integrity and security during migration and implementing a rollback plan are essential to safeguarding your environments.

While automation can handle many aspects of migration, manual interventions may still be required to address dependencies and configurations unique to your environment. This comprehensive approach ensures that your target environment is ready for production without compromising stability or security.

Additionally, SailPoint’s developer community blog provides further configuration insights, covering techniques to Backup, Deploy and Manage Identity Security Cloud Configurations.

Credits go to @kaveh_ahmadian and @rohit_prabhu for their invaluable contributions to the development and refinement of this migration guide. Special thanks to the ConfigHub Product Team for their ultimate support and assistance throughout the process of developing this guide.

olivier_detilleux · May 6, 2025, 1:56pm

Fantastic article Bassem. I need to read it more in details. I’ve played with ConfigHub a lot to import identityProfiles and I ran into troubles especially when importing LCS. For instance, if there is an access profile configured on the LCS, the id is not migrated. Do you know if this can be changed using a mapping ?

vishal_kejriwal1 · May 6, 2025, 2:02pm

@Bassem_Mohamed ,

based on the above table it is mentioned that IDENTITY_OBJECT_CONFIG object has no dependency

but when i check this object i see attributeTargets block which contain the source and attribute mapping

 {
                        "displayName": "Business Title",
                        "editMode": "ReadOnly",
                        "name": "businessTitle",
                        "silent": false,
                        "system": false,
                        "groupFactory": false,
                        "standard": false,
                        "type": "string",
                        "multi": false,
                        "extendedNumber": 0,
                        "attributeSources": [
                            {
                                "defaultValue": null,
                                "reference": {
                                    "type": "RULE",
                                    "id": "15XXXXXXXXXf608c2e3",
                                    "name": "Cloud Promote Identity Attribute"
                                }
                            }
                        ],
                        "attributeTargets": [
                            {
                                "name": "Title",
                                "provisionAllAccounts": true,
                                "applicationRef": {
                                    "type": "SOURCE",
                                    "id": "<SOURCE_ID>",
                                    "name": "VishalUS SaaS Application"
                                },
                                "ruleRef": null
                            },
                            {
                                "name": "Business_Title__c",
                                "provisionAllAccounts": true,
                                "applicationRef": {
                                    "type": "SOURCE",
                                    "id": "<SOURCE_ID>",
                                    "name": "VishalIndia SaaS Application"
                                },
                                "ruleRef": null
                            },
                            {
                                "name": "title",
                                "provisionAllAccounts": true,
                                "applicationRef": {
                                    "type": "SOURCE",
                                    "id": "<SOURCE_ID>",
                                    "name": "Vishal Slack Application"
                                },
                                "ruleRef": null
                            }
                        ]
                    },

Bassem_Mohamed · May 6, 2025, 2:18pm

That’s yes and no, the dependency here means that the promotion code is going to check of other objects if they are exit or not during the promotion, as example: For Lifecycle states the code will check if the Identity profile name exists while importing the LCS, if not it will come up with an error.

In case of IDENTITY_OBJECT_CONFIG the code doesn’t check for any dependency before importing it, and if you follow the approach mention to promote all Phase 1 objects the same time, the code is smart enough to map every transform or rule to its attribute.

vishal_kejriwal1 · May 6, 2025, 3:15pm

Thank you Bassem for clarification . I was checking the SOURCE Object when i try to export this source object it’s always shows authoritative as false even though if the SOURCE is authoritative.