Using the SailPoint Configuration Hub

The SailPoint Configuration Hub supports management of configuration objects in your SailPoint IdentityNow tenant through backup and deploy operations. For example, you can back up configurations like Sources and Identity Profiles defined for your business, restore them in the event of configuration errors or loss, or migrate and deploy them to your other tenants.

• Source Tenant - this is the tenant from which you want to migrate the configuration backup. This is sometimes referred to as 'connected tenant'.

• Target Tenant - this is the tenant you want to deploy the configuration to or compare with. This is sometimes referred to as live tenant.

Note

The Configuration Hub does not perform full system backups. It backs up configuration objects that represent your tenant settings, business systems, and access model components. For a list of supported objects in configuration backups, refer to SaaS Configurations on the SailPoint Developer Community.

Granular User Levels for Configuration Hub Access

You can use the various user levels to grant least privilege access to configuration hub for the specific administration needs of each admin, including read only access.
For more information on the user levels refer to Configuration Hub User Level.

Accessing the Configuration Hub

Access the Configuration Hub through the SailPoint Solution Center.

1. Select the Solution Center icon in the upper-left corner of any IdentityNow page.

2. Select Configuration Hub.

   Note

   You must be signed into IdentityNow as an Admin user to access the Configuration Hub.

You can also access the configuration hub directly with the URL: https://<tenantName>.identitynow.com/ui/a/admin/config-hub/backups

Creating a Backup

You can manually initiate a backup of your configuration objects, retaining up to 10 manual backups at a time per tenant. When you reach this limit, you must delete one or more manual backups before you can create a new one.

Note

Configuration Hub does not back up secrets or credential information.

1. On the Configuration Backups page of the Configuration Hub, select Create Backup.

2. Provide a name for your backup.

3. Select the checkbox beside the types of objects you want to include in this backup, or select All Objects.

   You can further limit the objects included in this backup by entering the exact names of the specific objects to back up in the Objects by Name field beside a selected object type and select Enter. The names you enter in this field are case-sensitive.

   If the Objects by Name field is left blank, and the checkbox beside the object type is selected, all objects of that type will be included in the backup.

4. Select Create Backup.

   When your backup is complete, it will appear in the list of backups, marked as the Latest.

   Select Actions on the backup row and select View Summary to view a summary of the object types and counts included in it.

   From the summary page, you can also select View Details to see various objects.

   If you added specific objects to your backup by name, those objects are listed within this summary. The Objects by Name column displays all names you entered for that type, regardless of whether or not an object was found matching that name and type. However, the number in the Count column only reflects only the names you entered that correspond with objects.

Note

There could be more than one tenant listed in the backups list. The list of tenants in your Backups list represents additional tenants connected to your current environment. Go to Using Tenant Connections for more information.

Important

To easily identify which tenant is the current live one (i.e. the target tenant you are about to deploy configuration to), a green dot will be next to the tenant name under Backups.

Automated Backups

In addition to your manual backups, SailPoint also automatically backs up your production tenant's configurations. Automated backups are listed as Created By: SYSTEM in the backups list, and their retention and deletion are managed by SailPoint.

• An automated backup occurs weekly. The process deletes the oldest weekly backup as necessary to retain up to 5 weekly backups at a time.
• The draft creation process also creates an automated backup to compare with the selected backup, and the most recent one of these appears in the backup list.

Deleting a Backup

Only manual backups (meaning backups not created by the SYSTEM) can be deleted. To delete a backup:

1. Go to the Configuration Backups page of the Configuration Hub, select Actions on the backup row, and select Delete.
2. Select Delete to confirm.

Viewing Detailed Backup Objects

You can view the details of your backup configuration in JSON format.

1. Select Actions on the backup row and select View Summary to view a summary of the object types and counts included in it.

