Changing SailPoint IdentityNow Identity Profiles Priorities using PowerShell

In SailPoint IdentityNow a single user is highly likely to be represented on multiple Sources, that in turn are likely to be authoritative for differing SailPoint IdentityNow Identity Profiles. Often the first or last Identity Profile you create isn’t the one you wish to have the highest or lowest profile and you therefore need to change an Identity Profiles precedence so that the correct Identity Profile is associated with your identities.

The priority of IdentityNow Identity Profiles cannot be changed through the Portal, but it is possible to perform the change via the API as detailed in this Compass document.

Rather than following the Postman path described in that document, knowing I’m going to need to do this irregularly but relatively quickly I’ve written a little PowerShell script to make the changes.

By default an Identity Profile when created is added to the bottom of the list and their priority increased by 10 from the last Identity Profiles’ priority. The script will by default make the Identity Profile you choose 5 higher that the Identity Profile you’re moving it above.

The following screenshot shows 5 Identity Profiles in their priority order. Let’s say we wanted to move the System Accounts Identity Profile from the bottom priority to between Cloud Identities and Badged Identities.

IdentityNow Priority List.PNG

Using the script (at the bottom of this post) we can authenticate to IdentityNow and retrieve the IdentityNow Profiles with their Priorities. It will ask which IdentityNow Profile you wish to increase the priority of. By default it defaults to the one at the lowest priority.

Identity Profile Priority Changer 1.PNG

You are then prompted for where you would like to move it. Type the name of the Identity Profile you want to move it above.

Identity Profile Priority Changer 2a.PNG

Confirm your selections by typing ‘y’. Anything else will cancel the operation.

Identity Profile Priority Changer 3.PNG

The update will be made in IdentityNow and the output will indicate the updated priority given to the Identity Profile that was moved.

Identity Profile Priority Changer 4.PNG

Checking in the IdentityNow Portal we can see that they Identity Profile was moved from the bottom to between Cloud Identities and Badged Identities.

IdentityNow Priority List Updated.PNG

The Script

Below is the script that performs the changes to Identity Profiles priorities. Update the following script for;

  • Line 2 for your Client ID
  • Line 4 for your Client Secret
  • Line 8 for your Org name
  • Line 10 for your Admin Account name
  • Line 11 for your Admin Account password

Summary

Using this script is a quick way to change the priority of Identity Profiles in SailPoint IdentityNow.

SailPoint IdentityNow Identity Profiles Mapping Report

Last year I wrote this post here that detailed using the SailPoint IdentityNow API to generate an IdentityNow Sources HTML Report using PowerShell.
In a similar vein here is a post that does a similar function, but for the IdentityNow Identity Profiles. The example script below will connect to IdentityNow and extract all the Identity Profiles and pull out the details for the Mappings and create an HTML Report with a section for each Identity Profile.

SailPoint IdentityNow Identity Profiles Report.PNG

Report Script

Update the script below for;

  • Line 2 for your v1 API ClientID
  • Line 4 for your v1 API Client Secret
  • Line 8 for your Org Name
  • Line 10 for your Admin Name
  • Line 11 for your Admin Password
  • Line 22 for an image path for the report
  • Line 27 for the output path for the report

The Report

The resulting report that will be located in the output path you specified, will let you expand each of your Identity Profiles and see the attributes mapping configuration associated with it. A snippet of an Identity Profile is shown below.

SailPoint IdentityNow Identity Profiles Report Details.PNG

Summary

The ability to report on the attribute mappings for Identity Profiles gives a quick way to document or report on the attribute mappings. If you’re so inclined the script can be easily extended to report on all other aspects of the configuration items of an IdentityNow Identity Profile.

The image I’m using in the report is from this page and sized at 240 x 82 px.

Aggregating SailPoint IdentityNow Sources via API with PowerShell

Aggregating an IdentityNow Source can be achieved in a number of ways, but when you are in a development environment there will be times where you need to add additional attributes for a Source to load. If the additional attribute(s) is/are used for Correlation, it’s at this time you will need to perform a full aggregation from a Source to re-evaluate each object with the new Correlation rules and to bring in the additional attributes for each identity on the Source.

The LoadAccounts API briefly mentions this in this SailPoint IdentityNow Compass document. It also details the option that needs to be disabled disableOptimization so that each identity is imported and re-evaluated.

This post details how to call the LoadAccounts API using PowerShell and disable optimization.

Prerequisites

The LoadAccounts API is a Private API that has a different authentication process that the v2 and v3. In this post I detail accessing the v1 Private API’s using PowerShell.  That post gives some more detail around the v1 Private API’s.

