Download, Version, and Update IdentityNow Cloud Rules

At the moment, SailPoint IdentityNow doesn’t offer a way to review or download cloud rules within the UI. This can be problematic as it makes it difficult to know what rules are running in your tenant. In this blog, I will demonstrate how to use the SailPoint API to manage your cloud rules. With this approach, you can export all rules in your tenant to your computer, store them in version control, and upload updated rules back into your tenant.

Download all rules

A script has been developed to export all rules into separate XML files in a chosen folder. This script can be extremely helpful when you need to export and maintain version control on your rules.

Prerequisites

  1. Install the SailPoint Powershell SDK
  2. Install Powershell 6.2 or higher (required by the SDK)
  3. Obtain a clientID and clientSecret from a personal access token

How to execute the script

To call the script from the command line, open your command prompt or Powershell terminal, navigate to the folder where you saved Export-Rules.ps1, and run this command:

.\Export-Rules.ps1 -Path <pathToExport all your rules>

How the script works

The Powershell script performs the following actions:

  • Get all the rules in your tenant
  • For each rule, create a file in the given “path” with the rule code snippet.
  • This will export the rules as per the SailPoint file naming conventions.
    Rule - {type} - {name}.xml

For more details about how the script works, you can follow along with the comments in the code below.

<#  
      .About
        Export rules from the API and store them as Java files. In this script, the PSSailPoint module is only used to extract tokens to inline with other scripts.
		If you want you can just add one more API call to get an access token and remove the dependency
  #>

param(
        [Parameter(Mandatory=$true)][String]$Path
    )
#Import Custom Modules
Import-Module PSSailPoint


#InIt SailPoint IdentityNow Configuration
$PROXY = <proxy>
$env:SAIL_BASE_URL = <BASE_URL>
$env:SAIL_CLIENT_ID = <clientId>
$env:SAIL_CLIENT_SECRET = <clientSecret>

#load the environmental variable to the sailpoint config
$SailpointConfig=Get-DefaultConfiguration
#Get-access token
$TOKEN=Get-IDNAccessToken
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Authorization", "Bearer $TOKEN")
$response = Invoke-RestMethod "$($SailpointConfig.BaseUrl)cc/api/rule/list" -Method 'GET' -Headers $headers -Proxy $POWERSHELL_CONFIG.idn.proxy

if($response -and $response.count -gt 0){
	foreach($rule in $response.items){
		$xmlContent = @"
		<?xml version='1.0' encoding='UTF-8'?>
			<!DOCTYPE Rule PUBLIC "sailpoint.dtd" "sailpoint.dtd">
				<Rule name="$($rule.name)" type="$($rule.type)">
  				<Description>$($rule.description)</Description>
				<Source><![CDATA[

				$($rule.source)

				]]></Source>
</Rule>
"@
		$fileName="Rule - $($rule.type) - $($rule.name)"+".xml"
		$filePath=$OUTPUT_PATH + $fileName
		if(Test-Path $filePath){
			Remove-Item $filePath
		}
		Add-content -Path $filePath -Value $xmlContent
	}
}

Export-Rules.ps1 (1.6 KB)

Note: I used the SailPoint Powershell module to get an access token to inline with the other scripts that I have in my environment.

Version control the rules

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.

  • Open git bash
  • Navigate to the folder that has the exported Java files.
cd <folder path with all the java files>
  • Initialize a new Git repo for the first time.
git init 
  • To save changes to the git repository, run these commands:
git add .
git commit -am "Description of what you changed"
  • If you have a remote repository, you can push your changes to that remote repository with this command:
git push

Upload rule changes to SailPoint

  • Open the folder with all the rules that were exported by the script.
  • Open the file you want to modify and make the necessary changes. Make sure you only change the content/code snippet inside the XML element <source> </source>.
  • Commit your changes in your git repo.
  • SailPoint requires that all cloud rules must go through a rule review process with Professional Services. Here is the [process to upload rules to Sailpoint]((https://developer.sailpoint.com/idn/docs/rules/cloud-rules) and the best practices to follow.
  • Once the rule(s) are uploaded, you can repeat the process to pull the files.
6 Likes

This is a helpful script. Thanks Raghunath!.

1 Like

The script is really useful for downloading the rules in a user-friendly readable format and avoid the step to extract rules and unescaping characters

1 Like

I’m glad to hear that you find it helpful! @sharvari

Thank you, @smukhija! I am pleased to hear that.

It is very helpful !! Thanks @anneragh !!

1 Like

I’m glad to hear that you find it helpful! @IAMpdu

That’s really useful Raghunath!!

1 Like

The current version of this script has a couple of issues. First the PSSailPoint module does not have a Get-AccessToken cmdlet and there is a missing " after the “+” and before the “.xml”.

Thanks @jtharbison-slack I will update accordingly. When I was posted this Get-AccessToken was part of the SailPoint module - I will check this one.

It seems like the file is missing a quote, but it is available above in the document ($fileName=“Rule - $($rule.type) - $($rule.name)”+“.xml”). I will update it. Thank you for bringing this to my attention.

@anneragh This is great! I have a quick question: The script uses CC API to get the list of rules. CC APIs are going to go away after March 2024, is that correct? Without that API, can we still be able to use the script?

@sushant1 - Good Question!, I also have a same question. @colin_mckibben - Any insights?

Short answer: Try using sp config to export your rules.

Long answer: Still waiting for engineering to confirm if /cc/api/rule/list will have a direct public replacement or not. In the meantime, use sp config.

SP-Config only gets the connectors rules. For cloud rules only way is /cc/api/rule/list

Ah, thanks for pointing that out. I have made a note and will bring this feedback to engineering.

Thanks for sharing this.

2 Likes

Hi Colin,

Is there an update about this topic?

Yes, the deprecation announcement for /api/rule/list has confirmed that SP config will include cloud rules.

1 Like

We can deprecate this blog! It was needed when cloud rules were not part of the sp config and we were using CC API.

Now these rules are part of SP-Config.