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.

Certification Report in Excel.PNG

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.

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
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
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.

Campaign Created
Campaign 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.

Entitlements Certification
Entitlements Certification

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.

Accessing SailPoint IdentityNow Certification Campaigns using PowerShell

Sailpoint IdentityNow Certifications

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
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
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.