Posted on

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.

Posted on

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.

Posted on

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.

Posted on

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.  Sample Report.PNG

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.

Source Details.PNG

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

Schema Example.PNG

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.

SailPoint IdentityNow 240px.png

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.

Example Output Files.PNG

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.

Posted on

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.

Posted on

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.

Application List.PNG

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. 

Application Settings 1.PNG

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.

Request Center Empty.PNG

Summary

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

Posted on

Managing SailPoint IdentityNow Roles via API and PowerShell

Managing SailPoint IdentityNow Role Groups typically involves leveraging the SailPoint IdentityNow Portal for the creation and on-going management. That’s because the API for Roles is not published or documented.

What happens then if you have many to create, update/manage? How does the IdentityNow Portal use the non-published undocumented API’s to create and manage them? I’ve worked it out and am documenting it here in the interim until the API’s get versioned and published.

Note: There is a chance that the Roles API may change, 
so use at your own risk. 

Roles API Authentication

First up the Roles API URI looks like this.

https://OrgName.api.identitynow.com/cc/api/role

The /cc/ part is a good indication that the API isn’t documented, but also that the Authentication mechanism to interact with it is using a JWT Bearer Token. 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.

Associated with managing the criteria of Roles we will also need to reference IdentityNow Sources. We can do that via a non-published API too.

https://OrgName.api.identitynow.com/cc/api/source

Listing all IdentityNow Roles

Similar to Governance Groups that I detailed in this post Roles can be returned on an individual basis (if you know the ID of the Role which you won’t). So the simplest way is to query and return them all (no, the Search (BETA) doesn’t support Roles either). The API to list all roles is:

https://OrgName.api.identitynow.com/cc/api/role/list

Doing this then via PowerShell to return all roles looks like this:

Roles = Invoke-RestMethod -Uri "https://OrgName.api.identitynow.com/cc/api/role/list" -WebSession $IDN
and finding Roles you are interested in can be done using Where-Object
$Roles.items | Select-Object | Where-Object {$_.displayName -like "Kloud*"}

SailPoint Roles.PNG

Creating Roles

The example script below shows the generation of information for a Role Object. Specifically;

  • name
  • displayname
  • description
  • disabled (whether the Role is enabled or disabled)
  • owner (the IdentityNow NAME attribute value of the owner of the Role)

Executing this creates the Role.

Role Created.PNG

Looking in the Portal we can then see the Role.

Role Created in Portal.PNG

Managing Role Criteria

The Role Criteria will obviously depend on what your criteria is. Is it based on Standard Group Rules, a List of Identities or Custom? I’ll cover a List of Identities and Group based criteria.

Adding a List of Identities to a Role

This isn’t too dis-similar to Governance Roles. We search for the list of users we want to add to the Role and add them to a collection. The key difference is that we use Name instead of ID. We then specify the type of Criteria (Identity_List) and the ID of the Group to update.

Executing the Script

The example script below switches the Headers for Basic Auth to use the v2 endpoint to search and locate the users to add to the Role. It then switches the Headers over to JWT Bearer Auth, generates the body for the request to update the Role Group and updates the Role Group.

Executing the script looks as per below and runs through successfully.

Adding IdentityList Members to Role Group.PNG

Checking the Role Group in the IdentityNow Portal

Identity List Updated - Portal.PNG

Adding a Members Based on Criteria to a Role

Adding users to a Role based on Criteria is similar to above except rather than searching for Identities we are adding the criteria for a role.

The criteria can be based on an Identity Attribute an Account Attribute or an Entitlement. I’ll show using an Identity Attribute and an Account Attribute.

Account Attribute based Criteria

Account criteria is based on attributes available in the Schema of a Source. In order to reference the Source we need the ID of the Source. This is available via the non-published Source API cc/api/source

The example script below shows getting all Sources and finding the one you want to base your Role Criteria off (based on name). You can of course mix criteria across many sources, but I’m showing you doing it from one. Running the following script will return your Sources. You require the ID of the Source you want to leverage attributes from to base your criteria off. The attribute that contains this used further along in these examples is $RoleSource 