2. Select View Details on the backup summary page.

   When the details load, all of the various object types within this backup display in a list on the left of the screen. By clicking an object type, a list of all the related configurations for that type display.

   You can click Previous Object or Next Object to see the other object types.

   On the object type summary page, you can filter and sort through the objects that are a part of that object type. You can also search for keywords of an object name if it is known.

3. From the object names provided, click View to see the details of that object.

   JSON details are provided. These details cannot be altered.

Restoring from a Backup

You can use an automated or manual backup from your tenant to restore configurations as they existed when that backup was generated.

To restore from a backup:

1. Create a draft to identify which objects are different between the selected backup and your live tenant.

2. (Optional) Edit the draft to choose which objects to restore or to adjust the object details.

3. Deploy the draft to update your live tenant.

Uploading a Configuration File

Configuration files can be managed and deployed using Configuration Hub by uploading a JSON file which contains configuration data. You can upload up to 10 configuration files. Uploading a configuration file can be used for:

• Migration of converted IdentityIQ configurations.
• If there are previously exported configurations but there is no access to the tenant.
• Migration of configurations between tenants in different domains or regions.
• Uploading configurations that were shared by various communities.

To upload a configuration file:

1. On the Configuration Upload page of Configuration Hub, select Upload.

   Note

   The only supported file that can be uploaded is a .JSON file with a valid sp-config API request format.

2. Provide a name for the uploaded file.

3. Either drag and drop the file or select a file to upload it.
4. Select Submit.

When your configuration file is uploaded, it will appear in the list of uploads and be marked as "Latest".

An uploaded configuration file can be managed as any other backup file in configuration hub. Select Actions on the uploaded file to view the summary, prepare the draft for deployment, or to delete the uploaded file.

You can also substitute attribute values of an uploaded configuration file by using the Object Mapping feature to add rules to the Default mapping set.

Creating a Configuration Draft

A configuration draft captures the differences between the selected backup configuration and the live configurations in your target tenant at the time the draft was prepared.

Notes

• Draft creation can be performed from backups which contain up to 30,000 objects. To enable drafts from larger backups, contact SailPoint Support.
• You can have up to 5 drafts at a time. Creating a new draft automatically deletes the oldest draft that hasn't been deployed when you reach this limit.

1. Go to the Configuration Backups page of the Configuration Hub, select Actions on the backup row, and select Prepare Draft for Deployment.

   You can also initiate a draft creation from the backup's View Summary overlay.

2. Specify a Draft Name that describes the intent of this draft. This is especially important if you are not deploying it immediately, as you may be working with multiple drafts at once for different purposes.

3. Select Create Draft to initiate the comparison. When that completes, the draft is automatically saved and its summary is displayed.

   The Draft Summary shows how deploying the draft to your tenant will alter your tenant's configurations.

During the draft creation, Configuration Hub will apply various system rules and logic to handle configuration object dependencies, identify reference issues, and resolve object references. This is done by using the name and type of referenced objects to match and substitute object IDs with the corresponding ID of the object in the target tenant.

Important

If an object only includes the Object ID and not a name, Configuration Hub is not able to identify or resolve the reference issue until the configuration is deployed. If objects are not referenced by ID, manually modify the draft prior to deployment.

Viewing a Draft Summary

The Draft Summary is a presentation of the deployment plan. On the draft summary page, a user can easily view all modifications to the draft and its objects. The following are the columns that signify the changes.

• Adds to Live represents objects in the backup that don't exist in the live tenant and will be added to the live tenant configuration settings if the draft is deployed.
• Modifies to Live represents live objects that will be changed to match the backup's representation of the same configuration object.
• Not in Backup represents objects in the live tenant that don't exist in the backup. This is usually because these objects were created in the live environment after the backup took place.

• Reference Issues - This column appears when there are reference issues for an object. The user can view a detailed error message to understand the issue.

  Note

  Selecting a number in the desired column will open the specific object type tab.

  You can also edit your draft objects from this summary.

  Note

  During a draft creation, if problems are detected in a draft object that will prevent successful deployment, the object and its object type will be marked with Reference Issues. In most cases, this is caused by references to other objects which do not exist in the tenant, such as an owner identity that has been deleted.

Editing a Draft

You can select a specific Object Type to edit and remove objects from the draft that you don't want to deploy to your live tenant. You can also edit object details before deploying.

To edit a draft that was previously, select Actions on the draft row to edit or delete a draft.

Editing a draft begins at the Draft Summary of a draft you just created or of a saved draft.

1. To remove all configuration objects of any object type from a draft, clear the checkbox on that row of the Draft Summary table. For example, you could remove all Source objects from the draft.

2. To view or modify the list of the draft's configuration objects for any type, select Edit on that row. Objects are grouped into tabs according to whether they will be added to or modified in the live tenant when deployed.

3. To remove an individual object from the draft, clear the checkbox on that object's row.

4. To change details about an object, select Edit on that row, modify its JSON definition, and select Save. The JSON is validated on save to prevent JSON errors.

   When editing a draft object, multiple views display:

   • Edit View - You can see already made modifications in Changes in Object. You can also edit the object definition in Draft Object and see the changes live in Changes in Object.
   • Change Log - Tells you the type of modification as well as the live and draft values.
   • Rule Substitution - Lists the attribute value substitutions that are automatically applied to the draft.
   • JSON View - Allows you to edit in Draft Object, while showing you what is currently live.

   Important

   • You cannot edit or remove the id of the object.
   • Your edits will only be saved to the draft when you save your changes on the Draft Summary page.
   • When you are finished making changes to individual objects, select Back to Draft Summary to return to the summary page.

5. Select Save Changes.

   Notes

   • When you save changes to your draft, any objects or object types that you removed from the draft are permanently deleted from it. If you discover you made a mistake, you must create a new draft from the backup and start again.
   • The backup itself is never modified by actions you take on the draft.

6. To cancel your changes without updating the draft, select Discard Changes.

Deploying a Draft

Deploying a draft to your live tenant adds or updates configuration objects in your tenant to match the ones in the draft.

Before deploying a draft, carefully review the new and edited objects within the draft to confirm the correct configuration is being deployed. Follow your organization's change management and approval process when deploying any draft configuration.

Note

Drafts containing up to 5,000 objects can be deployed. To enable deployment of larger drafts, contact SailPoint Support.

Important

Draft deployment does not automatically delete objects from the live tenant. The Not in Backup list is provided as a reference and includes objects that exist in the live tenant, but not in the backup. If necessary, these objects can be manually deleted within your live environment.

Deploying a draft begins at the Draft Summary of a draft you just created or edited, or of a saved draft.

1. To select a saved draft, go to the Configuration Drafts page of the Configuration Hub, select Actions on the draft row, and select Edit.
2. Select Deploy Draft to update your tenant's configurations from the draft. Select Deploy to confirm.

3. When deployment finishes, review the completion status and process details. The details contain the name and ID of each deployed object along with any errors or warnings encountered.

   Important

   These objects require manual actions after deployment to restore their connections to other configurations.

   • Password policies must be manually reconnected to sources. This includes redefining any exception policy filters.
   • Service desk integrations must be manually reconnected to virtual appliances.

Promoting a Backup

Promoting a backup means taking a backup from a connected tenant and deploying it to live.

Promoting a backup means taking a configured backup of a connected source tenant and deploying it to the current live tenant.

Reviewing Deployment Activity

You can review the results of all completed, failed, or partially completed deployments within the Configuration Hub.

To review deployment activity for your tenant:

1. Go to the Activity Log within the Configuration Hub.

   You can see a list of all deployment attempts within your current tenant, the name of the user that started the deployment, and its result.

2. To see detailed information about a specific deployment event, select the View button in the Actions column.

   • Failed - All configuration objects in the deployed drafts failed to deploy.
   • Complete - All configuration objects in the deployed drafts were successfully deployed.
   • Partially Complete - Some objects were successfully deployed and some failed.

