How to remove (de-assign) a role from identity via the API
How to remove (de-assign) a role from identity via the API
There are various times when an IdentityIQ installation may need to programmatically request that a Role assignment be removed from an Identity. One example would be specific types of transfer or leaver workflows that must immediately remove certain role assignments. The best practice for how to do this has changed over the years. Significant changes were introduced with the advent of changes in the Role management APIs in the 6.3 and newer releases to support assigning a Role to an Identity multiple times. This all raises an important question: How should you remove (or de-assign) a Role from Identity via the API?
Let's start with what not to do. There are many public methods available on the sailpoint.object.Identity object that look like they would be useful for dealing with role assignment methods. These include:
identity.remove(role);
identity.removeAssignedRole(role);
identity.removeRoleAssignment(roleAssignment);
While these may have worked in earlier releases of the IdentityIQ they are not forward compatible with current or future releases of the product. Please do not call these APIs directly from custom BeanShell code or workflow code. SailPoint reserves the right to remove these methods from the public API or deprecate them in a future release. Many implementations that call these methods fail to lock Identity objects before committing changes.
What method should be used? The best practice is that you should treat a Role addition or removal like an LifeCycleManager (LCM) request. This means conceptually a role addition has a requesting party, a target identity on which the role will be removed, and some other meta data. That means you should construct a provisioning plan requesting the removal of what role(s) you want removed from the virtual application named "IIQ". The "IIQ" application is an application that can be used to make changes to an Identity's assignments inside IdentityIQ itself.
There is a distinction that can be made when removing Role assignments from an Identity. One method would be to "Remove the Role/Bundle assignment, but leave the entitlements that came from the role on the user's accounts". Another method would be to "Remove the Role/Bundle assignment, and walk down the tree of user's accounts and send off provisioning events to remove all of the entitlements supplied by that Role from from the user's accounts". This conceptually a "shallow removal" versus a "deep removal". The former is quicker and happens in IdentityIQ's database and the latter may expand to include many applications and take time for provisioning events to process.
There are a couple of ways to approach the best practice in code. One is short-winded and good for simpler circumstances but provides less visibility in the UI for what change took place. The other is longer-winded and better for circumstances where you want to see more of a paper-trail in the user interface. The longer winded method creates formal IdentityRequest objects that can be seen in the user interface under the Manage -> Access Requests menu screen.
Let's look at the shorter example first. This example is useful if you want to programmatically remove a role without approvals, email notifications, or the record of an IdentityRequest being left in the system. The code block for this approach is fairly easy.
String identityName = “mary.johnson”;
ProvisioningPlan plan = new ProvisioningPlan();
plan.setIdentity(context.getObject(Identity.class, identityName));
plan.add(“IIQ”, identityName, “assignedRoles”, ProvisioningPlan.Operation.Remove, “Some Role Name”);
Provisioner p = new Provisioner(context);
// if you want to remove the assignment without de-provisioning the entitlements set this
p.setNoRoleExpansion(true);
p.execute(plan);
You could think of this as a lightweight implementation. Many installations require a more feature-rich implementation that can be seen as an IdentityRequest much later on, days after the request was submitted. Attached is a fully functional example tested in a lab system that creates a Provisioning Plan for the Role Removals, then uses the Request Processor to launch a Workflow in the background to remove the Role(s) from the target Identity. This example provides all of the features for a completely searchable, viewable, and audit-able paper trail of why a Role was removed from an Identity.
The attachment sets the "approvalMode" to "none", which like the example above, disables approvals for the removal. If you want to require approvals for removing access then you will want to change this feature of the attached example.
Thanks for this post. We would like to remove all roles from all identities without removing the entitlements. thinking of using this code with the no role expansion option. Would you think its ok to to repeat this code thousands of time in code? As we have many identities which have role assigned..
Although i am not sure what is being tried here , Make sure you have your assigned roles with filter inactive EQ true and skip inactive identities in the refresh task , so that the roles once removed are not assigned/detected back.(or something similar based on your condition)
This code logic should ideally run in case of a leaver/transfers - so only once for an identity for an event. Unless you have thousands of leavers/transfers triggering in one go you shouldn't even worry about this.
Thanks for the reply. We are going to de assign roles from all identities using a rule. We will loop over the identities and use this code on each one. We will be deleting the roles after this as we want to get rid of roles altogether. My main concern is the performance impact in case this code runs for all identities in one go inside the rule
hi Adam, am using the mentioned code to Remove the BusinessRoles for Bulk of identities , using a task where the Task Reads identities from a file , but i don't see the result reflected immediately on the identity , is their is way to confirm if the Code actually removed the Business Role from the Identity ...
Out of curiosity, with your implementation and hardware specs, how has the performance been for you? Were you able to determine how many assignments can be processed per minute utilizing the above procedure? What type of hardware specs are you running with?
Sorry for the late reply. We ran this on a server with 8 GB Ram, Quad Core Processor. It took around 10 minutes to remove the roles for 3k identities approx
