SailPoint Archives - Bespoke learnings from an Identity & Access Management Consultant

January 16, 2019January 15, 2019

Managing SailPoint IdentityNow Tasks with PowerShell

Sailpoint IdentityNow Tasks via API using PowerShell

In SailPoint IdentityNow when using the Request Center, tasks are created for activities that are not able to be automatically (directly) fulfilled. Essentially completion of the request requires someone to do something, then return to the IdentityNow Portal and flag the Task as complete. What if we want to see what Tasks are open and flag them as complete through external automation?

Well, this SailPoint IdentityNow Compass article gives the only background to using the API to get visibility of Tasks. But what we needed to do was;

enumerate Tasks that were pending for Flat File Sources
understand the pending operations and complete them
mark the Task(s) as complete

This post will cover the first and last bullet points. The performing the operation will be dependent on what you have integrated with and what is being requested for an Entitlement.

Prerequisites

I’m using a v3 Token to access the IdentityNow API’s. I detailed that in this post here. If you don’t have API keys for the v3 endpoint you can use this method to get the oAuth JWT Token. You will also need to make sure that you don’t have any Content-Type set in your headers. If you do then you will get an error message like this;

Missing or invalid arguments

Enumerating all Tasks

To enumerate all tasks we need to call the API /task/listAll. Using PowerShell and the access token from one of the methods listed in the prerequisites we can make the following call.

$orgName = "myOrgName"
$tasksURI = "https://$($orgName).identitynow.com/api/task/listAll"
$tasksList = Invoke-RestMethod -method Get -uri $tasksURI -Headers @{Authorization = "$($v3Token.token_type) $($v3Token.access_token)"}
$tasksList.items

A task then looks like this;

Searching for and retrieving an Individual Task

To retrieve an individual task we need to know the ID of the task. If we know what we are looking for we can use PowerShell to locate the specific task, get the ID then get that individual task.

The following command shows looking through the Task items and finding tasks that are ManualAction, are not completed and contain Luke in the description.

$manualActions = $tasksList.items | select-object | Where-Object {$_.type -eq "ManualAction" -and $_.complete -eq $false -and $_.description -like "*Luke*"}
$taskID = $manualActions.id

With our Task identified we can then retrieve it using the API /task/get/{taskID}

$utime = [int][double]::Parse((Get-Date -UFormat %s))
$getIdvTaskbyIDURI = "https://$($orgName).api.identitynow.com/cc/api/task/get/$($taskID)?_dc=$($uTime)"
$indvTask = Invoke-RestMethod -method Get -uri $getIdvTaskbyIDURI -Headers @{Authorization = "$($v3Token.token_type) $($v3Token.access_token)"}
$indvTask

Looking at it, it is the one we wanted.

Completing a Task

With the task ID we can then update the Task and mark it as completed. To complete the task we make a POST request to task/complete/{taskID}

$completeTaskURI = "https://$($orgName).api.identitynow.com/cc/api/task/complete/$($taskID)"
$completeTask = Invoke-RestMethod -method Post -uri $completeTaskURI -Headers @{Authorization = "$($v3Token.token_type) $($v3Token.access_token)"}
$completeTask

The API will return the object on Success.

Looking in the IdentityNow Portal we can see that the Task is showing as Completed.

Summary

Using the IdentityNow Task API’s we can get a list of Tasks, search and find the task we are looking for and retrieve all the details it before finally updating the status of the Task to complete.

December 18, 2018December 17, 2018

Using SailPoint IdentityNow v3 API’s with PowerShell

The SailPoint IdentityNow SaaS product is evolving. I’ve previously posted about integrating with the IdentityNow API’s using PowerShell;

IdentityNow now has v3 API’s which are essentially the v2 and non-Published API’s with the added benefit of being able to obtain an oAuth token from a new oAuth Token endpoint. Unlike the v2 process for enabling API integration, v3 currently requires that SailPoint generate and provide you with the ClientID and Secret. This Compass document (at the very bottom) indicates that this will be the preferred method for API access moving forward.