Within the View option, you can view the following information in the deployments.

• The Deployment Log provides a summary of the results with the status for each of the deployed configuration objects.

• The Deployment Draft provides details of the draft configuration with all objects that were submitted for deployment.

To view audit records of draft deployments, use search to view events with the name Update Config Passed or Update Config Failed.

Using Tenant Connections

You can create and review various tenant connections. Connecting other tenants to your environment allows you to perform an array of tasks, such as deploying a backup of your staging environment to your production tenant.

Note

To ensure a successful connection, verify network traffic is not blocked from the current tenant to the connected tenant. This could happen if the user's Identity Profile blocks access or if the Network Setting does not allow traffic from the target tenant. Also, tenants should be in the same region.

To connect another tenant to your environment:

Note

Before entering the required information, a Personal Access Token needs to be created. Create a Personal Access Token in the connected tenant to grant access to view its backups from the target tenant. Tenant connections are per user and are not shared with other users.

Note

The Personal Access Token for the tenant connection should be created with a scope of sp:config:backup-connection.

1. Login to the target tenant.
2. Go to the Tenant Connections within the Configuration Hub. You can see a list of all connected tenants. This list also provides the Client ID and the date and time the tenant was added.
3. Select Create Tenant Connection. The connection dialog displays where you need to provide authentication details.
4. Once the Personal Access Token is created, provide the new Tenant Name, Client ID, and Secret.

5. Select Create New.

   Your tenant connection is immediately added to the list as well as the backup list.

Note

Only tenants in the same region can migrate between each other.

Deleting Tenant Connections

1. Go to the Configuration Backups page of the Configuration Hub, select Actions on the tenant row, and select Delete.
2. Select Delete to confirm.

Mapping Objects

The function of object mapping allows objects with varying names and IDs to be compared. While objects are compared, a user can replace a value in the source tenant with a new value. Object mapping also helps in locating referenced objects to the source object during the drafting process.

Object Mapping can be found by going to Advanced Settings > Object Mapping.

The following must be specified for effective mapping:

• Object Type
• JSON Path
• Source Value
• Target Value
• Enabled Status

Create a New Mapping

1. From the dropdown Select a Tenant, choose the tenant you want to start mapping from.

   The different object types within that tenant displays.

   The JSON Path column provides specific fields that are matched to the target value during the creation of the mapping. It is always preceded by a "$."

   The values listed under Original Value provide the name of what the value was before it was mapped to something else.

   The values listed under New Value are editable. Hover over one you wish to change and a pencil icon displays. Select the pencil icon and change the value.

   The user has the ability to decide whether a particular mapping entry should be applied during the next draft creation process. To apply the mapping, select Enabled.

   Note

   When a new mapping is created, The Enabled column is turned off by default.

2. To delete an object mapping from the tenant, select Delete.

To create a new mapping between objects, complete the following:

1. Select Create New.

2. To add a mapping, select Add Another. A row of empty values appears.

3. From the dropwdown, select the Object Type.

4. In the JSON Path field, type the specific field that needs to be matched to the target. This field value has to be started with $..
5. In the Original Value field, type the old value.

6. In the New Value field, type of the new value of the Object Type.

   Continue creating more mapping by selecting Add Another.

7. If a new mapping is not needed, select Remove.

8. When all mappings have been added, select Save Changes.

Important

Users cannot create duplicate mappings with the same object type, JSON path, and source value.

Note

During the draft creation, Configuration Hub uses Global Configuration Substitution Rules which are pre-configured logic for attribute value substitution. This helps reduce the manual adjustments of configuration settings which are required when comparing or migrating configurations between different environments:

• Retain tenant specific attribute values of target tenant when deploying configurations (such as environment specific values, dates, owners)
• Set default values for configuration attributes (such as state fields)
• Attributes which should be ignored when comparing configurations between environments, to avoid false modify (such as dates, object owner, ids)
• Array elements sorting rules