SailPoint IdentityNow PowerShell Module

I’ve just published v1 of my SailPoint IdentityNow PowerShell Module. Don’t want to wait or read anymore? You can install it from the PowerShell Gallery

install-module -name SailPointIdentityNow
You can also download it from GitHub here and run the installer.
NOTE: This is not an official SailPoint IdentityNow PowerShell Module.

Features

  • Easy command-line use, after setting default configuration options and securely saving them to the current user’s profile.
  • Get an IdentityNow Organisation and Get / Update an Organisation Configuration
  • Search IdentityNow Users
  • Search IdentityNow Users Profiles
  • Search IdentityNow Entitlements
  • Create / Get / Update / Remove IdentityNow Access Profiles
  • Create / Get / Start IdentityNow Certification Campaigns
  • Get IdentityNow Certification Campaign Reports (output to file or return as PSObject)
  • Create / Get / Update / Remove IdentityNow Governance Groups
  • Create / Get / Update / Remove IdentityNow Roles
  • Get / IdentityNow Sources
  • Get Accounts from an IdentityNow Source
  • Create / Update / Remove IdentityNow Source Account (Flat File / Delimited Sources)
  • Get / Complete IdentityNow Tasks
  • Get IdentityNow Virtual Appliance Clusters (and clients (VA’s))
  • Get / Update IdentityNow Applications
  • …. and if they don’t fit use Invoke-IdentityNowRequest to make any other API call (examples for Get Source Schema, Get IdentityNow Identity Profiles, Get IdentityNow Identity Attributes)

Here is a quick overview of each of the cmdlets from the SailPoint IdentityNow PowerShell Module. As alluded to above they allow you to retrieve, update, create and remove IdentityNow elements.

Setting up the IdentityNow PowerShell Module Credentials and Organisation Configuration

The following cmdlets (Set-IdentityNowOrg, Set-IdentityNowCredential, Save-IdentityNowConfiguration) securely store the credentials required to operate the cmdlets in your PowerShell Profile. They will autoload each time you import the IdentityNow PowerShell module. If you are only integrating with one environment you only need to do this once per host you are using the module on.

NOTE: This module also requires a SailPoint Expert Services provided v3 API ClientID and Secret. Contact your SailPoint CSM to obtain them for your IdentityNow Organisation

Update the following example with your credentials and API keys. The credentials shown below aren’t real, but random chars in the indicative format. 

$orgName = "customername-sb"
Set-IdentityNowOrg -orgName $orgName

# IdentityNow Admin User
$adminUSR = "identityNow_admin_User"
$adminPWD = 'idnAdminUserPassword'
$adminCreds = [pscredential]::new($adminUSR, ($adminPWD | ConvertTo-SecureString -AsPlainText -Force))

# Customer IdentityNow Org v3 API Creds obtained from SailPoint Expert Services   
$clientIDv3 = "badbeef6-5f24-4448-ac0b-abcdefG"
$clientSecretv3 = "770a71abcdef5301848d00000d8760fe0d9f632383775b315aa1234567890"
$v3Creds = [pscredential]::new($clientIDv3, ($clientSecretv3 | ConvertTo-SecureString -AsPlainText -Force))

# Customer IdentityNow API Client ID & Secret generated in IdentityNow Portal
$clientID = 'zo7ABCDaTHjA0Rwv'
# Your API Client Secret
$clientSecret = '3Zm9Qod4sWhihABCdefgCX9DIfmwAZiP'
$v2Creds = [pscredential]::new($clientID, ($clientSecret | ConvertTo-SecureString -AsPlainText -Force))
Set-IdentityNowCredential -AdminCredential $adminCreds -v2APIKey $v2Creds -v3APIKey $v3Creds 

Save-IdentityNowConfiguration

Get an IdentityNow Organisation and Get / Update an Organisation Configuration

Display the configured IdentityNow Organisation as set by “Set-IdentityNowOrg
API endpoints for currently configured organisation – Example

Get-IdentityNowOrg

Name Value
---- -----
Organisation Name customer-sb
Organisation URI https://customer-sb.identitynow.com
v1 Base API URI https://customer-sb.identitynow.com/api
v2 Base API URI https://customer-sb.api.identitynow.com/v2
v3 / Private Base API URI https://customer-sb.api.identitynow.com/cc/api