The process to get an oAuth Token the process is;

Generate Credentials using your IdentityNow Admin Username and Password as detailed in my v1 Private API post
- Lines 1-12
Use the credentials from the step above in the oAuth token request
Use the ClientID and Secret as Basic AuthN to the Token endpoint
Obtain an oAuth Token contained in the resulting $Global:v3Token variable

Authentication Script

Update:

Line 2 with your Org name
Line 5 with your Admin Login Name
Line 6 with your Admin Password
Line 15 with your SailPoint supplied ClientID
Line 16 with your SailPoint supplied Secret

Your resulting token will then look like this;

SailPoint v3 API oAuth Token.PNG

Using the v3 oAuth Access Token

So far I’ve found that I can use the oAuth Token to leverage the v2 and non-published API’s simply by using the JWT oAuth Token in the Header of the webrequest e.g

@{Authorization = "Bearer $($Global:v3Token.access_token)"}

Depending on which API you are interacting with you may also require Content-Type e.g

@{Authorization = "Bearer $($Global:v3Token.access_token)"; "Content-Type" = "application/json"}

Summary

Talk to your friendly SailPoint Support Rep and get your v3 API ClientID and Secret and discard this previous hack of scraping the Admin Portal for the oAuth Token saving a few hundred lines of code.

December 17, 2018January 1, 2019

Enabling Requestable Roles in SailPoint IdentityNow using PowerShell

Recently I wrote this post about Retrieving, Creating, and Managing SailPoint IdentityNow Roles using PowerShell.

Last week SailPoint enhanced Roles with the ability to request them. The details are located on Compass here.

I had a number of Roles that we wanted to make requestable, so rather than opening each and using the Portal UI to enable them, I did it via the API using PowerShell.

As per my other Roles post, a JWT Bearer Token is required to leverage the Roles API’s. That is still the same. I covered how to obtain a JWT Bearer Token specifically for interacting with these API’s in this post here. I’m not going to cover that here so read that post to get up to speed with that process.

Enabling Roles to be Requestable

The following script queries to return all Roles, iterates through them to make them requestable. Update;

Line 2 for your IdentityNow Org Nam
after Line 9 you can refine the roles you wish to make requestable

Summary

Using the API we can quickly enable existing IdentityNow roles to be requestable. When creating new Roles we can add in the attribute Requestable with the value True if we want them to be requestable.

November 23, 2018November 27, 2018

Searching & Returning all Objects/Users from a SailPoint IdentityNow Source

There are times when need to get an extract of all objects on an IdentityNow Source. Just a particular Source, not the object from the Identity Cube with attributes contributed from multiple sources.

I’ll cover how I do that in this post, which in turn also handles paging the results from IdentityNow as the SearchLimit is 2500 objects.

The basis of the logic is;

Define the Source to retrieve objects from
Define the number of results you wish to return per page (maximum is 2500)
Page results until you return the base object for all objects on the Source
Retrieve the Full Object details for each object

The Script

The following script has been written to run in VS Code and provide a Progress bar using the psInlineProgress PowerShell Module available from the PowerShell Gallery and here. If you are also running this via VSCode, after obtaining psInlineProgress update the psInlineProgress.psd1 file to change Line 36 as shown below. You should be able to find it in C:\Program Files\WindowsPowerShell\Modules\psInlineProgress\1.1

#PowerShellHostName = 'ConsoleHost'
PowerShellHostName = 'Visual Studio Code Host'

Update;

Line 3 for your IdentityNow API ClientID
Line 5 for your IdentityNow API ClientSecret
Line 9 for you IdentityNow Tenant name
Line 13 for the ID of the IdentityNow Source you want to retrieve entities from
Line 17 for the number of entries to return per page (2500 is the maximum)

Example

The output below shows using the script to return 2591 objects from an IdentityNow Source.

Summary

