SailPoint Configuration Manager

anneragh · March 15, 2024, 2:23pm


	Description	PowerShell Module to download cloud configuration and push it into version control
	Legal Agreement	By using this CoLab item, you are agreeing to SailPoint’s Terms of Service for our developer community and open-source CoLab.
	Repository Link	https://github.com/sailpoint-oss/colab-sailpoint-configuration-manager
	Supported by	Community Developed

Overview

Powershell module to download the configurations from the SailPoint Identity Security Cloud and manage them in a version control(git). This module enables you to schedule backups, ensuring the preservation of configuration history. The module incorporates built-in Git commands, facilitating configuration management through PowerShell cmdlets.

Version control enhances productivity, facilitates collaboration, and helps ensure the stability and integrity of Identity Security Cloud projects.

Requirements

As of today(01-Feb-2024), Sailpoint configurations are not version-controlled. Only the current configuration state is stored in the Sailpoint tenant.

Retrieve the configuration from the Sailpoint tenant and store it on your computer.
Upload your configurations to version control to manage their history.

Guide

To get started with the SailpointConfigManager

prerequisite

1 Powershell module 6.2 and above
2 Sailpoint clientId and Secret

Download

Follow these steps to manually install the PowerShell module:

Download Module
Download the source code zip from the most recent release on GitHub.
Extract the zip
Extract the ZIP file, then open the folder labeled SailpointConfiguration-Vx.x.x, with the x.x.x representing the version you downloaded.
Move the SailpointConfigManager module folder inside to one of the following locations:
- To install for the Current user:
```
C:\Users\<username>\Documents\WindowsPowerShell\Modules\
```
- To install for All users (requires Administrator privileges):
```
C:\Program Files\WindowsPowerShell\Modules\
```
Import Run Import-Module SailpointConfigManager to import the module into the current session.
To validate that the module is installed, run Get-Module -ListAvailable SailpointConfigManager and verify that the module is listed. Additionally, you can run Get-Command -Module SailpointConfigManager to see the module’s available commands.

The SDK is now installed. To learn how to configure the SDK, refer to the Configure section.

Configure

**Import PowerShell Module

  Import-Module SailpointConfigManager

Sailpoint Configuration

    $env:SAIL_BASE_URL="https://<tenant>.api.identitynow.com"
    $env:SAIL_CLIENT_ID="<client ID>"
    $env:SAIL_CLIENT_SECRET="<client secret>"

Export configuration from the Sailpoint
This cmdlet downloads the configuration from the sailpoint to your computer.

    Export-SpConfig -OutputPath "/path/to/your/sailpoint/configuration/folder"

Version control - One-time setup

There are many version control applications available, but one of the most widely used programs is git. If you are new to git, you can learn more here. Setting up a Git repository involves a series of steps, from initializing a new repository to making the initial commit. Here’s a basic guide to help you set up a Git repository:

Install Git:
Ensure that Git is installed on your system. You can download and install Git from the official website: Git Downloads.
Open a Terminal or Command Prompt:
Open a terminal or command prompt on your computer.
Navigate to Your Project Directory:
Use the cd command to navigate to the directory where you want to create your Git repository. For example:
```
cd /path/to/your/sailpoint/configuration/folder
```
Initialize a Git Repository:
Run the following command to initialize a new Git repository:
```
git init
```
This creates a hidden .git directory in your project folder, which is where Git stores its internal data and configuration.
Add Files to the Repository:
Add the files you want to include in the initial commit using the following command:
```
git add .
```
This command stages all the files in the current directory for the initial commit. You can also specify individual files if needed.
Commit the Changes:
```
git commit -m "Initial commit"
```
Replace “Initial commit” with a meaningful message describing the changes made in this commit.
Create a Remote Repository:
If you want to store your repository on a remote server (like GitHub, GitLab, or Bitbucket), create a new repository on the platform and follow the instructions to link your local repository to the remote one.
Push to Remote:

