Update: Oct 2019. Leveraging the SailPoint IdentityNow API's is now easier using the SailPoint IdentityNow PowerShell Module.
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;
- Reporting on SailPoint IdentityNow Identities using the ‘Search’ (Beta) API and PowerShell
- Authoring Identities in SailPoint IdentityNow via the API and PowerShell
- Lifecycle Management of Identities in SailPoint IdentityNow via API and PowerShell
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)
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;
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.
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
The process is;
- Generate the Request to the Token Endpoint
- Submit the request and obtain a token
- Execute subsquent requests with the Bearer Token received in Step 2
- 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
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.