Using the v2/accounts IdentityNow API we can retrieve the base objects associated with an IdentityNow Source and then call it again with each objectID to retrieve the full object record. This can be useful if you want to then programatically extract and process the information rather than downloading a CSV via the IdentityNow Portal. Say for example ingestion into another system or Identity Management tool. But that’s a post for another time.

November 20, 2018November 16, 2018

Retrieving SailPoint IdentityNow Certification Reports using PowerShell

This is the third and probably last post in the Certifications by API series. The first post detailed retrieving and searching campaigns, the second post detailed creating and starting campaigns. If you haven’t read those, check them out as they will give you the background for this one.

As detailed in the previous two posts this post also assumes you are authenticated to IdentityNow as detailed in this post, and you understand that this post details accessing Certifications using the non-versioned SailPoint IdentityNow API’s.

With that all said, this post details obtaining Certification Reports from Completed Campaigns. The process goes like this;

Search and return Completed Campaigns
Identify campaigns completed within a time period
Retrieve and export the CSV completion reports

Note: The first time you access the getReports API for a Campaign the Reports are automatically generated. You can and should include additional logic to catch that the request for the report fails and wait a minute before retrying when the report has been generated allowing you to then retrieve it.

Reports API

As mentioned above the getReports API is used to get a list of reports from campaigns.

https://$($orgName).api.identitynow.com/cc/api/campaign/getReports

To get an individual report the report/get API call is used along with the ID of the report to retrieve. The base URI is;

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

Exporting Certification Campaign Completion Reports

The following PowerShell script will enumerate completed campaigns, compare the completion time to the current time and the time window to export (last 7 days in my example below) and export the CSV version of the reports to a directory on the host running the script.

Update:

Line 11 for the number of days previous to days date to retrieve reports on
Line 34 for the output CSV path. The exports are named based on the Description of the Campaign, so you’ll need to modify that if all your descriptions are the same

