PowerShell SDK
Read this guide to learn how to use the PowerShell SDK. The PowerShell SDK has some pre-built code examples you can use to learn how to build tools that can interact with IdentityNow.
Requirements
You need the following to use the PowerShell SDK:
-
PowerShell 6.2 or greater. To learn how to install, refer to Installing PowerShell.
-
Your tenant name in IdentityNow. To learn how to find it, refer to Getting Started. The SDK will use this tenant name to connect to your IdentityNow instance.
-
A PAT with a client secret and ID. To learn how to create one in ISC, refer to Personal Access Tokens. The SDK will use this PAT to authenticate with the SailPoint APIs.
Setup
CLI Assisted (Recommended)
The SailPoint CLI offers a few commands that will allow you to quickly get started with the PowerShell SDK. To learn how to install and use the SailPoint CLI, refer to SailPoint CLI.
Once the CLI is installed and configured, run this command to create a new PowerShell project with the PowerShell SDK:
sail sdk init powershell
Running the command create the structure for your project:
|-- powershell-template
| |-- paginate.ps1
| |-- paginateAccounts.ps1
| |-- patchEntitlement.ps1
| |-- sdk.ps1
| |-- search.ps1
| |-- transform.ps1
Run this command to install the required dependencies:
Install-Module -Name PSSailpoint
The command installs the SailPoint PowerShell SDK module. You will be prompted to confirm that you want to install the module from 'PSGallery'. Enter "A" to say "Yes to All".
If you already have a version of the PowerShell SDK installed, you can install a new version side-by-side with it by adding the -Force
parameter to the end of your Install-Module
commmand:
Install-Module -Name PSSailpoint -Force
To validate that the module is installed, run this command, Get-Module -ListAvailable PSSailpoint
, and verify that the module is listed. Additionally, you can run this command, Get-Command -Module PSSailpoint
, to see the available commands included in the module.
The SDK is now installed. To learn how to configure the SDK, refer to the Configure section.
Manual Installation
Manually install the SDK
If access to the PowerShell Gallery isn't available, you can also install the PowerShell SDK manually.
If you manually install the module on a machine without access to the PowerShell Gallery, you will also need to manually install updates to the SDK.
Follow these steps to manually install the PowerShell module:
- Download the source code zip from the most recent release on GitHub.
- Open the ZIP file, then open then folder labeled
powershell-sdk-x.x.x
, with thex.x.x
representing the version you downloaded. - Extract the
PSSailpoint
module folder inside to one of the following locations:- To install for the Current user:
C:\Users\<username>\Documents\WindowsPowerShell\Modules\PSSailpoint
- To install for All users (requires Administrator privileges):
C:\Program Files\WindowsPowerShell\Modules\PSSailpoint
- To install for the Current user:
- Run
Import-Module PSSailpoint
to import the module into the current session. - To validate that the module is installed, run
Get-Module -ListAvailable PSSailpoint
and verify that the module is listed. Additionally, you can runGet-Command -Module PSSailpoint
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
You must provide configuration to the SDK so that it can authenticate to your SailPoint tenant and make API calls. To do so, you can use a configuration file, config.json
, or environment variables.
Configuration File
The SDK requires a configuration file to be named "config.json". Within the file, provide these key/value pairs: ClientId
, ClientSecret
, BaseURL
.
Details
CLI Assisted (Recommended)
The SailPoint CLI offers a command to generate the config.json file with your currently configured CLI credentials.sail sdk init config
If you have multiple environments configured with the CLI, you can pass an additional parameter to state the environment you wish to create a config.json
for.
To pass an additional parameter that states the environment you want to configure, run this command:
sail sdk init config --env devrel
Example config.json
{
"ClientId": "g0567b766b413b22c05c66e75d532f1b",
"ClientSecret": "cabd0e950a7230b63c1ff45be33fb22065b382b6251a73c61177a8bb5482fcc7",
"BaseURL": "https://[tenant].api.identitynow.com"
}
Manual Configuration
Create a file named "config.json", and provide these key/value pairs: ClientId
, ClientSecret
, BaseURL
.
Example config.json
{
"ClientId": "g0567b766b413b22c05c66e75d532f1b",
"ClientSecret": "cabd0e950a7230b63c1ff45be33fb22065b382b6251a73c61177a8bb5482fcc7",
"BaseURL": "https://[tenant].api.identitynow.com"
}
Please ensure this file is ignored in your version control system (ex. .gitignore for git)
Environment variable configuration
You can also store your configuration in environment variables.
To get your environment variables to persist across terminal sessions, add these exports to your shell profile, something like ~/.bash_profile
.
- Linux/Mac
- Windows PowerShell
export SAIL_BASE_URL=https://[tenant].api.identitynow.com
export SAIL_CLIENT_ID=[clientID]
export SAIL_CLIENT_SECRET=[clientSecret]
$env:SAIL_BASE_URL=https://[tenant].api.identitynow.com
$env:SAIL_CLIENT_ID=[clientID]
$env:SAIL_CLIENT_SECRET=[clientSecret]
To get your environment variables to persist across PowerShell sessions, run these commands instead:
[System.Environment]::SetEnvironmentVariable('SAIL_BASE_URL','https://[tenant].api.identitynow.com')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_ID','[clientID]')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_SECRET','[clientSecret]')
Discuss
You can use this SDK to build new tools that extend your ISC platform and improve experiences across your organization. Use this guide to get started, and if you have questions, don't hesitate to reach out on the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss!
Getting Started
To get started using the SDK, refer to the Getting Started Guide.