Now that we have the Source ID for the Source that contains the attribute that we want to base our Role Criteria on, we need to build the criteria. Let’s start with a simple one and Single Criteria.

Here is an example JSON document with a Single Criteria that contains the variables for the Role that we just created (Role ID), the Source ID for the Source with the attribute we are using for the criteria and the value we want to match (RoleCriteriaValue). The Attribute from my Source that I’m using is Supplier. Update for the attribute you’re using on your Source.

"{`"id`":`"$($newRole.id)`",`"accessProfileIds`":[],`"selector`":{`"type`":`"COMPLEX_CRITERIA`",`"entitlementIds`":[],`"aliasList`":[],`"valueMap`":[],`"complexRoleCriterion`":{`"operation`":`"OR`",`"children`":[{`"operation`":`"EQUALS`",`"key`":{`"type`":`"ACCOUNT`",`"property`":`"attribute.Supplier`",`"sourceId`":`"$($RoleSource)`"},`"value`":`"$($RoleCriteriaValue)`"}]}}}"
After converting the JSON object to a PowerShell Object using ConvertFrom-JSON it looks like this:
Single Role Criteria.PNG

Having it as a PowerShell Object also makes it easy to modify. If you wanted to change the criteria to match against, the Operator and/or the operation then just change the value. e.g. the following will change the value to match from “Kloud Solutions Pty Ltd” to “Darren J Robinson”

$RoleCriteria.selector.complexRoleCriterion.children.value = "Darren J Robinson"

Convert back to JSON for Post via the webrequest to the API. That and updating the Role with the criteria thereby is;

Update Single Criteria.PNG

In the Portal we can see that the Criteria has been added.

Update Single Criteria - Portal.PNG

And you will notice I have a Role Refresh call after the update to update the Role Membership as it is now based on Criteria. If you are updating/adding criteria to numerous roles only call the Refresh at the end.

Role Refresh.PNG

Adding Multiple Criterion

Multiple criterion is just more information to pass to the update. The format can be a little confusing so here is a template for three criteria showing the three Operators (Equals, Contains and Not_Equals).

$RoleCriteria = "{`"id`":`"$($newRole.id)`",`"accessProfileIds`":[],`"selector`":{`"type`":`"COMPLEX_CRITERIA`",`"entitlementIds`":[],`"aliasList`":[],`"valueMap`":[],`"complexRoleCriterion`":{`"operation`":`"OR`",`"children`":[{`"operation`":`"AND`",`"children`":[{`"operation`":`"EQUALS`",`"key`":{`"type`":`"ACCOUNT`",`"property`":`"attribute.Supplier`",`"sourceId`":`"$($RoleSource)`"},`"value`":`"$($RoleCriteriaValue)`"},{`"operation`":`"NOT_EQUALS`",`"key`":{`"type`":`"ACCOUNT`",`"property`":`"attribute.country`",`"sourceId`":`"$($RoleSource)`"},`"value`":`"New Zealand`"},{`"operation`":`"CONTAINS`",`"key`":{`"type`":`"ACCOUNT`",`"property`":`"attribute.email`",`"sourceId`":`"$($RoleSource)`"},`"value`":`".com.au`"}]}]}}}"

When converted to a PowerShell Object and displayed it looks like this;

3 Account Criteria Options.PNG

Identity Attribute based Criteria

The last example is Identity Attribute Criteria. This is simpler than the Account Attribute Criteria as we just need to reference the Identity Attribute and don’t need to reference a Source. A single criteria for isEmployee  = True looks like this;

{`"operation`":`"EQUALS`",`"key`":{`"type`":`"IDENTITY`",`"property`":`"attribute.isemployee`"},`"value`":`"true`"}

As a second Criteria Group though in the Portal it looks like this;

2nd Criteria Group.PNG

and for the JSON object (RAW without variablizing) looks like this;

"{`"id`":`"2c918086663fbbd0016612345678909876`",`"accessProfileIds`":[],`"selector`":{`"type`":`"COMPLEX_CRITERIA`",`"entitlementIds`":[],`"aliasList`":[],`"valueMap`":[],`"complexRoleCriterion`":{`"operation`":`"OR`",`"children`":[{`"operation`":`"AND`",`"children`":[{`"operation`":`"EQUALS`",`"key`":{`"type`":`"ACCOUNT`",`"property`":`"attribute.Supplier`",`"sourceId`":`"2c91808365f742620165f9ba0e831bf8`"},`"value`":`"Kloud Solutions Pty Ltd`"},{`"operation`":`"NOT_EQUALS`",`"key`":{`"type`":`"ACCOUNT`",`"property`":`"attribute.country`",`"sourceId`":`"2c91808365f742620165f9ba0e831bf8`"},`"value`":`"New Zealand`"},{`"operation`":`"CONTAINS`",`"key`":{`"type`":`"ACCOUNT`",`"property`":`"attribute.email`",`"sourceId`":`"2c91808365f742620165f9ba0e831bf8`"},`"value`":`".com.au`"}]},{`"operation`":`"EQUALS`",`"key`":{`"type`":`"IDENTITY`",`"property`":`"attribute.isemployee`"},`"value`":`"true`"}]}}}"

