This week as part of the SailPoint Developer Days 2023 conference the SailPoint Developer Relations team proudly announced the official SailPoint IdentityNow PowerShell SDK. They also announced Typescript and Go, but I’m sure you’re here for PowerShell.
I was very proud to be included in the announcement with Jordan Violet the head of Developer Relations at SailPoint and then followed up by Philip Ellis who gave an overview of the SDKs. I was lucky enough to get a heads-up on the SDKs and early access to them to provide some feedback to the team, especially of course on the PowerShell SDK.
This post will give my quick start guide to getting started with the PowerShell SDK so you too can start using it. Keep in mind, these SDKs are very fresh and as the IdentityNow APIs themselves continue to evolve the SDKs will be automatically generated and refined.
SailPoint CLI
The SailPoint SDKs all leverage the SailPoint CLI. You can find the latest version of the SailPoint CLI here. Download the version for your architecture. Being on Windows that is the Windows AMD 64bit binary for me. Uncompress the archive and put the sail.exe binary in the same directory you will create your PowerShell script.
Once you’re up and running you may consider putting sail.exe into a location in your system environment paths or add the location to your path environment.
Whilst the PowerShell module leverages the CLI to perform your automations, the CLI can also be used to quickly configure your environment and authentication.
Firstly, you need to specify the environment (your IdentityNow Tenant).
We do that using the SailPoint CLI and the sail.exe environment command.
Provide your IdentityNow tenant name and URIs.
.\sail.exe environment
Now with your IdentityNow Personal Access Token (PAT) credentials handy run ‘sail.exe configure‘. Provide your PAT Client ID and Client Secret.
That’s it. The CLI is now configured with your credentials that will persist between restarts as the CLI stores the configuration in your home directory.
Building and importing the SailPoint IdentityNow PowerShell SDK
Clone the latest PowerShell SDK from the GitHub repo here and extract to your local development machine.
Build and import the PowerShell Module.
.\PSSailpoint\Build.ps1
import-module .\PSSailpoint\PSSailpoint.psm1
List the Get cmdlets using the following command. You can use a similar command to find cmdlets based on the function of them. e.g., Accounts, Profiles, Groups, Search.
Get-Command -Module PSSailpoint | where-object {$_.name -like "*Get-*" | Sort-Object Name | Get-Help | Format-Table Name, Synopsis -Autosize
Using the SailPoint IdentityNow PowerShell SDK Module
You’re now ready for action. You’ve configured the SailPoint CLI with your Tenant and Personal Access Token details. You’ve cloned and imported the PowerShell SDK Module. Now let’s use it. The key starting point is finding the right cmdlet for what you want to do. I’ve found the best way to do that is to use the Get-Command PowerShell command.
Get-Command -Module PSSailpoint | where-object {$_.name -like "Get-*Source*"} | Sort-Object Name | Get-Help | Format-Table Name, Synopsis -Autosize
Get Sources
Using the example above for Sources, knowing we want to “get” the sources from our IdentityNow environment let’s find the right cmdlet. We have cmdlets to use both the Beta and v3 APIs for getting information about our sources. We’ll use Get-Sources to return all sources.
Rather than outputting all the information about all sources let’s give a few more parameters to list the key details. List the sources with their name, type, description and id.
get-sources | Select-Object -Property name, type, description, id | Sort-Object name | Format-List
Taking that one step further we could see earlier there is a Get-Source cmdlet. Using IntelliSense we can see it needs an Id parameter which we now have.
Getting and updating other IdentityNow entities
Using a similar method, you can now find the right cmdlet to get other Identity entities such as groups, profiles, etc. For any of the IdentityNow entities, but even more so for search and updating entities look to the API reference documentation to understand what the format and requirements of the associated APIs are. The cmdlets are automatically generated from the API specifications.
Summary
SailPoint in the last few years have gone from a standing start with respect to developer relations to now having an awesome team delivering on a consistent cadence bring improvements to the development capabilities of IdentityNow. They are a fantastic team, that do care about what they do and the SailPoint developer community. They’ve taken a lot of feedback over the last few years and it’s both refreshing and inspiring to see the fruits of their efforts coming to the public forums.
Finally, do you want to contribute to the SDK, provide examples, or fix something that is broken? Submit Issues and PRs on GitHub.