The output is the CSV File which can then be manipulated in PowerShell or Excel (via Data => Import CSV.

Summary

Using the Certifications API we can query for Completed Certification Campaigns and then retrieve their complete reports and export them to the file system. Likewise with a few simple changes you can also export the other reports.

November 16, 2018November 16, 2018

Creating SailPoint IdentityNow Certification Campaigns using PowerShell

Create Sailpoint IdentityNow Certification Campaigns

This is the second post in the Certifications by API series. The last post detailed searching and retrieving campaigns. If you haven’t read that, check that out as it will give you the background for this one.

Also as per the last post this post also assumes you are authenticated to IdentityNow as detailed in this post, and you understand that this post details accessing Certifications using the non-versioned SailPoint IdentityNow API’s.

With that all said, this post details the creation of IdentityNow Certification Campaigns via the API using PowerShell. The Create Campaigns from IdentityNow Search process goes like this;

using the Search API, find the users connected to a Source (or a group of users based on other criteria)
iterate through them to identify their Role(s), Entitlement(s) and Source(s) and create a Manager Certification Campaign
Specify the period for the Campaign along with options such as notifications and revocation
Start the Campaign

Campaign Creation

As stated above the first task is to search and retrieve candidates for the campaign. This uses the Search function as I described in more detail in this post here.

If you have more than the searchLimit allowable via the API you will need to page the results over multiple queries. I’ll detail how to do that in a future post. In the query below I’m searching for users on the Source “Active Directory”.

$searchLimit = '2500'
# Search Identities URI $searchURI = "https://$($orgName).api.identitynow.com/v2/search/identities?"
# Query for Source that Campaign is for
$query = '@accounts(Active Directory)'
# Search Accounts
$Accounts = Invoke-RestMethod -Method Get -Uri "$($searchURI)limit=$($searchLimit)&query=$($query)" -Headers @{Authorization = "Basic $($encodedAuth)" }
write-host -ForegroundColor Yellow "Search returned $($accounts.Count) account(s)"

With the users returned we need to iterate through each and look at the users Entitlements, Roles and Access Profiles. We are creating a Manager campaign for these users for all of these (you can reduce the scope if required). The PowerShell snippet to do that looks like this.

User Roles Access Profiles and Entitlements

For inclusion in the campaign we need to build a collection for the Roles, Entitlements and Access Profiles. Using PowerShell to iterate through the list obtained from the users above therefore looks like this:

The summary after enumeration below shows the users for the source will be cover 1 Role, 9 Entitlements and 2 Access Profiles.

Summary of Roles Entitlements and Access Profiles

Now we have most of the information defined for the scope of our campaign we can specify the additional criteria and information such as duration, name, description, notification, and revocation. Each of those settings are self explanatory by the configuration setting. We then create the Campaign and and Activate it. I have a short delay after creation before activation as I found race conditions. You could lower the delay, but YMMV.

You can also add a Static Reviewer for the campaign as by default the owner will be the account you’re using to perform the creation. Add the following line into the configuration options and specify the ID for the identity.

$campaignOptions.Add("staticReviewerId", $reviewerUser.id )

The ID for an Identity can be obtained via Search. e.g.

# Get Campaign Reviewer in addition to the campaign creator
$usrQuery = '@accounts Rick.Sanchez'
$reviewerUser = Invoke-RestMethod -Method Get -Uri "$($searchURI)limit=$($searchLimit)&query=$($usrQuery)" -Headers @{Authorization = "Basic $($encodedAuth)" }

Putting it all together then looks like this in PowerShell.

The screenshot below shows the campaign being created.

Looking at the Certifications section in the IdentityNow Portal we can see the newly created Campaign.

Campaign in Portal — Created Campaign shows in Portal

And we can see the two Managers requiring review.

Campaign in Portal 2.PNG — Campaign details in Portal

As the reviewer for Ronnie I can then go and start the review and see the Entitlements that I need to review for the campaign.

Summary

Using PowerShell we can search IdentityNow and find accounts on a Source and create a Certification Campaign for them based on Roles, Entitlements and Access Profiles. We can then also activate the campaign. Happy orchestrating.

November 15, 2018November 14, 2018

Accessing SailPoint IdentityNow Certification Campaigns using PowerShell

This is the first post in a series covering SailPoint IdentityNow Certifications. Specifically listing and returning campaigns, creating campaigns and accessing campaign reports. This post will show Listing Active and Completed Campaigns, Searching for a specific Campaign and returning the full details for a Campaign.

The IdentityNow v1 API’s and v2 API’s don’t expose endpoints for IdentityNow Certification Campaigns so access will be via the non-public/versioned Certification API’s. In order to access these API’s you will need to be appropriately authenticated. This post here details getting up to speed with that and is a prerequisite for performing the campaign functions I detail in this post.

Retrieving Certification Campaigns

Now that you’re authorized to IdentityNow we can look to retrieve Certification Campaigns. This can be achieved by calling the /campaign/list API.

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

Using PowerShell all Active Certification Campaigns can be returned by making the following API call and configuration. Note the Content-Type is removed as if you specify a Content-Type the API will error.

To retrieve Completed campaigns change $completedOnly = $false to $completedOnly = $true

# List Campaign Base URI
$GetCampaignBaseURI = "https://$($orgName).api.identitynow.com/cc/api/campaign/list"
$IDN.Headers.Remove("Content-Type")
$utime = [int][double]::Parse((Get-Date -UFormat %s))
$completedOnly = $false
$campaigns = 100
# Get Active Campaigns
$existingCampaigns=Invoke-RestMethod-method Get -uri "$($GetCampaignBaseURI)?_dc=$($utime)&completedOnly=$($completedOnly)&start=0&limit=$($campaigns)"-WebSession $IDN

Iterating through each result and outputting a summary to the console is then possible as shown below.

List Active SailPoint IdentityNow Campaigns

To retrieve an individual Campaign you need to know the ID of the Campaign. You can then retrieve it directly using the campaign/getCertifications API e.g.

https://$($orgName).api.identitynow.com/cc/api/campaign/getCertifications?_dc=1542094205212&campaignId=2c9180856708ae38016709f4812345c3

Doing that via PowerShell looks like this

$IDN.Headers.Remove("Content-Type")
$utime = [int][double]::Parse((Get-Date -UFormat %s))
$campaignID = "2c9180856708ae38016709f4812345c3"
$Certs=Invoke-RestMethod-method get -Uri "https://$($orgName).api.identitynow.com/cc/api/campaign/getCertifications?_dc=$($utime)&campaignId=$($campaignID)"-websession $IDN
$Certs.items

Searching for Certifications

The new Search Beta does not extend to Certifications. Retrieving a Certification Campaign via the Campaign ID is fine, if you know it (which you won’t). So here is my workaround for this. Retrieve all Campaigns (Active OR Completed) as detailed above using PowerShell and then use the power of PowerShell (Where-Object) to search and find the Campaign you want.

$completedOnly = $true
$existingCampaigns = Invoke-RestMethod -method Get -uri "$($GetCampaignBaseURI)?_dc=$($utime)&completedOnly=$($completedOnly)&start=0&limit=$($campaigns)" -WebSession $IDN
$myCampaign = $existingCampaigns.items | Select-Object | Where-Object {$_.name -like "*Dec 2018 Campaign*"}

Searching and returning campaigns and then retrieving the full details for a campaign therefore looks like this in PowerShell.

$myCampaignFull=Invoke-RestMethod-method get -Uri "https://$($orgName).api.identitynow.com/cc/api/campaign/getCertifications?_dc=$($utime)&campaignId=$($myCampaign.id)"-websession $IDN
$myCampaignFull.items

Search SailPoint IdentityNow Campaigns and Retrieve Full Campaign

Summary

Using PowerShell we can get a list of all Completed and Active Certification Campaigns. We can then find the campaign we are looking for information on and retrieve all its details. In the upcoming posts I’ll show how to create a Certification Campaign and also how to retrieve Reports from completed campaigns.

October 25, 2018October 26, 2018

Creating SailPoint IdentityNow Source Configuration Backups and HTML Reports with PowerShell

In this post from earlier in the week I detailed leveraging the SailPoint IdentityNow APIs to retrieve IdentityNow Sources, and their configuration. This post takes that a little further, backing up the configuration and also creating a friendly HTML Report with each Sources’ Configuration and Schema. The resulting HTML Report that is dynamically created reports on all Sources in an IdentityNow Tenant Org and looks like the image below.

After selecting a Source you can then expand a report section for the Source Details and another for the Schema. Each Source and then Source Details and Source Schema is a collapsible DIV toggled by the link. A snippet of a Source Details output for a Generic Source looks like the image below.

A snippet of a Source Schema output for a Generic Source looks like the image below.

The Script

This script 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 and have the necessary JWT Access Token to execute these API requests.

The report features an image. Here is the one I created. Download it and put it in the root of the output folder where the reports will be created.

Make the following updates to the script:

Line 10 for the path to the Image file you saved from above
Line 17 for the base output path (sub directories are created for the date/time of each execution) for the Report and Configuration Backups

The Output

Following execution of the script a sub-directory under your directory path is created and you will find the HTML Report along with two files for each Source. An XML export of the Source Details and the Source Schema. If you need to inspect a configuration that has been exported you can use the Import-Clixml -Path “path to the exported xml file” to import it into PowerShell and inspect it.

Summary

Put the execution of this script on a schedule whilst you are in the development/configuration phase of your IdentityNow deployment and you will get automated configuration reports and backups that can be reviewed if you need to roll-back or just see what changes have been made over time.

October 24, 2018October 24, 2018

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.

October 19, 2018January 1, 2019

Managing SailPoint IdentityNow Applications via API with PowerShell

The SailPoint IdentityNow Request Center comes pre-populated with 130 Applications (as shown below) that by default are visible to users in the Dashboard and can be requested via the Request Center. Whilst this is great the majority are not often applicable and you need to configure each individual application to remove visibility and requestablity. You could of course ask your IdentityNow Support representative to do this for you, or you could manage it yourself. Lets go with option B and I’ll show you how.

To disable visibility of an Application, and to also remove it from being requested through the Request Center there are two options that need to be toggled off. Enabled For Users, and Visible in the Request Center.

Say you want to remove all from being visible and requestable. You will need to open each app, toggle the slider and the radio button and select save. That’s a minimum of 4 mouse clicks and some mouse scrolling x 130, or do it via the IdentityNow API in < 60 seconds. Option B please.

Retrieving Applications

The URI to return all IdentityNow Applications is

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

Before you can call that URI you will need to be authenticated to IdentityNow. Follow this post and make sure you have the headers in the WebSession configured with the Bearer Access Token.

Then using PowerShell you can return all Applications with;

$appList = Invoke-RestMethod -Uri $appListURI -Method Get -WebSession $IDN

If you want to find a single app, find it by name using Select-Object | Where-Object

$myApp = $appList | Select-Object | Where-Object {$_.name -eq "New York Times"}

The Application PowerShell Object for the New York Times looks like;

id : 24184
appId : 11
serviceId : 32896
serviceAppId : 24184
name : New York Times
description : American daily newspaper
appCenterEnabled : False
provisionRequestEnabled : False
controlType : PERSONAL
mobile : True
privateApp : False
scriptName : C:1-new-york-times
status : ACTIVE
icon : https://files.accessiq.sailpoint.com/modules/builds/static-assets/perpetual/identitynow/icons/2.0/n
ytimes/
health : @{status=HEALTHY; lastChanged=1539766560496; since=0; healthy=True}
enableSso : True
ssoMethod : PASSWORD
hasLinks : True
hasAutomations : True
primaryLink : https://myaccount.nytimes.com/auth/login
primaryMobileLink : https://myaccount.nytimes.com/mobile/login/smart/index.html?EXIT_URI=://mobile.nytimes.com/loginRet
urnthUK?url=/?redir_esc=
stepUpAuthData :
stepUpAuthType : NONE
usageAnalytics : False
usageCertRequired : False
usageCertText :
launchpadEnabled : False
passwordManaged : False
owner :
dateCreated : 1522393052000
lastUpdated : 1539766536000
defaultAccessProfile :
service : New York Times
selectedSsoMethod : PASSWORD
supportedSsoMethods : 2
authenticationCookie : []
directoryPassword_supported : false
none_supported : true
passwordReplay_supported : true
proxy_supported : false
saml_supported : false
wsfed_supported : false
accountServiceId : -1
launcherCount : 0
accountServiceName :
accountServiceExternalId :
accountServiceMatchAllAccounts : True
externalId :
passwordServiceId : -1

Removing Applications from User Visibility

Let’s remove all Applications from user visibility (and the Dashboard). The process is simply to retrieve all Applications, then update each one to toggle off the options for visibility. The following script does just that.

After updating each app the Request Center is empty. Much quicker than hundreds of mouse clicks.

Summary

With the ability to retrieve Applications and update them via the API repetitive configuration becomes super quick.

Prerequisites

Enumerating all Tasks

Searching for and retrieving an Individual Task

Completing a Task

Summary

Share this:

Authentication Script

Using the v3 oAuth Access Token

Summary

Share this:

Enabling Roles to be Requestable

Summary

Share this:

The Script

Example

Summary

Share this:

Reports API

Exporting Certification Campaign Completion Reports

Summary

Share this:

Campaign Creation

Summary

Share this:

Retrieving Certification Campaigns

Searching for Certifications

Summary

Share this:

The Script

The Output

Summary

Share this:

Getting a List of Sources

PowerShell Example

Getting the Details of a Source

PowerShell Example

Getting the Schema of a Source

PowerShell Example

Updating the Details for a Source

Summary

Share this:

Retrieving Applications

Removing Applications from User Visibility

Summary

Share this: