Guides

IQService: June 2022 Release – Auto Update Feature

So this snuck it without much fanfare but I was waiting for this feature (and just in time) as a client had just asked about it.

IDN is a great SaaS platform application which requires very little on-prem deployments. VA (Virtual Appliance) is obviously the key one but all the security and patching is managed by SailPoint itself. 

IQService is another must have tool for most clients as it is needed for AD Provisioning (among few other things it does for other connectors). So its generally deployed in nearly every client instance. One of the main thing about this is that it was not autoupdated and thus client needed to download the latest and do an update themselves. Although its not a lot (maybe twice a year) but still good to have a software which can patch itself to latest version. And of course this is optional and who don’t want this can choose not to install the feature but we highly recommend it.  

You DON’T need to give internet access to the IQService boxes to download latest updates. The latest IQService binaries are pushed to and are present on VA. This is via our existing process of update bundles being pushed to VA from cloud. At connector level, version is checked for IQService and if there is mismatch (new version available), latest version will be pushed out to UpdateService from the VA (As they already have line of sight to each other). Then UpdateService will coordinate and update local and then remote services.  It is quite simple process where in the respective services are stopped and binaries are replaced.

Article assumes you know what IQService is and where to deploy it. I will quickly give some commands on how to do so with the latest release. I will show various setups and quick commands to run to update them.

NOTE: You must have Provisioning License to use IQService. Talk to your CSM about it and make sure you are licensed to use it.

Documentation: https://documentation.sailpoint.com/connectors/iqservice/help/integrating_iqservice_admin/intro.html

Uninstall Previous IQService

Single Box install with Fallback Implementation

Assumptions
  • Installing TLS port only: 5060
  • UpdateService Port: 5062
  • User authenticating against IQService: abc\sailpoint
  • Software downloaded and extracted: C:\SailPoint\IQService\
  • Domain: abc.local
  • Certificates already configured and working for TLS (Check this post to do self sign cert for home labs)
  • Firewall is open for TLS port. You don’t have to open for 5062 as no remote IQService is connecting to it in this configuration. 
Check Status of Services
Check Status of UpdateService

IQService UpdateService

Multiple Box Install with Client Side Load Balancer

Assumptions
  • Installing TLS port only: 5060
  • UpdateService Port: 5062
  • User authenticating against IQService: abc\sailpoint
  • Software downloaded and extracted: C:\SailPoint\IQService\
  • Domain: abc.local
  • Certificates already configured and working for TLS (Check this post to do self sign cert for home labs)
  • Firewall is open for ports 5060 TLS on both servers and on primary server for UpdateService 5062 to accept incoming requests from other IQService boxes for update check.
  • Installing on two boxes: iqservice1.abc.local (considered primary) ; iqservice2.abc.local (considered secondary)
  • Box boxes can talk to each other for UpdateService
iqservice1.abc.local (installing UpdateService here)
iqservice2.abc.local (Going to connect to above UpdateService Instance)

That is it!!! you should have an IQService which can update itself and keep the environment updated with latest features and bug fixes.

 

By Piyush Khandelwal, ago

IDN + Transforms + VS Code + Snippets = Lightning Speed #IDN101

Hiya Folks

Happy New Year!!!  

I have written a few posts before on how to write nested transforms and about a few new transform types available. But it still look like a tedious task when writing a transform – especially a complex one. It is as powerful as its confusing sometimes. I still don’t have full grip on the capabilities or the possibilities I can achieve without the need of rules. 

I love VS Code and especially its features and plugins. I use it extensively and also advocate the same to all my colleagues and clients for doing JSON and CSV files with IDN (and java coding obviously).

Few years ago one of my good mate Thomas Bui had shown me an interesting way to not need to remember syntax of each transforms while writing it. So credits to him.

Here I have built a package and hopefully show you how to deploy it in VS code and using the Snippet feature quickly write transforms with less errors.

It’s pretty simple. View the video I have made in VS Code (Works on Windows / Mac) . Please click on the gif to enlarge it. The embedded one is not rendering properly for some reason.

You will see how quickly I wrote a firstValid transform and replaced few lines with accountAttributes transforms (nested) and created a “Get New Dept” Transforms in couple of sec.

Steps are as below

  1. Open “Configure User Snippets” in VS Code Preferences
  2. Click on “New Global Snippets File”
  3. Call it say “transforms”
  4. In the file opened, replace the entire content with below code snippet
  5. Save and close the file 
  6. Now start typing the name of the transform (e.g. firstValid) and it will show up.
  7. Press Enter and it will show you the code

That’s it

Hopefully this was helpful and makes it easy for you to write transforms for IDN. Feel free to expand the snippet by adding your own shortcuts of complex transforms or code which you use often and feel free to share it below or the article

Cheers!!!

 

By Piyush Khandelwal, ago

How to Search Non-Indexed Account Attributes in IDN Rules

Hey Folks!!!