Commit the staged changes to the repository with a commit message:
If you’ve created a remote repository, push your local changes to the remote server:
```
git remote add origin <remote-repository-url>
git push -u origin master
```
Replace <remote-repository-url> with the URL of your remote repository.

Now, you’ve successfully set up a Git repository, committed your initial changes, and, if applicable, linked it to a remote repository. Adjust these steps based on your specific needs and workflow.

Example snippet: Extract configuration and git push

    #Import module
    Import-Module SailpointConfigManager


    #Configure connection parameters
    $env:SAIL_BASE_URL="https://<tenant>.api.identitynow.com"
    $env:SAIL_CLIENT_ID="<client ID>"
    $env:SAIL_CLIENT_SECRET="<client secret>"

    #Path to store configuration
    $Outpath = /path/to/your/sailpoint/configuration/folder
    Set-Location $Outpath

    #git Pull (prerequisite Version control - One time setup )
    Invoke-Gitpull
    
    #Download all the configurations
    Export-SpConfig -OutputPath $outputpath
    
    #git add
    Invoke-GitAdd .

    #git commit
    Invoke-Gitcommit -Message "New changes"
    
    #Git push
    Invoke-Gitpush

Schedule

Schedule the above snippet to frequently pull from your sailpoint tenant and push to the git to maintain the history of all configuration changes in your tenant.

Version Control cmdlets

Add Files:
- Add the files you want to track to the version control system. For Git, use Invoke-GitAdd -Path <file>.
Commit Changes:
- Commit your changes to the version control system, creating a snapshot of the current state. For Git, use Invoke-GitCommit -Message "Your commit message".
Branching:
- Create branches to work on specific features or fixes without affecting the main codebase. For Git, use Invoke-GitBranch -Name "Branch Name" and Invoke-GitCheckout -Name "Branch Name.
Update and Sync:
- Fetch changes from a remote repository and update your local copy. For Git, Invoke-GitPull.
Push Changes:
- Upload your local changes to a remote repository to collaborate with others. For Git, use Invoke-GitPush.
Pull Requests:
- If using platforms like GitHub or GitLab, create pull requests to propose changes and discuss them before merging. Invoke-GitPull

svenkitachalam · March 28, 2024, 1:57am

Hi Raghunath,

I seem to not get this working. On checking further it seems like foreach($Object in $ConfigResponse.objects) isn’t returning any objects. From the logs I can confirm that the export is complete and $ConfigResponse has the exported json. Am I missing something in the configuration or is there a different version of the code I need to be using?

Thanks in advance!

Regards,
Sreejith

anneragh · March 28, 2024, 2:03am

Hi Sreejith,

Thank you for downloading and using this module. I just tested and it is working!
Could you please help me with troubleshooting:

Do you see any error?
Which scopes are granted for the supplied credentials?

Which version you have downloaded, V1.0.1 or V1.0.0?

Please use the below link for the latest version.

Thanks
Raghu

anneragh · March 28, 2024, 2:32am

@svenkitachalam

I have validated the version just now.

Export-SpConfig -OutputPath $Outpath

DEBUG: Getting Access Token
DEBUG:
DEBUG:
DEBUG:
DEBUG:
DEBUG: Initiating Export
DEBUG: Initiated Export : Response JOBID: @{jobId=; status=NOT_STARTED; type=EXPORT; expiration=04/04/2024 02:25:05; created=03/28/2024 02:25:05; modified=03/28/2024 02:25:05}
DEBUG: Initiated Export done - checking is request completed for job ID
DEBUG: checking is request done
DEBUG: request not completed to download configurations - wait 2 seconds now - TOtal time in seconds 0
DEBUG: request not completed to download configurations - wait 2 seconds now - TOtal time in seconds 2
DEBUG: request not completed to download configurations - wait 2 seconds now - TOtal time in seconds 4
DEBUG: REquest completed starting download/download
DEBUG: download completed
DEBUG: Start Extract to files

Directory: D:\Sailpoint\EndUser

…

DEBUG: Finish Extract to files

svenkitachalam · March 28, 2024, 2:43am

I don’t see the folders created and json outputs in them. Supplied credentials has scope:all. I added additional debug statements on the powershell scripts and see that the exported json is received. The statement “foreach($Object in $output.objects)” in ExportSpConfig.ps1 doesn’t seem to return anything. So its not entering the loop.

anneragh · March 28, 2024, 3:33am

@svenkitachalam

That sounds tricky to reproduce on my side, especially when no errors, that sounds like the configuration export was sucess. However, failing to loop through each object.

Please enable the debug and post your findings. $DebugPreference="continue"

svenkitachalam · March 29, 2024, 5:45pm

Thanks @anneragh . This could well be something to do with my environment. I will debug more and let you know once I fix it. This module is really helpful to back up the configurations to git periodically. It would be even better if we are able to push only the configurations that are changed and not do every object all the time. By doing so, we would be able to truly use git for any change management review. Unfortunately, I don’t think there are APIs today to fetch just the changed objects. Hopefully with expansion of the configuration hub, we have option for it.

Thanks,
Sreejith

anneragh · March 29, 2024, 6:06pm

Thanks for using this module. I’m glad it helped you!.

Concerning pushing changed configurations, technically, this script downloads all configurations from the tenant every time. However, internally, Git only commits changes, if no changes git will not push them to repository. If the configurations object hasn’t changed, Git won’t commit it.

However, Today, the API response JSON configuration format may vary.
For instance

A list like [1,2,3,4] might be reordered as [2,3,1,4] when pulling configurations from the tenant.
The JSON response contains identical data, but the fields are rearranged. For instance, the name might appear first in one response, while the ID is listed first in the next response.

This variation prompts Git to treat it as a change and push the modifications.

AND SO ON…

I thought about but arranging JSON content and lists in ascending order can indeed require a significant amount of development effort.

I am investigating the libraries, we have some libraries that we can use or ask sailpoint to send us the response in the same order without rearranging the list or attributes.

Thanks
Raghu

svenkitachalam · March 29, 2024, 9:37pm

Yes, if we could get the response from SailPoint the same way all the time, that would be helpful.

Regarding the issue I ran into, I was able to find the cause of it. The issue is happening because of large size of $ConfigResponse. I believe its not able to store the entire string in that variable and gets truncated at some point losing the structure of JSON. If I give specific object to export, the code works fine. Something to optimize I guess.

Thanks,
Sreejith

anneragh · March 29, 2024, 9:40pm

@svenkitachalam How big is your configuration export?

svenkitachalam · March 29, 2024, 9:44pm

74502 lines. I updated the script to bring specific objects and brought the number of lines in the result to 16130 and the script worked.

Thanks,
Sreejith

anneragh · March 29, 2024, 9:56pm

@svenkitachalam - Thanks for providing the insights. I will try to reproduce this on my side with the large configuration files.

I will also add a new optional argument ConfigTypes for cmdlet Export-SpConfig . This will allow end users to pick and choose which configuration objects they want to export. This will help to break the big config file into small ones and also provide an option for users to choose the required configuration objects instead of pushing everything into git everytime.

$ConfigTypes = @("ACCESS_REQUEST_CONFIG","ATTR_SYNC_SOURCE_CONFIG","AUTH_ORG","CAMPAIGN_FILTER","FORM_DEFINITION","IDENTITY_OBJECT_CONFIG","IDENTITY_PROFILE","LIFECYCLE_STATE","NOTIFICATION_TEMPLATE","PASSWORD_POLICY","PASSWORD_SYNC_GROUP","PUBLIC_IDENTITIES_CONFIG","SERVICE_DESK_INTEGRATION","SOD_POLICY","SOURCE","TRANSFORM","TRIGGER_SUBSCRIPTION","WORKFLOWS") 

Export-SpConfig -OutputPath $Outpath -ConfigTypes $ConfigTypes