Update an IdentityNow Organisation Setting – Example
[Reference post]

$orgConfig = Get-IdentityNowOrgConfig

$approvalConfig = $orgConfig.approvalConfig
# global reminders and escalation policies for access request approvals
$daysBetweenReminders = 3
$daysTillEscalation = 5
$maxReminders = 10
# SailPoint user name of the identity
$fallbackApprover = "darren.robinson"

# Set Config options to update
$approvalConfig.daysBetweenReminders = $daysBetweenReminders
$approvalConfig.daysTillEscalation = $daysTillEscalation
$approvalConfig.maxReminders = $maxReminders
$approvalConfig.fallbackApprover = $fallbackApprover
$approvalConfigBody = @{"approvalConfig" = $approvalConfig }

Update-IdentityNowOrgConfig -update ($approvalConfigBody | convertto-json)

Search IdentityNow Users

Search for IdentityNow Users – Examples
[Reference post]

Search-IdentityNowUsers -query darrenjrobinson
Search-IdentityNowUsers -query "@accounts(accountId:darren.robinson)"
Search-IdentityNowUsers -query "@source(id:2c91808469110d6a016954d4dad138a3)"
Search-IdentityNowUsers -query "@access(source.name:*Active Directory*) AND attributes.company:Kloud"

Search IdentityNow Users Profiles

Search for a user’s IdentityNow Profile from the IdentityNow Identity List – Example
[Reference post – See Profile Owner Section]

Search-IdentityNowUserProfile -query "darrenjrobinson"

Search IdentityNow Entitlements

Search for Entitlements associated with IdentityNow Sources – Example
[Reference post]

Search-IdentityNowEntitlements -query "File_Share_Sydney"

Create / Get / Update / Remove IdentityNow Access Profiles

Get all IdentityNow Access Profiles – Example
[Reference post]

Get-IdentityNowAccessProfile

Get a specific IdentityNow Access Profile – Example

Get-IdentityNowAccessProfile -profileID 2c91808369a606f00169c756f0a00017

Create an IdentityNow Access Profile – Example 1

New-IdentityNowAccessProfile -profile "{"entitlements": ["2c91808668dcf3970168dd722e7a020d","2c91808468dcf4610168dd78d2e8531e"],"description": "FS-SYDNEY-AUS-ENGINEERING","requestCommentsRequired": true,"sourceId": "39082","approvalSchemes": "manager","ownerId": "1397606","name": "Sydney Engineering","deniedCommentsRequired": true}"

Create an IdentityNow Access Profile – Example 2

# Get Owner for Access Profile
$owner = Search-IdentityNowUserProfile -query "darren.robinson"

# Get Source for Access Profile
$sources = Get-IdentityNowSource
$adSource = $sources | Select-Object | Where-Object {$_.name -like '*Active Directory*'}

# Entitlements
$entitlement = Search-IdentityNowEntitlements -query "FS-SYDNEY-AUS-ENGINEERING"
$e = $entitlement | Select-Object | Where-Object {$_.source.name -eq 'Active Directory'}

# Access Profile Details
$accessProfile = @{}
$accessProfile.add("name", "Sydney Engineering")
$accessProfile.add("description", "FS-SYDNEY-AUS-ENGINEERING")
$accessProfile.add("sourceId", $adSource.id)
$accessProfile.add("ownerId", $owner.id)

# Access Profile Entitlements
$entitlements = @()
ForEach($i in $e) {$entitlements += $i.id}
$entitlementsToAdd = @{"entitlements" = $entitlements}
$accessProfile.add("entitlements", $entitlementsToAdd.entitlements)

# Access Profile Type
$accessProfile.add("approvalSchemes", "manager")
$accessProfile.add("requestCommentsRequired", $true)
$accessProfile.add("deniedCommentsRequired", $true)

New-IdentityNowAccessProfile -profile ($accessProfile | convertto-json)

Update an IdentityNow Access Profile – Example 1

Update-IdentityNowAccessProfile -profileID 2c91808466a64e330112a96902ff1f69 -update "{"deniedCommentsRequired": true,"requestCommentsRequired": true}"

Update an IdentityNow Access Profile – Example 2

$ap = Get-IdentityNowAccessProfile
$accessProfile = $ap | Select-Object | Where-Object {$_.description -like '*Darren*'}

$updateAccessProfile = @{}
$updateAccessProfile.Add("requestCommentsRequired", $true)
$updateAccessProfile.Add("deniedCommentsRequired", $true)

Update-IdentityNowAccessProfile -profileID $accessProfile.id -update ($updateAccessProfile | convertto-JSON)

Remove an IdentityNow Access Profile – Example 1

Remove-IdentityNowAccessProfile -profileID 2c91808369a606f00169c756f0a00017

Remove an IdentityNow Access Profile – Example 2

$ExistingAPs = Get-IdentityNowAccessProfile
$myAP = $ExistingAPs | Select-Object | Where-Object {$_.name -like "*My Access Profile*"}
Remove-IdentityNowAccessProfile -profileID $myAP.id

Create / Get / Start IdentityNow Certification Campaigns

Get all (active and completed) IdentityNow Certification Campaigns – Example
[Reference post]

Get-IdentityNowCertCampaign -completed $false

Get a specific IdentityNow Certification Campaign – Example

Get-IdentityNowCertCampaign -campaignID 2c9180856708ae38016709f4812345c3

Create an IdentityNow Certification Campaign – Example
[Reference post]

$query = "@apps.name:'Special Application'"
$campaignFilter = Search-IdentityNowUsers -query $query

$entitlements = $null
$e = $campaignFilter.access | where-object { $_.type -eq "ENTITLEMENT" } | Select-Object id
$entitlements = $e | Select-Object -Property id -Unique

$roles = $null
$r = $campaignFilter.access | where-object { $_.type -eq "ROLES" } | Select-Object id
$roles = $r | Select-Object -Property id -Unique

$accessProfiles = $null
$a = $campaignFilter.access | where-object { $_.type -eq "ACCESS_PROFILE" } | Select-Object id
$accessProfiles = $a | Select-Object -Property id -Unique

$inclusionList = @()

$InclusionTemplate = [pscustomobject][ordered]@{
id = $null
type = $null
}

# ROLES
foreach ($role in $roles) {
$incRole = $InclusionTemplate.PsObject.Copy()
$incRole.id = $role.id
$incRole.type = "ROLE"
$inclusionList += $incRole
}

# ENTITLEMENTS
foreach ($entitlement in $entitlements) {
$incEntitlement = $InclusionTemplate.PsObject.Copy()
$incEntitlement.id = $entitlement.id
$incEntitlement.type = "ENTITLEMENT"
$inclusionList += $incEntitlement
}

# ACCESS PROFILES
foreach ($accessProfile in $accessProfiles) {
$incAccessProfile = $InclusionTemplate.PsObject.Copy()
$incAccessProfile.id = $accessProfile.id
$incAccessProfile.type = "ACCESS_PROFILE"
$inclusionList += $incAccessProfile
}

$e = $inclusionList | select-object -Property type | Where-Object { $_.type -eq "ENTITLEMENT" }
$a = $inclusionList | select-object -Property type | Where-Object { $_.type -eq "ACCESS_PROFILE" }
$r = $inclusionList | select-object -Property type | Where-Object { $_.type -eq "ROLE" }

write-host -ForegroundColor Blue "Campaign scope covers $($r.type.count) Role(s), $($e.type.count) Entitlement(s) and $($a.type.count) Access Profile(s)."

# Create Campaign
$campaignOptions = @{ }
$campaignOptions.Add("type", "Identity")
$campaignOptions.Add("timeZone", "GMT+1000")
$campaignOptions.Add("name", "Oct 2019 Special App Campaign")
$campaignOptions.Add("allowAutoRevoke", $false)
$campaignOptions.Add("deadline", "2019-11-1")
$campaignOptions.Add("description", "Special App Oct 2019")
$campaignOptions.Add("disableEmail", $true)
$campaignOptions.Add("identityIdList", @())
$campaignOptions.Add("identityQueryString", $query )
$campaignOptions.Add("accessInclusionList", $inclusionList)
$campaignBody = $campaignOptions | ConvertTo-Json

New-IdentityNowCertCampaign -start $true -campaign $campaignBody

Get IdentityNow Certification Campaign Reports

Get all certification campaign reports from the last year and output them to a local folder – Example
[Reference post]

Get-IdentityNowCertCampaignReport -period "365" -outputPath "C:\Reports"

Get certification campaign reports for a specific campaign and return as PSObject – Example

Get-IdentityNowCertCampaign -campaignID '2c918085694a507f01694b9fcce6002f'

Create / Get / Update / Remove IdentityNow Governance Groups

Get IdentityNow Governance Groups – Example
[Reference post]

Get-IdentityNowGovernanceGroup

Get a specific IdentityNow Governance Group – Example

Get-IdentityNowGovernanceGroup -groupID 4fc249bd-46ff-405a-93b9-21372f97c352

Update an IdentityNow Governance Group to remove one member and add two members – Example

# Get Group
$govGroups = Get-IdentityNowGovernanceGroup
$myGroup = $govGroups | Select-Object | Where-Object { $_.description -like "*My IDN Governance Group*" }

# Add
$user1 = Search-IdentityNowUsers -query "@accounts(accountId:darren.robinson)"
$user2 = Search-IdentityNowUsers -query "@accounts(accountId:rick.sanchez)"
$user3 = Search-IdentityNowUsers -query "@accounts(accountId:morty.smith)"

$add = @()
$remove = @()
$add += $user3.id
$add += $user2.id
$remove += $user1.id

$update = (@{
add = $add
remove = $remove
})

Update-IdentityNowGovernanceGroup -groupID $myGroup.id -update ($update | convertto-json)

Create an IdentityNow Governance Group and assign an owner – Example

$GovGroupOwner = Search-IdentityNowUsers -query "@accounts(accountId:darren.robinson)"

$body = @{"name" = "New IDN Module Gov Group";
"displayName" = "New Module Gov Group";
"description" = "New Module Gov Group";
"owner" = @{"displayName" = $GovGroupOwner.displayName;
"emailAddress" = $GovGroupOwner.email;
"id" = $GovGroupOwner.id;
"name" = $GovGroupOwner.name
}
}
New-IdentityNowGovernanceGroup -group ($body | convertto-json)

Delete an IdentityNow Governance Group – Example

Remove-IdentityNowGovernanceGroup -groupID 4fc249bd-46ff-405a-93b9-21372f97c352

Create / Get / Update / Remove IdentityNow Roles

Get IdentityNow Roles – Example
[Reference post]

Get-IdentityNowRole

Get a specific IdentityNow Role – Example

Get-IdentityNowRole -roleID 2c918084691653af01695182a78b05ec

Update an IdentityNow Role – Example
[Reference post]

$body = @{
"id" = "2c9180886cd58059016d1a4757d709a4"
"name" = "Role - Special Admins";
"displayName" = "Special Admins";
"description" = "Special Admins Role";
"disabled" = $false;
"owner" = "darrenjrobinson"
}
Update-IdentityNowRole -update ($body | convertto-json)

Create an IdentityNow Role – Example

$body = @{
"name" = "Role - Special Administrators";
"displayName" = "Special Administrators";
"description" = "Special Administrators Role";
"disabled" = $true;
"owner" = "darrenjrobinson"
}

New-IdentityNowRole -role ($body | convertto-json)

Delete an IdentityNow Role – Example

Remove-IdentityNowRole -roleID 2c9180886cd58059016d1a5a23f609a8

Get / IdentityNow Sources

Get all IdentityNow Sources – Example
[Reference post]

Get-IdentityNowSource

Get a specific IdentityNow Source – Example

Get-IdentityNowSource -sourceID 12345

Get Accounts from an IdentityNow Source

Get accounts from an IdentityNow Source – Example
[Reference post]

Get-IdentityNowSourceAccounts -sourceID 40113

Create / Update / Remove IdentityNow Source Account (Flat File / Delimited Sources)

Create an account on an indirect IdentityNow Source – Example
[Reference post]

$account = @{"id" = 'darrenjrobinson';
"name" = 'darrenjrobinson';
"givenName" = 'Darren';
"familyName" = 'Robinson';
"displayName" = 'Darren Robinson';
"email" = 'darren.robinson@customer.com.au'
}

