Granfeldt PowerShell Management Agent Schema HRESULT: 0x80231343 Error

Yesterday I was modifying the Schema configuration on a Granfeldt PowerShell Management Agent on a Microsoft Identity Manager 2016 SP1 Server.

I was changing the Anchor attribute for a different attribute and on attempting to refresh the schema or view the configuration I got the following error;

Unable to retrieve schema. Error: Exception from HRESULT 0x80231343

Unable to retreive Schema.PNG

I knew I’d seen this before, but nothing was jumping to mind. And this was a particular large Schema script.

After some debugging I realized it was because the attribute I had changed the Anchor attribute too, was also listed in the Schema script. It wasn’t obvious as the attribute entry was multiple pages deep in the script.

Essentially if you are seeing the error Unable to retrieve schema. Error: Exception from HRESULT 0x80231343 there are two likely causes;

  • you haven’t declared an Object Class e.g User
    • $obj | Add-Member -Type NoteProperty -Name “objectClass|String” -Value “User”
  • the attribute you have as your anchor is also listed as an attribute in the schema script e.g
    • $obj | Add-Member -Type NoteProperty -Name “Anchor-ObjectId|String” -Value “333a7e07-e321-42ea-b0a5-820598f2adee”
    • $obj | Add-Member -Type NoteProperty -Name “ObjectId|String” -Value “333a7e07-e321-42ea-b0a5-820598f2adee”
      • you don’t need this entry, just the Anchor entry

Hopefully this helps me quickly find the reason next time I make a simple mistake like this in the Schema script.

 

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.

Using Invoke-WebRequest calls within a Granfeldt PowerShell MA for Microsoft Identity Manager

MIM Sync Service Account IE Security Settings

If you use PowerShell extensively you should be familiar with the Invoke-RestMethod cmdlet and the ability for PowerShell to call API’s and receive information. The great thing about Invoke-RestMethod is the inbuilt conversion of the results to PowerShell Objects. However there are times when you need the raw response (probably because you are trying to bend things in directions they aren’t supposed to be; story of many of my integrations).

From within Granfeldt PowerShell Management Agent script(s) that use Invoke-WebRequest calls, these will in turn leverage the Internet Explorer COM API on the local machine. That means the account that is performing those tasks will need to have the necessary permissions / Internet Explorer configuration to do so.

Enabling Invoke-WebRequest for the FIM/MIM Synchronization Server Service Account

Logon to your Microsoft Identity Manager Synchronization Server using the Service Account associated with the Forefront Identity Manager Synchronization Service. If you’ve secured the service account properly you will need to temporarily allow that service account to Log on Locally.

FIM Sync Service Account.PNG

Open Internet Explorer and open Internet Options. Select the Security Tab, the Internet zone and select Custom Level.

Locate the Scripting section and set Active scripting to Enable. Set the Allow websites to prompt for information using scripted windows to Disable. Select Ok and Ok.

MIM Sync Service Account IE Security Settings.PNG

With the configuration completed, go back and change back the Forefront Identity Manager Service Accounts’ local permissions so it can’t logon locally.

Your Import / Export Granfeldt PowerShell Management Agent Scripts can now use Invoke-WebRequest where the requests/responses use the Internet Explorer COM API and respect the Internet Explorer security settings for the user profile that the requests are being made by.

Hopefully this helps someone else that is wondering why the scripts that work standalone fail when operating under the FIM/MIM Sync Service Account by the Granfeldt PowerShell Management Agent.

Microsoft Graph and the $whatIf option

What we know today as the Microsoft Graph has evolved over the last few years from a number of different API’s that were developed by different product teams within Microsoft (e.g Azure AD, Office 365, Outlook). That doesn’t mean the old ones have gone away, but it does mean that we can connect to the Microsoft Graph API and leverage the API’s we used to interface with independently.

What this means is, where information is actually coming from is obfuscated. But there is a way to find out where it is coming from.

The $whatIf option is a mostly undocumented switch that provides visibility on the source of information returned by Microsoft Graph from differing back-end API’s. The easiest way to use this is via the Graph Explorer.

Running a query using Graph Explorer for /me returns a bunch of information.

Graph me base request.PNG

Running the same query with the $whatIf option returns what the /me call actually performs on the API.

Graph me base request with whatIf.PNG

In this case it returns the base user information as shown below in the $select query.

