Managing SailPoint IdentityNow Sources via the API with PowerShell

Back again with another post in my series detailing accessing SailPoint IdentityNow via the API using the unpublished and undocumented APIs. Previous posts detail;

This post also assumes you are able to access the IdentityNow APIs as detailed in this post here. You will need to use that process to access the Sources APIs. You will also need to update the Headers for “Content-Type” for the Get API calls and again for the Post API call. Add this line to your script to allow the query and return of Source Details

$Global:IDN.Headers.Remove("Content-Type")

This post details:

  • Getting a List of Sources
  • Getting the Details of a Source
  • Getting the Schema of a Source
  • Updating the Details of a Source

Getting a List of Sources

https://$($orgName).api.identitynow.com/cc/api/source/list

The API call shown above will return all Sources configured in the queried IdentityNow Tenant. For each Source a limited set of configuration information is returned. Below is an example for a Delimited File Source File Source Type.

id : 36666
version : 2
name : Privileged Access Management
description : Cyberark PAM
owner :
lastUpdated : 2018-10-05T00:39:33Z
scriptName : delimitedfile
definitionName : Delimited File
appCount : 0
userCount : 0
sourceConnected : False
sourceConnectorName : Delimited File
supportsEntitlementAggregation : true
externalId : 2c918086663fbbc0016641aa51041603
icon : https://files.accessiq.sailpoint.com/modules/builds/static-assets/perpetual/identitynow/icons/2.0/source/
health : @{hostname=564c355e916f; lastSeen=1538699972555; org=orgName; healthy=True; lastChanged=1538699972555;
isAuthoritative=false; id=36777; type=C:173-delimited-file; status=SOURCE_STATE_UNCHECKED_SOURCE_NO_ACCOUNTS;
since=1494370939}
sourceType : DELIMITED_FILE
useForAuthentication : False
useForAccounts : False
useForProvisioning : False
useForPasswordManagement : False
iqServiceDownloadUrl : https://files.accessiq.sailpoint.com/integrations/iqservice/IQService.zip

PowerShell Example

The following will return the list of Sources in an IdentityNow Tenant where $orgName is the Organisation Name for your IdentityNow Tenant.

$IDNSources=Invoke-RestMethod-Method Get -Uri "https://$($orgName).api.identitynow.com/cc/api/source/list"-WebSession $IDN
write-host -ForegroundColor Green "$($IDNSources.Count) Sources found"

Getting the Details of a Source

https://$($orgName).api.identitynow.com/cc/api/source/get/$($sourceID)

The API call shown above will return all the details for the specified Source. Below is an example of the full details for the same Delimited File Source File Source Type above.

id : 36666
version : 3
name : Privileged Access Management
description : Cyberark PAM 
owner : @{id=1084412; name=IDN Admin}
lastUpdated : 2018-10-22T21:29:12Z
scriptName : delimitedfile
definitionName : Delimited File
appCount : 0
userCount : 0
sourceConnected : False
sourceConnectorName : Delimited File
supportsEntitlementAggregation : true
externalId : 2c918086663fbbc0016641aa51041603
icon : https://files.accessiq.sailpoint.com/modules/builds/static-assets/perpetual/identitynow/icons/2.0/source/
health : @{hostname=564c355e916f; lastSeen=1538699972555; org=orgName; healthy=True; lastChanged=1538699972555;
isAuthoritative=false; id=36777; type=C:173-delimited-file; status=SOURCE_STATE_UNCHECKED_SOURCE_NO_ACCOUNTS;
since=1547135418}
sourceType : DELIMITED_FILE
useForAuthentication : False
useForAccounts : False
useForProvisioning : False
useForPasswordManagement : False
iqServiceDownloadUrl : https://files.accessiq.sailpoint.com/integrations/iqservice/IQService.zip
entitlementsCount : 0
accountsCount : 0
connector_featuresString : DIRECT_PERMISSIONS, NO_RANDOM_ACCESS, DISCOVER_SCHEMA
hasValidAccountProfile : False
correlationConfig : @{attributeAssignments=; id=; name=}
sourceConfigFrom : Mantis Config: Cloud Connector
isAuthoritative : False
accessProfilesCount : 0
connector_delimiter : ,
connector_commentCharacter : #
connector_numberOfLinesToSkip :
connector_filterString :
cloudDisplayName : Privileged Access Management
cloudExternalId : 36777
cloudOriginalApplicationType : Delimited File
deleteThresholdPercentage : 10
file : /var/lib/identityiq_workspace/f8001b46-4fab-4e0b-ad15-18f53dc1507c-accounts.csv
filetransport : local
filterEmptyRecords : True
formPath :
group.columnNames : {id, name, displayName, created...}
group.delimiter : ,
group.file : /var/lib/identityiq_workspace/156524b6-9513-404c-8063-40275edfa575-groups.csv
group.filetransport : local
group.filterEmptyRecords : True
group.hasHeader : True
group.host : local
group.indexColumn : id
group.mergeColumns : {entitlements, groups, permissions}
group.mergeRows : True
group.partitionMode : disabled
hasHeader : True
host : local
indexColumn : id
managerCorrelationFilter :
mergeColumns : {groups}
mergeRows : True
partitionMode : disabled
templateApplication : DelimitedFile Template