New-IdentityNowUserSourceAccount -source 36702 -account ($account | convertto-json)

Update an account on an indirect IdentityNow Source – Example
[Reference post]

$update = @{
"country" = "Australia"
"department" = "Identity Architects"
"organization" = "Kloud"
}

Update-IdentityNowUserSourceAccount -account 2c91808469110d6a016954d4dad138a3 -update ($update | ConvertTo-Json)

Delete an IdentityNow account from an indirect IdentityNow Source – Example (assumes user only has a single account on an indirect source)
[Reference post]

$user = Search-IdentityNowUsers -query "@accounts(accountId:darrenjrobinson)"
$userIndirectAccounts = $user.accounts | select-object | where-object { ($_.source.type.contains("DelimitedFile")) }
$account = $userIndirectAccounts.id

Remove-IdentityNowUserSourceAccount -account $account

Get / Complete IdentityNow Tasks

Get IdentityNow Tasks – Example
[Reference post]

Get-IdentityNowTask

Get a specific IdentityNow Task – Example

Get-IdentityNowTask -taskID 2c918084691120d0016926a6a94251d6

Mark and IdentityNow Task as complete – Example

Complete-IdentityNowTask -taskID 2c918084691120d0016926a6a94251d6

Get IdentityNow Virtual Appliances & Clusters

Get IdentityNow Virtual Appliance Clusters – Example
[Reference post]

Get-IdentityNowVACluster

Get IdentityNow Virtual Appliances from a cluster – Example

$clusters = Get-IdentityNowVACluster
foreach($va in $clusters){
"Cluster: $($va.description) VA ID: $($va.clients.id) VA Description: $($va.client.description)"
}

Get / Update IdentityNow Applications

Get IdentityNow Customer Created and Managed Applications – Example
[Reference post]

Get-IdentityNowApplication

Get IdentityNow Customer default configured SailPoint Applications – Example

Get-IdentityNowApplication -org $true

Get a specific IdentityNow Applications – Example

Get-IdentityNowApplication -appID 32128

Update an IdentityNow Application – Example

$appBody = @{
"launchpadEnabled" = $false
"provisionRequestEnabled" = $false
"appCenterEnabled" = $false
}
Update-IdentityNowApplication -appID 24188 -update ($appBody | ConvertTo-Json)

Initiate Aggregation of an IdentityNow Source

Aggregate an IdentityNow Source – Example
[Reference post]

Invoke-IdentityNowAggregateSource -sourceID 12345

Aggregate an IdentityNow Source without optimization – Example
[Reference post]

Invoke-IdentityNowAggregateSource -sourceID 12345 -disableOptimization $true

And the ultimate flexible cmdlet Invoke-IdentityNowRequest

The cmdlet that lets you do your thing, with a little help. This cmdlet has options for v2 and v3 authentication and will provide the web request headers (with and without content-type = application/json set). You supply the URI for the request, the method (POST, GET, DELETE, PATCH) and the request will be sent, and the results sent back.

Request Methods are;

  • Get
  • Put
  • Patch
  • Delete
  • Post

Header options are;

  • HeadersV2 – Headersv2 Digest Auth with no Content-Type set
  • HeadersV3 – Headersv3 is JWT oAuth with no Content-Type set
  • Headersv2_JSON – Headersv2_JSON is Digest Auth with Content-Type set for application/json
  • Headersv3_JSON – Headersv3_JSON is JWT oAuth with Content-Type set for application/json

Example 1 – Get the Schema of a Source
[Reference post]

$orgName = "customer-sb"
$sourceID = "12345"
Invoke-IdentityNowRequest -Method Get -Uri "https://$($orgName).api.identitynow.com/cc/api/source/getAccountSchema/$($sourceID)" -headers HeadersV3

Example 2 – List Identity Profiles
[Reference post]

$orgName = "customer-sb"
Invoke-IdentityNowRequest -Method Get -Uri "https://$($orgName).identitynow.com/api/profile/list" -headers Headersv2_JSON

Example 3 – Get IdentityNow Identity Attributes
[Reference post]

$orgName = "customer-sb"
Invoke-IdentityNowRequest -Method Get -Uri "https://$($orgName).api.identitynow.com/cc/api/identityAttribute/list" -headers HeadersV3

Enjoy.