Anyone well versed with IDN Rules will know that there has been some historic limitations on what attributes we can and can’t use for uniqueness search or for other such methods. We were generally tied to “Account ID” and “Account Name” attribute in each source which were indexed in the DB which could be used in rules to do so. 

Workaround till date had been to promote these attributes to an identity attribute and index them (which again had limitations of it own in terms on number of attributes and size of attribute).

Now we have a way to do this. Personally been involved with the product team and engineers in getting this shaped and delivered so a bit proud of this work. It is a great first start and will help you in doing so many use cases much simpler now. 

Lets take a use case and a walkthrough on how you can set this up

Use Case

We want to generate a new email address which must have a unique prefix ([email protected]) by checking against the “mail”, “userPrincipalName”, “proxyAddresses” attributes across 3 x AD connectors. 

Note: Sources don’t have to be AD explicitly and can be virtually any source (AAD, ServiceNow, Okta, Workday etc) 

Design

Now anyone who has worked with rules before would have known that this use case was not very easy to implement. You would have to promote these attributes, index identity attribute and then use it in the rule. Now we can create searchable attributes in the backend via API and use these in the rule. 

High Level Steps are

  • Identify Source ID and attributes
  • Create Searchable Attributes
  • Do an unoptimised aggregation if source already exists (like production tenant) to populate these searchable attributes.
  • Use new methods in rules to search for uniqueness

Identify Source ID and Attributes

Now we have 3 x AD source in our design. For each of them we need to get their sourceID. You can fetch them with an API call

Where

  • {{api-url}}: This is your tenant URL in form of https://tenantName.api.identitynow.com
  • {{source-id}}: This is the number you see in your browser URL when visiting the source via UI

In the response you will get an externalId with a value like 2c9180867745f3b10177469563be7451d

Gather the externalId for all three sources you want to build it for. 

Create Searchable Attributes

Now when you have all the SourceID’s we need to map and create searchable attributes. We will design 3 attributes (one for each – mail, userPrincipalName, proxyAddresses). It takes care of multivalued attributes as well (like proxyAddresses). The below table explains the design 

Search Attribute NameAccount AttributeSource IDSource Name
allMailAddressesmail2c9180867745f3b10177469563be7451dAD Source 1
2c9180867745f3b10177469563be7451eAD Source 2
2c9180867745f3b10177469563be7451fAD Source 3
allProxyAddressesproxyAddresses2c9180867745f3b10177469563be7451dAD Source 1
2c9180867745f3b10177469563be7451eAD Source 2
2c9180867745f3b10177469563be7451fAD Source 3
allUserPrincipalNamesuserPrincipalName2c9180867745f3b10177469563be7451dAD Source 1
2c9180867745f3b10177469563be7451eAD Source 2
2c9180867745f3b10177469563be7451fAD Source 3

Create each of the attribute via Create Search Attribute Config API

Similarly do it for other 2 attributes as well

Once all are created you can do a GET call to check all attributes

You should see all the above listed. 

Populate Searchable Attributes

Now if these are existing sources with accounts in them, simply do a once off unpotimized aggregation of each source via the following API call. 

Once done for all sources, the search attributes get populated in the backend. Currently you can’t check them with the UI or API calls. Any new accounts which get created after this or come as aggregation (delta or full) will automatically keep updating the search attribute. So once set, you don’t have to do anything. Also new account created is populated immediately. So no need of aggregation of it. So if you are creating multiple users in concurrent – uniqueness check will still capture the previous value calculated – no need to wait for aggregation.

Use New Methods in the Rules

Our IDNRuleUtil guide has been updated with few new methods. Two in particular which use these attributes are 

attrSearchCountAccounts(): This will be helpful to use for uniqueness search

attrSearchGetIdentityName(): This will be helpful in say a correlation rule. 

The link above has a bit more technical in-depth on what parameters are required by these methods and what is the return. But I will show you how to use the attrSerachCountAccounts() method in an example of uniqueness search. 

AttributeGenerator Rule

Will short type the logic what I have followed here. 

  • Create a list of 3 attributes with sourceID in them. This is required to pass the list to the new method.
  • Get the firstName and lastName from identity attribute, sanitise it and pass it to generateUniqueEmail() method
  • emailSuffix is also brought from identity attribute. This logic is already done via Transforms on what user email domain or suffix is suppose to be
  • In generateUniqueEmail() create a emailPrefix attribute and call isUnique() method.
  • isUnique() is where the magic happens
    • We are using StartsWith option (there is Equals also available). Reason being all the data coming from AD will be in some form of “[email protected], [email protected]”. We want to match “[email protected]” only as we don’t care about exact match or equals match. Remember both are case-insensitive checks.
    • First check with proxyAddressSources in the idn.attrSearchCountAccounts() call
      • Here we have appended SMTP / SIP to do a startsWith check as we know that these are the known values we need to check in proxy address. We don’t have a contains. Also since its case-insensitive we don’t need to worry about camel casing or other such things. Data normally looks like “smtp:[email protected]” , “SIP:[email protected]”.
      • There are other such prefix found if proxyAddress attribute which we didn’t care about check but if your use case does, just add them and search as above.
      • If return == 0 means nothing is found, thus unique and move on to next check
      • Else isUnique == false and will return that value
    • Else check with upnSources source. Same logic as above
    • Else check with mailSources source. Same logic as above
      • If no account found here, isUnique is set to true and thus isUnique() has passed and the new email address is generated
    • If still a value is found, isUnique is set to false and thus isUnique() failed and new iteration starts
  • Max Iteration is set to 99 and then fail