{“Description”:”Execute HTTP request”,”Uri”:”https://graph.windows.net/v2/dcd219dd-bc68-4b9b-bf0b-4a33a796be35/users(’48d31887-5fad-4d73-a9f5-3c356e68a038′)?$select=businessPhones,displayName,givenName,jobTitle,mail,mobilePhone,officeLocation,preferredLanguage,surname,userPrincipalName,id“,”HttpMethod”:”GET”}

If I change the query to a specific user and request information that comes from different products behind the Microsoft Graph and I use the $whatIf option we can see where the data is coming from.

https://graph.microsoft.com/v1.0/users/MeganB@M365x214355.onmicrosoft.com?$select=mail,aboutMe&whatIf

The screenshot below shows that the request actually executed 2 requests in parallel and merge the entity responses

Data from multiple APIs.PNG

The result then shows where the two queries went. In this case graph.windows.net and sharepoint.com.

{“Description”:”Execute 2 request in parallel and merge the entity responses”,”Request1“:{“Description”:”Execute HTTP request”,”Uri”:”https://graph.windows.net/v2/dcd219dd-bc68-4b9b-bf0b-4a33a796be35/users(‘MeganB@M365x214355.onmicrosoft.com’)?$select=mail”,”HttpMethod”:”GET”},”Request2“:{“Description”:”Execute HTTP request”,”Uri”:”https://m365x214355.sharepoint.com/_api/SP.Directory.DirectorySession/GetSharePointDataForUser(’48d31887-5fad-4d73-a9f5-3c356e68a038′)?$select=aboutMe”,”HttpMethod”:”GET”}}

Summary

The next time you’re trying to workout where information is coming from when using the Microsoft Graph API, try adding the $whatIf switch to your query and have a look at the Response.

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

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

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

The basis of the logic is;

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

The Script

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

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

Update;

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

Example

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

Search and return all objects on an IdentityNow Source

Summary

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

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.

Adding Delta Sync Support to the Microsoft Identity Manager PowerShell Management Agent for Workday HR

Recently I posted a sample Microsoft Identity Manager Management Agent for Workday HR. Subsequently I also posted about some updates I made to the WorkdayAPI PowerShell Module to enable functionality to specify the time period to return changes for. This post details updating  my sample Workday Management Agent to support Delta Synchronisation.

WorkdayAPI PowerShell Module

First up you will need the updated WorkdayAPI PowerShell Module that provides the Get-WorkdayWorkerAdv cmdlet and can take a time period to return information for. Get the updated WorkdayAPI PowerShell Module from here

Update the PowerShell Module on the MIM Sync Server. The module by default will be in the  C:\Program Files\WindowsPowerShell\Modules\WorkdayApi folder.

You will need to unblock the new files.

Get-ChildItem 'C:\Program Files\WindowsPowerShell\Modules\WorkdayApi' | Unblock-File
Get-ChildItem 'C:\Program Files\WindowsPowerShell\Modules\WorkdayApi\scripts' | Unblock-File

Updated Schema

In the updated Management Agent I’m also bringing into MIM additional attributes from the other enhancements I made to the PowerShell Module for HireDate, StartDate, EndDate, Supplier and WorkdayActive. The updates to the Schema.ps1 are shown below.

$obj | Add-Member -Type NoteProperty -Name "HireDate|string" -Value "string"
$obj | Add-Member -Type NoteProperty -Name "StartDate|string" -Value "string"
$obj | Add-Member -Type NoteProperty -Name "EndDate|string" -Value "string"
$obj | Add-Member -Type NoteProperty -Name "Supplier|string" -Value "string"
$obj | Add-Member -Type NoteProperty -Name "WorkdayActive|Boolean" -Value $True

The full updated Schema Script is below;

With the Schema Script updated, refresh the Management Agent Schema.

Update Schema

You can then select the new attributes in the Workday MA under Select Attributes.

Select New Attributes.PNG

Then select Ok.

Attributes Selected.PNG

Updated Import Script

The Import Script has a number of changes to handle creating and updating a WaterMark File that is used to store the date stamp of the last run. Also updated in the Import Script is the change to use the Get-WorkdayWorkerAdv cmdlet over the Get-WorkdayWorker cmdlet so that a time period can be specified, and to retrieve the additional attributes we just added to the schema.

Update:

  • Line 11 for the path and name of the Watermark File you wish to use
  • Line 31 for the URI of your Workday Tenant

Executing the Management Agent using a Delta Import Delta Sync Run Profile

After creating a Delta Import Delta Sync Run Profile we can now run a Delta Sync. The following graphic is after seeding the WaterMark file (with the last run time in a format like this 2018-10-29T22:09:08.3628953+00:00), as by default without the WaterMark file being present a Full Import is performed by the MA as it doesn’t have a watermark to base the import time period on.

The changed records in Workday HR are then identified and those records obtained, imported and synchronised via the Management Agent.

Delta Sync.PNG

Summary

Using Delta Synchronisation functionality from Workday HR allows for much quicker synchronsiation from Workday HR to Microsoft Identity Manager.