PowerShell Example

The following will return the details for all sources in an IdentityNow Tenant where $orgName is the Organisation Name for your IdentityNow Tenant and IDNSources is the collection of Sources returned from the List Sources API call above.

foreach ($idnSource in $IDNSources){
    # Get Source Details
    $sourceInfo=Invoke-RestMethod-Method Get -uri "$($sourceDetailsURI)/$($idnSource.id)"-WebSession $IDN
    $sourceInfo
}

Getting the Schema of a Source

https://$($orgName).api.identitynow.com/cc/api/source/getAccountSchema/$($sourceID)

The API call shown above will return the Schema for the specified Source. Below is an example of the Schema for the same Delimited File Source File Source Type above.

attributes : {@{description=The unique ID for the account; displayAttribute=False; entitlement=False; identityAttribute=True; managed=False;
    minable=False; multi=False; name=id; type=string}, @{description=The name of the account - typical username etc;
    displayAttribute=True; entitlement=False; identityAttribute=False; managed=False; minable=False; multi=False; name=name;
    type=string}, @{description=The first or given name of the user associated with the account; displayAttribute=False;
    entitlement=False; identityAttribute=False; managed=False; minable=False; multi=False; name=givenName; type=string},
    @{description=The last, family name, or surname of the user associated with the account; displayAttribute=False; entitlement=False;
    identityAttribute=False; managed=False; minable=False; multi=False; name=familyName; type=string}...}
displayAttribute : name
groupAttribute : groups
identityAttribute : id
nativeObjectType : User
objectType : account

PowerShell Example

The following will return the schema for all sources in an IdentityNow Tenant where $orgName is the Organisation Name for your IdentityNow Tenant and IDNSources is the collection of Sources returned from the List Sources API call above.

foreach ($idnSource in $IDNSources){
   # Get Source Schema Details
   $sourceSchema=Invoke-RestMethod-Uri "$($sourceSchemaURI)/$($source.id)"-WebSession $IDN
   $sourceSchema
}

Updating  the Details for a Source

https://$($orgName).api.identitynow.com/cc/api/source/update/$($sourceID)

The API endpoint above is called to update the Details for a Source. In conjunction with calling the API endpoint a Body needs to be provided to update the Source Details. Below is an example of updating the Owner and the Description of a Source.

Notes:

  • The Content-Type needs to be updated for “application/x-www-form-urlencoded; charset=UTF-8”
  • You only need to specify the attributes you wish to change and append them to each other with the separator ‘&
  • The body with the udpate(s) needs to be URLEncoded. PowerShell Invoke-RestMethod handles that
$sourceUpdateURI = "https://$($orgName).api.identitynow.com/cc/api/source/update"
$Global:IDN.Headers.Add('Content-Type', "application/x-www-form-urlencoded; charset=UTF-8")
$sourceID=$idnSource.id
$sourceDesscription = "CyberArk"
$sourceOwnerID = "1089912"
$sourceDetailsBody = "description=$($sourceDesscription)&ownerId=$($sourceOwnerID)"
$updateSource = Invoke-RestMethod -Method Post -Uri "$($sourceUpdateURI)/$($sourceID)" -Body $sourceDetailsBody -WebSession $Global:IDN

If you set a variable to the POST webRequest you get the updated object returned following a successful update. A snippet of the response is below. The version updates with each update.

id : 36666
version : 7
name : Privileged Access Management
description : CyberArk
owner : @{id=1089123; name=Bob Smith}
lastUpdated : 2018-10-23T01:15:26Z
scriptName : delimitedfile
definitionName : Delimited File

Summary

In this post I showed using PowerShell to access the Sources APIs to List Sources, Get full details for a Source, Get the Schema of a Source and Update the Details for a Source. In my next post I’ll show generating HTML Reports for the configuration of Sources.

Here is the snippet of the calls as listed in this post. As per the introduction it assumes you are authenticated and re-using your WebSession.