Managing SailPoint IdentityNow Governance Groups via the API with PowerShell

Update: Oct 2019. Governance Groups can be easily managed using the SailPoint IdentityNow PowerShell Module.

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.

See the gist on github.

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

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.

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.

See the gist on github.

Executing the script successfully creates the group.

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

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.

See the gist on github.

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.

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.