The following script will aggregate a SailPoint IdentityNow Source disabling optimisation.

Update;

  • Line 2 with your API ClientID
  • Line 4 with your API Client Secret
  • Line 8 with your IdentityNow Org Name
  • Line 10 with your IdentityNow Admin Account Name
  • Line 11 with your IdentityNow Admin Account Password
  • Line 25 with the SourceID (5 digit number) for the Source to Aggregate

Line 29 contains the Web Request Post Body disableOptimization=true” that disables optimisation for the aggregation. If you just require an aggregation of a source omit the body.

Executing the script with valid credentials and a Source will result in the aggregate variable returning a summary for the trigger of the aggregation. You will notice in the attributes that optimizedAggregation is disabled.

Returned Object when initiating IdentityNow Aggregation via API with optimisation disabled.PNG

This is also reflected in the Aggregation Summary from the Portal when completed.

IdentityNow Aggregation via API with optimisation disabled.PNG

Summary

Using the above script it is possible to quickly perform a full aggregation and re-evaluation of correlation rules for an IdentityNow Source.

 

Creating SailPoint IdentityNow Access Profiles via API and PowerShell

Managing SailPoint IdentityNow Access Profiles is easy enough to do using the SailPoint IdentityNow Portal. But what if you have the requirement to update, report on, or create numerous Access Profiles? That’s where the SailPoint IdentityNow API comes into play. The Access Profiles API is documented here but doesn’t go into a lot of detail. In this post I’ll detail interfacing with it using PowerShell primarily to create and update Access Profiles.

Prerequisites

You will need to Authenticate to the IdentityNow API. Both v2 and v3 authentication methods work. I detail the v2 method here and the v3 method here. Personally I’m using the v3 method. Just make sure you change your Headers for the requests to whatever method you use and the naming of your variables.

For reference my v3token variable is $v3Token so my Authentication Header is then @{Authorization = “$($v3Token.token_type) $($v3Token.access_token)”}

Getting Access Profiles

The Access Profiles API URI is

https://$($yourOrgName).api.identitynow.com/v2/access-profiles

If you know the ID of the Access Profile you can return just that Access Profile via it’s ID (where $accessProfileID is the ID that looks like 2c91808466a64e330112a96902ff1f69)

https://$($yourOrgName).api.identitynow.com/v2/access-profiles/$($accessProfileID)

The following script will return Access Profiles from your SailPoint IdentityNow Tenant. Update;

  • Line 2 for your IdentityNow Org name

Updating Access Profiles

To update an Access Profile the API URI is;

https://$($orgName).api.identitynow.com/v2/access-profiles/$($accessProfileID)

The following will update an existing Access Profile to make Request Comments Required and Denied Comments Required equal False.

Update;

  • Line 2 for your IdentityNow Org name
  • Lines 6 for the ID of the Access Profile you want to update
  • Lines 9,10 for the settings to update

Preparing to create an Access Profile

In order to create an Access Profile, there are a number of configuration items that you will need to provide. The key items are;

  • SourceID is the (currently) five digit ID of a source that you can get from the IdentityNow Portal when looking at the properties of a Source. Or via API as I detailed in this post.
  • OwnerID is the Identity ID for the user you will make the owner. To do that you will need to query IdentityNow for the user (see below for an example)
  • Entitlements
    • In order to get the Entitlements ID(s) to assign to the Access Profile you will need to query the Source. This post here details querying Sources to get Entitlements whereby you can get the ExternalID of Entitlements.

Search for Owner ID Request Object

Here is an example Search Request JSON Object required for the Search User call. Update it for a unique attribute for an Identity to query and return.

Update for your criteria. e.g if you copy the JSON below;

  • create a variable name
    • $requestFilter = ‘JSON snippet content from below’
  • Update the search criteria for your search
    • $newRequestFilter = $requestFilter .Replace(“darren.robinson@customer.com.au”,”yourUser@mydomain.com”)
  • Then search for the user and get the ID of the identity
  • Update
    • Line 2 for your Orgname
    • Line 8 for the user to search for that matches the JSON object from above

Creating an Access Profile

Finally, now that we have the prerequisite information to create an Access Profile we can create it. Modify for your environment based off information retrieved from the processes above. Namely;

  • Line 1 for your Orgname
  • Line 2 for the SourceID associated with the Access Profile
  • Line 3 for the Access Profile Owner’s ID
  • Lines 7-10 for your Access Profile Details
  • Line 14 for the Entitlements
  • Line 19 for the Approver (see below for more details)

Access Profile Approvers

For Approvers you can provide the order for approval. For the approval by the Access Profile Owner and then the Manager use the following when creating the Access Profile in Line 19 above.

  • $accessProfile.add(“approvalSchemes”,”accessProfileOwner, manager”)

Other options are:

  • SourceOwner
  • appOwner
  • Governance Group. See managing Governance Groups here to get the Governance Group ID (GUID format)
    • workgroup: 86929844-3391-4ce2-80ef-760127e15813

Summary

Whilst the creation of an Access Profile via API does require some configuration, if you have multiple to create and you know the criteria it is possible to automate the task. I hope this helps others.

 

Searching and Returning SailPoint IdentityNow Entitlements using the API and PowerShell

Entitlements on IdentityNow Sources can be leveraged for many purposes within IdentityNow. Recently I’ve been looking to automate some Access Profiles that will in-turn have entitlements associated with them.

This post details how to query for Entitlements in IdentityNow using the v3 API and PowerShell.

Prerequisites

You will need to Authenticate to the IdentityNow API. The v3 authentication method is required. I detail the v3 method here. The Headers for the requests detailed in this post use the following variables for the JWT oAuth Token.

My v3token variable is $v3Token so my Authentication Header is then
@{Authorization = “$($v3Token.token_type) $($v3Token.access_token)”; “Content-Type” = “application/json”}

Searching for Entitlements

The Base API URI to search for entitlements is;

https://$($org).api.identitynow.com/cc/api/entitlement/list

You will also need to provide a timestamp and a source for which you want to retrieve entitlements for.

Generating the Timestamp

The timestamp is in Unix format which can be generated in PowerShell like this;

$utime = [int][double]::Parse((Get-Date -UFormat %s))

Getting a list of Sources

I’ve previously described listing IdentityNow Sources in this post and this post. Essentially though you can return a list of all sources by performing a GET request to

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

Obtain the Source ExternalID from the source of  your choice that you then wish to return entitlements for.

Entitlement Results

You can limit the number of entitlements returned by using the limit option. The following will return the first 1000 entitlements for a source starting at 0

&start=0&limit=1000

If the source has more than 1000 then you will need to page the results to return the next 1000 results. Continue until you’ve returned all.

&start=1000&limit=1000

Of course you can just not provide a limit and all entitlements will be returned in a single call.

Finding an Entitlement on a Source

Using the power of PowerShell it is quick to find the Entitlement you want if you know some of the information about it. For referencing an Entitlement when creating an Access Profile via the API you will need the Entitlement ID  e.g

$myEntitlement = $sourceEntitlements.items | Select-Object | Where-Object {$_.displayName -like "*Sydney*"}
$myEntitlement.id

Summary

Using the IdentityNow API and the v3 endpoints we can retrieve entitlements for a Source and quickly locate the entitlement and the entitlement ID for use during automation of IdentityNow tasks such as Access Profile creation.

SailPoint IdentityNow Governance Groups Management Agent for Microsoft Identity Manager

Last week I posted a SailPoint IdentityNow Roles Management Agent for Microsoft Identity Manager. Today I’m posting a sister for it, an IdentityNow Governance Groups Management Agent.

I’ve posted about Governance Groups before. See Managing SailPoint IdentityNow Governance Groups via the API with PowerShell. That post details creating and managing Governance Groups via the API.

This Management Agent is essentially the enumeration of Governance Groups in IdentityNow via API wrapped up in a PowerShell Management Agent. You can extend the management agent for managing Governance Groups to fit your needs.

Prerequisites

  • On your MIM Sync Server you will need the PowerShell Community Extensions (PSCX)  for the Get-Hash cmdlet
  • Authentication to IdentityNow for Governance Groups can leverage the v2 Authentication method. I cover  enabling that in this post here. You can also use the v3 Authentication method I detail here. If you do that you will need to appropriately secure the extra credentials as I show in the Roles Management Agent.
  • The Management Agent leverages the Granfeldt PowerShell Management Agent. Start here to get up to speed with that. As detailed above this is an Import only MA so I’m not providing an Export Script and the Password is redundant. The script files need to be present but will be empty

Schema Script

The Schema Script below covers the core attributes associated with IdentityNow Governance Groups.

Import Script

The Import Script unlike the Roles Management Agent can use v2 Authentication. As such we don’t need to perform additional effort to provide the necessary credentials.

Your v2 IdentityNow credentials need to be provided on the Management Agent Connectivity Configuration page. The Username and Password Authentication options take the v2 API Client ID and API Client Secret respectively.

IdentityNow Governance Groups MA Connectivity Username Password

NOTE: The Import Script is also configured to page the import of Governance Groups. The Page Size is configured in your Run Profile.

Make the following update for your implementation;

  • Line 24 for your IdentityNow Orgname

Customisation

Depending on what you want to do with it, will depend on how you want Identity Manger to consume the data. You will likely want to;

  • Create a new ObjectType in the Metaverse along with the attributes associated with IdentityNow Governance Groups
  • Flow the information in and perform any logic
  • Create an Export Script that will;
    • create Governance Groups in IdentityNow
    • update Governance Groups in IdentityNow

Summary

Using this base management we can get connectivity and visibility of IdentityNow Governance Groups in Microsoft Identity Manager.

SailPoint IdentityNow Roles Management Agent for Microsoft Identity Manager

This is the first post in a series where I will provide a number of base-level Management Agents for Microsoft Identity Manager to integrate with SailPoint IdentityNow. Whilst the two products have areas of competing/equivalent functionality there are other aspects where integration of the two compliment each other. Whilst that is not the purpose of this post, through the series of upcoming posts it will be relatively easy to extrapolate how the two products can happy co-exist and orchestrate each other for certain functions.

This Management Agent is for Microsoft Identity Manager to have visibility of IdentityNow Roles (see customisation at the end for me functionality).

For more information on IdentityNow Roles see this post where I detailed Creating Roles as well as updating/managing them via API. The MA also consumes whether the Role is requestable that I covered in this post.

Notes

  • The Management Agent is a Full Sync only Management Agent. This is because the IdentityNow API doesn’t expose differential style requests. That is also why this is a single function Management Agent (just for Roles).
  • The Management Agent is configured for Paging the results back into Identity Manger. For more details on that see this post.

Prerequisites

  • On your MIM Sync Server you will need the PowerShell Community Extensions (PSCX)  for the Get-Hash cmdlet
  • The Management Agent uses IdentityNow v3 Authentication. You will need to request the API Keys from your SailPoint Customer Success Manager. Details on v3 Authentication can be found in this post
  • The Management Agent leverages the Granfeldt PowerShell Management Agent. Start here to get up to speed with that. As detailed above this is an Import only MA so I’m not providing an Export Script and the Password is redundant. The script files need to be present but will be empty

Schema Script

The Schema Script below covers the core attributes associated with IdentityNow Roles.

Import Script

As IdentityNow v3 API Authentication requires a number of artifacts, we need to make sure we secure them all appropriately.

For the Admin Username and Password we will do that by exporting them to an XML file using Export-CLIXML and then in the Import Script, import them using Import-CLIXML. Those cmdlets respect the context by which the credentials were exported and will only be able to access them when imported under that same context. As our Management Agent will be run by the MIM Sync Server Service Account we need to create the credentials file using that login. To do that;

  • temporarily reconfigure the MIM Sync Service Account so that it can logon locally
    • On the MIM Sync Server open Local Security Policy = > Local Policies => User Rights Assignment => Deny log on locally and remove the MIM Sync Server Service Account
    • repeat for Deny access to this computer from the network
  • Logon to the MIM Sync Server using the MIM Sync Server Service Account
  • Run the following to create the credential file and put the credential file in the Extensions\yourRolesMA directory
$adminUSR = [string]"Partner_Admin".ToLower()
$adminPWDClear = 'myStr0ngP@$$w0rd'
$adminPWD = ConvertTo-SecureString $adminPWDClear -AsPlainText -Force
$Credentials = New-Object System.Management.Automation.PSCredential $adminUSR,$adminPWD
$Credentials | export-clixml c:\temp\RoleAdminCred.xml
  • IMPORTANT: Add the MIM Sync Server Service Account back  into the Deny access to this computer from the network and Deny Logon Locally policies

The IdentityNow v3 API Credentials are stored on the Management Agent Connectivity Configuration page. The Username and Password Authentication options take the v3 API Client ID and API Client Secret respectively.

MA Configuration Username Password ClientID Client Secret.PNG

Make the following updates for your implementation:

  • Line 24 for your IdentityNow Organisation name
  • Line 27 for the location and name of the credentials file created above

Customisation

Depending on what you want to do with it, will depend on how you want Identity Manger to consume the data. You will likely want to;

  • Create a new ObjectType in the Metaverse along with the attributes associated with the Roles
  • Flow the information in and perform any logic
  • Create Roles in IdentityNow
  • Update Roles in IdentityNow

Summary

Using this base management we can get connectivity and visibility of IdentityNow Roles in Microsoft Identity Manager.

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

API Error when ContentType is set.PNG

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;

Manual Task Details.PNG

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.

Individual Task.PNG

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.

Complete Task.PNG

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

Complete in Portal.PNG

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.

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.

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.