Summary

Using the cc/api/role APIs we can Create Role Groups, Update Roles Groups to contain Criteria and Refresh Role Groups to have the membership calculated. With the base functionality detailed we can now use this to create and manage our Role Groups through automation. Happy Days.

Posted on

Managing SailPoint IdentityNow Governance Groups via the API with PowerShell

In this post I detail the management of SailPoint IdentityNow Governance Groups using the IdentityNow v2 API as the functions associated with Governance Groups is not currently detailed in the v2 API Documentation here (9 Oct 2018).

In order to interact with the v2 API you will need to use Basic Authentication which I detail in this post here. The common authentication/authorization piece from that post is also shown below.

Retrieving Governance Groups

Now that you’re authorized to IdentityNow using Basic Authentication we can look to retrieve Governance Groups. This can be achieved by calling the /v2/workgroups API.

https://OrgName.api.identitynow.com/v2/workgroups?&org=ORGName

Using PowerShell all Governance Groups can be returned by making the following API call.

$GovGroups = Invoke-RestMethod -Method Get -Uri "$($baseURI)/v2/workgroups?&org=$($orgName)" -Headers @{Authorization = "Basic $($encodedAuth)"}

To retrieve an individual group you need to know the ID of the Group. You can then retrieve it directly using the v2/workgroups API  e.g.

https://OrgName.api.identitynow.com/v2/workgroups/6289788a-c73c-426b-9170-12340aaa6789
Doing that via PowerShell looks like this:
Invoke-RestMethod -uri "https://OrgName.api.identitynow.com/v2/workgroups/6289788a-c73c-426b-9170-12340aaa6789" -Method Get -Headers @{Authorization = "Basic $($encodedAuth)"}

It would be nice to search Governance Groups using the new Search (BETA) feature. But currently the only Groups that are returned via it are Entitlement Groups.

Searching for Governance Groups

As mentioned above the new Search Beta only returns Entitlement Groups. Retrieving Governance Groups via the Governance Group ID is fine, if you know it (which you won’t).  So here is my workaround for this. Retrieve all Governance Groups as detailed above using PowerShell and then use the power of PowerShell (Where-Object) to search and find the group you want.

$GovGroups = Invoke-RestMethod -Method Get -Uri "$($baseURI)/v2/workgroups?&org=$($orgName)" -Headers @{Authorization = "Basic $($encodedAuth)"}
$myGovGroup = $GovGroups | Select-Object | Where-Object {$_.description -like "Kloud*"}

The above looks through each of the Governance Groups to find the ones that contain the word Kloud in the Description field. 53 Groups returned and 2 meet the criteria.

Search Governance Groups.PNG

Creating IdentityNow Governance Groups

To create a Governance Group you will/should provide:

  • IdentityNow Governance Group
    • name (e.g Vendor XX)
    • description (e.g Vendo)
    • owner
      • displayName (e.g Vendor Admin)
      • emailaddress (e.g vendor_admin@vendor.com.au)
      • id (eg 2c918084624f8b59016275c123456789)
      • name (e.g Vendor_Admin)

My approach is;

  • Use the Search API to search and find the user account that will be the Owner for the Governance Group
  • Create the Governance Group assigning the Owner

Here is an example of creating a single Governance Group implementing the approach above.

Executing the script successfully creates the group.

Create Governance Group.PNG

Looking at the Group in the Portal I can see that it has been created with the correct owner.

Governance Group Created

Now if you are like me and you have numerous Governance Groups to create you can of course have a list of Governance Groups to be created and loop through creating each one. Brilliant.

Managing Members of Governance Groups

Updating a group for membership is a simple case of sending through a collection of members to add/remove. This isn’t a replace operation but an addition. So if you want to add a single member, just send through the details to add that member and they will be added to the Governance Group. Likewise for removal.

Process overview;

  • taking a group that was just created we use the ID of that group to then update the membership
  • searching IdentityNow we find the members to add
  • generate the collection to add
  • update the group

Here is a sample wscript the performs that process.

And looking at the Governance Group in the IdentityNow Portal we can see the membership has been updated. Obtaining the Group (using the search method above) also allows for easy removal of all/any members.

Members Added to Governance Group.PNG

Summary

Using the v2/workgroups IdentityNow API we can create and manage Governance Groups. This is extremely powerful when you have many to create and manage.

Posted on

Leveraging v1, v2 and non-Published SailPoint IdentityNow API’s with PowerShell

This post supersedes my previous posts on leveraging the IdentityNow API’s in relation to API Authentication/Authorization;

Using this Compass document as my guide (which takes a bit of finding) I’ve automated the process of being able to use PowerShell to leverage the non versioned/published API’s. The method I show below is also valid for the documented and versioned API’s.

I show how I generate the necessary credentials required for:

  • IdentityNow Basic Authentication
  • IdentityNow Cookie Authentication
  • IdentityNow JWT oAuth Bearer Authentication

I also show working calls using Basic and JWT oAuth Authentication. The CCSessionID is extracted for use in Cookie Authentication for completeness, but everything can be accomplished using Basic and JWT oAuth Authentication. This document on SailPoint Compass provides more details on each.

Script Overview

Using PowerShell I;

  • authenticate to the IdentityNow Portal
  • elevate via authentication to the Admin section of the IdentityNow Portal
  • obtain the CCSESSIONID Cookie and the CSRF Token
  • provide the ability to add into the Web Session Header IdentityNow Basic or JWT oAuth Authentication credentials

That then allows access to the non-published API’s that are leveraged via the IdentityNow Portal and published API’s.

Obtaining the CSRF Token, JWT Access Token and Session Cookie Programatically with PowerShell

Update the Strong Authentication Methods for IdentityNow Admins

As we need to programatically authenticate to the Portal itself to get the necessary information required for API authorization, we need a mechanism that supports that. The only one that does easily is password. So you will need to enable that.

  • NOTE: chances are you’re using programmatic access to configure/ingest data or configuration as part of service enablement. Once that is done, REMOVE “re-entering password” as a Strong Authentication Method.

In the IdentityNow Portal go to Admin => Identities => Identity Profiles => IdentityNow Admins =>Enable By re-entering their password

Admin Centre Strong Auth Options.PNG

Using a Chrome Browser head to the IdentityNow Login screen for your Tenant. e.g. https://TENANT.identitynow.com. Press F12 for Developer Tools and then enter the Username and Password for an Admin account. Press the Record button (highlighted below, if it isn’t already red) to start recording and then press the Sign In button.

Portal Login Window

When the browser has logged you in, select the Network tab and then right-click on the ‘login’ entry in the trace. Select Copy and then Copy as PowerShell which will copy the webrequest that you just performed to login. Paste this into the script below on Line 25.

WebRequest Login

Next in the browser select Admin and then any of the Admin menu items. e.g. Dashboard => Overview. Select Enter password and check Remember my preference then Continue.

Record the Strong Auth Screen.PNG

The next screen will give you the prompt to supply your password again. Enter the password and then clear the traces from the Developer Tools pane and then make sure Record is enabled, then press Authenticate.

Record Password 2nd Screen.PNG

Select the strongAuthn trace from the Network tab, right-click and select Copy and then Copy as PowerShell. Paste this into the script below on Line 43. Don’t forget to edit it for the CSRF Token variable.  

Strong Auth Capture.PNG

The Script

Update the script below for your environment by:

  • Line 3 with your IdentityNow Organisation name
  • Line 9 with your IdentityNow API Client ID
  • Line 11 with your IdentityNow API Client Secret
  • Line 16 with your Admin login name for the IdentityNow Portal
  • Line 25 with the first PowerShell Webrequest you copied above
  • Line 43 update with the second PowerShell Webrequest you copied above. Make sure to go back and add in the variable for the CSRF Token as shown below. $($orgName) is optional.
    • example $admPortalAuthN = Invoke-WebRequest -Uri $adminStrongAuthURI -Method “POST” -Headers @{“Origin” = “https://$($orgName).identitynow.com”; “Accept-Encoding” = “gzip, deflate, br”; “X-CSRF-Token” = $($csrf); “Accept-Language” = “en-US,en;q=0.9”; “User-Agent” = “Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36”; “Accept” = “*/*”; “Referer” = “https://$($orgname).identitynow.com/ui/admin”; “X-Requested-With” = “XMLHttpRequest”} -ContentType “application/x-www-form-urlencoded; charset=UTF-8” -Body “password=f2dbeb5a897abeeecafc9deee5612345678903456789bdedf7d42” -WebSession $IDN

Output from the Script

The screenshot below shows successfully making API calls to IdentityNow across the v1, v2 and the non versioned API’s after generating the necessary Authentication credentials.

Note that after calling the v1 and non versioned API’s I change the Headers to remove the Bearer Authorization Token and replace it with the Basic Authorization Token so that the v2 API’s can be called.

Examples Output.PNG

 

Optional: Obtaining the CSRF Token Manually

If you do want to obtain the CSRF Token manually then using a web browser.

  • Login to IdentityNow Portal main Dashboard with an Admin account
    • A direct URI looks like this;
https://TENANT.identitynow.com/login/login?goto=https%3A%2F%2FTENANT.identitynow.com%2Fui%2Fd%2Fdashboard
  • Head to the Admin Dashboard and you will be prompted for Strong Authentication
https://TENANT.identitynow.com/ui/admin#admin:dashboard:overview
    • At this point though you will also be able to retrieve the CSRF Token

Using the Chrome Developer Tools (e.g. pressing F12 in Chrome) select Console, then at the prompt type SLPT.CSRFToken You will then see your CSRF Token for that session.

CSRFToken via Browser.PNG

Summary

With the ability to programatically generate the necessary Authorization tokens for IdentityNow we can interact with the documented API’s along with the API’s that are being leveraged by the IdentityNow Admin Portal itself.

Posted on

Integrating with SailPoint IdentityNow Private (v1) API’s using PowerShell

UPDATE: 5 Oct 2018
Please see this new post on accessing v1, v2 and 
non-published SailPoint IdentityNow API's using PowerShell.
The details in this post will still work for v1 API's.

How to generate the ‘Password Hash’ to leverage the IdentityNow Private API’s

Recently I’ve posted about integrating with the SailPoint IdentityNow API’s. Specifically;

So why another post on a very similar subject? Well, not all IdentityNow API’s are exposed on the v2 API Endpoints that were leveraged in the previous posts. The v1 (Private API List) is detailed on SailPoint Compass here and contains a number of functions that are extremely useful. And here is where it gets interesting. The authentication methods between v1 and v2 are not the same. There is a document that gives you most of what you need also on SailPoint Compass here that describes IdentityNow’s oAuth methods.

But here is the kicker. In order to use the older v1 API endpoints you need to generate a hash for the user associated with oAuth2.0 authentication which is in addition to the Client ID and Client Secret. The only method that I’m aware of (and believe me I lost time and effort searching) that SailPoint provide to generate the hash is to use the File Upload Utility which is available on Compass here. And that method only came to my attention after posting to the IdentityNow Community.

Now let’s say you run into the problem I did with the version of Java (yes it is a Java Utility) I had installed (v1.7);

java version "1.7.0_71"
Java(TM) SE Runtime Environment (build 1.7.0_71-b14)
Java HotSpot(TM) 64-Bit Server VM (build 24.71-b01, mixed mode)
Wrong Version of Java.PNG
identitynow fileuploader hash generator – idnFileUploader.jar

I didn’t have a need for Java, in fact I was surprised it was even installed on my laptop. Seems it was from an installation of Virtual Box some time ago. I didn’t want to go and get another version etc etc. But I did spin up a VM and get the Java App to run and generate the hashed password. A hashed password for IdentityNow v1 API integration looks like this;

160a028019a1ce58c679f2216a7f707fa666a674772b4742cef7b08eab99de7b

Looking at that I guessed SHA256, but there was something else going on (check the case).

The Premise and Intent

I’ve generated the password hash, why not just move on? What I was looking to achieve was the ability for a number of services to interact with IdentityNow via v1 Private API’s. As part of those processes and for management of that privileged access, it needs to be automated. Running a Java app to generate the hashed password for each identity and on each password change wasn’t an option.

The Solution

What I ended up doing, as there was no accessible documentation around how the hashed password is generated for v1 API integration still makes me feel a bit dirty and guilty that I had to do it. Maybe I shouldn’t even be documenting it? But we are licensed for this service and integration with it is still limited to what functions are available via the API and identity you are authenticating with.

I decompiled the Java App, peeked inside and looked to see how the hash was being generated. Then mimicked the process in PowerShell.

Direct Integration with IdentityNow Private (v1) API’s

Direct integration is essentially like any other API. What you need is;

  • Client ID and Client Secret (enabled via the Admin => Global => Security Settings => API Management)
  • Admin Account and Password (account name and password of an account granted Admin permissions in IdentityNow)
    • this is passed in the WebRequest Header as Digest AuthN (Base64 Encoded)
  • Token End Point to get a Token
    • “https://orgname.identitynow.com/api/oauth/token?grant_type=password&username=AdminUser&password=HashedAdminPassword”

The process is;

  1. Generate the Request to the Token Endpoint
  2. Submit the request and obtain a token
  3. Execute subsquent requests with the Bearer Token received in Step 2
  4. Renew token before it expires if continuing to make requests longer than the token life (default 60 mins)

That all looks simple right. Except for that bit about ‘hashed password’.

The Special Sauce

You’ve made it this far, so you’re probably looking to do this. Here it is. The inputs are the IdentityNow Login Name for an Admin account and the plaintext password for that account.

In order to simplify generating the hash you will need to install the PowerShell Community Extensions (PSCX) Module which is in the PowerShell Gallery here. This provides the super handy Get-Hash cmdlet that I use extensively in a number of my scripts. Here I’m using it to generate the SHA256 hashes.

You should be on PowerShell 5.1 or later so the following will install it for you (from an elevated PowerShell console);

install-module -name pscx

Generate passwordhash Script

Update lines 2 and 3 for the Admin Identity you are generating the hash for. Line 8 and 9 are the lines that generate the hash and prepare it for use in requesting a token.

Calling IdentityNow Private API’s with PowerShell

Here is an example of using PowerShell to generate the hashed Password, obtain a token then call the API to return the list of Profiles in IdentityNow.

  • Update the obvious lines for your instance (Lines 2, 4, 8, 10, 11)
  • Update Line 25 if you want to call a different v1 API

Summary

Hopefully I’ve saved others the couple of hours of messing around to workout how to programatically generate the needed password hash to allow automated integration with the SailPoint IdentityNow v1 Private API’s.