Use case

Rehire an account who comes back after 5 years with the same AD account. 

Design

Now the account could be sitting as an uncorrelated account in IDN and we want to resurrect it. We can only search against the accountID or accountName as discussed previously and say if the correlating factor is employeeID which is not a part of either of these attributes.

Correlation Rule

  • We create an attribute like above called “allADEmployeeNumbers” and populate that with AD – employeeID (or whatever you may have)
  • We do an unoptimised aggregation to populate the search attribute
  • On an aggregation of an authoritative source, we have a correlation rule attached
    • It grabs the “employeeNumber” coming in from the source
    • Calls attrSearchGetIdentityName() to find that employeeNumber in the searchable attribute.
      • If found it returns an IdentityName of the cube and this can be used to correlate
      • If not found it returns an empty returnMap i.e. creates a new identity.
  • During design we took care of the following scenarios
    • It should return null if it found multiple names or no names. 
    • It should return one identityName even if multiple links were found but single identityName (i.e. say if you had multiple employeeNumbers in links but all are attached to cube). Like in a daisy chain scenario.

Possibilites

You can see the power of these new methods and how you can use them. Some of my thoughts here on possibilities. 

  • We can daisy chain them like above to search for multiple attributes in multiple sources as per your pattern.
  • We can use these for more attributes from accounts without the need to identity attribute creation and hitting limits on indexing.
  • Resurrections with attributes not indexed is also now pretty easy. 

Hope this really help you in your future implementations!!!

By Piyush Khandelwal, ago

How to upload Connector Rules into IDN via API

So I did a post couple of days ago that now we are allowed to upload some rule types via API

Here is a quick guide on how to do so. In this example, I will take a very basic BuildMap rule. 

Previously we would submit the rule like above to ES team to upload. Now you just need to take the code and upload yourself.

Now the real trick – You need to escape the actual java code else you will not be able to upload it and postman will show errors.

So head down to https://www.freeformatter.com/java-dotnet-escape.html and paste the code part of above. There are other such websites or can be some easier local method in your editor.

You will get some output like

Rest is then easy as per the API links

You should get a 201 Created and see a similar output

That is it. You should be able to see and use this rule now on your source. 

Please remember to follow the IDN Rule Guide on what is allowed and what is not.

And if you want you can reverse the process by getting existing rules via API, unescape it via the URL above and get the neat looking java code.

By Piyush Khandelwal, ago

PSA: Connector Rules can now be deployed directly by clients

In my previous guide I had mentioned that how to deploy and attach rules in IDN. But there is a big change to this announced.

Client can now directly attach what we call as “Connector Rules” into their IDN tenants without going through the rule review process. Reason behind it

Connector-Executed Rules or Connector Rules are rules that are executed in the IdentityNow virtual appliance, and are usually an extension point of the connector itself. The rules are commonly used for performing complex connector-related functions, and likewise are very specific to only certain connectors. Because these rules execute in the virtual appliance, they do not have access to query the IdentityNow data model, or fetch information from IdentityNow; instead they rely on contextual information sent from IdentityNow. Connector-executed rules may also have managed connections supplied in their contexts in order to support querying end systems or sources. While these managed connections may be used, making additional connections or call-outs is not allowed.

This should make it much easier and faster for clients to upload and modify rules themselves. The rule types allowed are

  • Before Creation Rule
  • Before Modify Rule
  • Before Delete Rule
  • After Creation Rule
  • After Modify Rule
  • After Delete Rule
  • Build Map Rule
  • JDBC Build Map Rule
  • JDBC Provisioning Rule
  • SAP Build Map Rule
  • SAP HR Provisioning Modify Rule
  • Web Services Before Operation Rule
  • Web Services After Operation Rule

This is done via REST API Calls. 

Name

Path

List Connector Rules

GET /beta/connector-rules/

Get Connector Rule

GET /beta/connector-rules/{id}

Create Connector Rule

POST /beta/connector-rules/

Update Connector Rule

PUT /beta/connector-rules/{id}

Delete Connector Rule

DELETE /beta/connector-rules/{id}

Validate Connector Rule

POST /beta/connector-rules/validate

There are some restrictions in the rule which will auto reject them

Please go and have a full read in our IDN Rule Guide

 

By Piyush Khandelwal, ago
%d bloggers like this: