Example of calling GroupWise REST API from Identity Manager policy - Part 1

Example of calling GroupWise REST API from Identity Manager policy - Part 1

Use case requirement:

Recently a customer had the following use case requirements to be satisfied via the Identity Manager GroupWise REST connector.

  1. Obtain a list of GroupWise groups(Distribution lists) that the user is currently a member of.

  2. The ability to remove all group membership in cases when the user gets disabled in IDVault.

  3. When users are deleted in the Identity vault, it was required for the user to be dissociated with LDAP in GroupWise (only remove the internal ldap association which is shown in the red box below) and not actually delete the GroupWise account. (Currently being worked as an enhancement)


GWDissociate

At the time of writing this cool solution, the GroupWise REST connector (version 4.0.0.1) has the ability to satisfy all of the traditional requirements and some of the above are being currently worked on as enhancements. The others fall into requirements of a specific implementation. Hence in this article we will see how some of extended GroupWise REST APIs can be called from Identity Manager rules.

Approach:

There are 2 ways to solve this, first being the ecma script way and the second calling an external java class. In both approaches the REST calls will be made against the target GroupWise 2014 system with the desired functional URI that produces the expected results from GroupWise to Identity manager. In this case external java class is used.

Solution:

  • Java components


The solution uses Apache HttpComponents project (Apache HttpComponents). The following jar files

org.apache.httpcomponents.httpclient_4.5.x.jar

org.apache.httpcomponents.httpcore_4.4.x.jar

commons-codec-1.3.jar

commons-logging.jar

gwutils_(xx).jar (in the zip file attached below)


will need to be placed in the eDirectory lib folder (default location on Linux: /opt/novell/eDirectory/lib/dirxml/classes/).

(Note: The solution has been tested only with IDM 4.5.2 on SLES 11 and GroupWise 2014)

  • Identity Manager components


The solution leverages the driver's startup, shutdown and output transformation policy sets to talk to GroupWise REST interface. The java http components are initialized during the driver startup and they get gracefully released when the driver is shutdown by the rules in the shutdown policies. For the purpose of this article, the actual policy where the request is initiated and a response obtained is placed in the output transformation policy set. The java class depends on the GroupWise driver's configuration parameters to initialize itself with the REST interface.

Since the admin console uses a secure http connection, a separate keystore with the admin-console server key will be created and used for simplicity, but if a keystore already exists with the GroupWise server key, the same can be used. A few global configuration parameters will be add and used (explained below in the installation section).

Installation:

  • Copy the libraries to the IDM server


A. Make a good working copy of the existing GroupWise Rest driver in Designer before making any changes to the driver.

B. Stop eDirectory

C. Copy the attached gwutils.jar, org.apache.httpcomponents.httpclient_4.5.1.jar and org.apache.httpcomponents.httpcore_4.4.4.jar (currently the version tested with) to the /opt/novell/eDirectory/lib/dirxml/classes folder

D. Start eDirectory so the libraries can be loaded by the JVM.

  • Creating the keystore with the GroupWise server certificate


In this section, a java keystore will be created and we are going to obtain the GroupWise server's public key certificate to be used in the httpclient to make a secure connection to the GroupWise system. Follow the steps as shown below to accomplish that.

Access the secure GroupWise admin console page (https://<server ip>:9710/gwadmin-console) in a browser

Cert1

Click on the lock button beside the address bar and expand it.

Cert2

Click on "More information" to view the certificate details

Cert3

Click on View Certificate -> Go to the Details tab and click on Export

Cert4

Give a name to the certificate and save it in the "DER" format on to the local workstation.

Cert5

The util requires that the Groupwise server certificate be added to the default JVM's keystore cacerts. This JVM is the one under which Identity Manager engine will run. Hence copy the downloaded server certificate to the Identity Manager server. On linux the JVM used by Identity Manager in a default installation is /opt/novell/eDirectory/lib64/nds-modules/jre. Inside lib/security the cacerts can be found. Use the below command to import the Groupwise server certificate in the keystore.

cert-import

keytool -import -trustcacerts -alias gw14 -file /tmp/GWServerCert.der -keystore cacerts

The default cacerts file's password is 'changeit'. If this has been changed from the default then make sure the same is edited in the Named Password configuration in the section down after importing the package.

 

Importing the demo package to the IDM connector

The solution discussed in the article is made available as a package which is available in the zip file at the bottom. It needs to be made available in the GroupWise designer project. Download the attached zip file onto the machine where designer is installed. Extract the zip and examine the folders.

In designer open the project that has the existing GroupWise REST driver or if this is a new driver creation import one with the GroupWise REST base package, configure it to connect to GroupWise. Once the connector is found to be operational, follow the below steps to get the functionality discussed here into the existing driver.

Now go to the outline view of the project and import the package (package jar attached to this article) provided.

importPackage

Click "Browse" and select the folder where the <package-name>.jar is available on the designer workstation

importPackage-1

NOTE: Ignore the package name shown in the above screen shot, but make sure the one in the GWRestUtils\GroupWise-Package is selected from the extracted zip file is selected.

pack-import

 

pack-import1

Once the package is imported and the project saved, it will be available for installation in the "Packages" section of the Groupwise driver properties. From the driver properties window browse to the packages section.

Click the plus button and add the GroupWise Custom REST Api package to the driver. Follow the configuration prompts and finish adding the new package to the driver.

pack-import2

After completing the prompts, edit the driver properties and select Named Passwords section. The package import adds 2 named passwords that are used by the utils.

GWUtils: JVM cacerts password: This is the password for the default JVM's keystore file. The factory default password is 'changeit'. If this has not been changed ever, then nothing needs to be edited for this named password as the package sets it to the factory default. If the default password has been changed in your installation then make sure the same is reflected here as well.

GWUtils: GW Application Password: This is the password that should match the Application password that is specified during the driver configuration. This password will be used by the account configured in the driver to connect to the Groupwise system.

This is essential or else the HttpClient connection will not be successful.

pack-import3

 

Click OK to save the changes and save the designer project as well so that all the changes made so far are retained.




Details of Custom IDM policies

If all the above steps are carried out in sequence then, at this stage there will be 3 new policies added to the driver which can be viewed in the fish bone view in Designer.

Startup policy -> Initialize GWUtils for extended REST Operations

In this policy, the driver configuration parameters are read to determine the GroupWise system to which the connection needs to be made. A secure HttpClient will be initialized only one time during the starting up of the driver.

Shutdown policy -> Finalize GWRestUtils

Shutdown policy will ensure that the secure HttpClient that was created during the driver startup will be gracefully released.

Output transformation -> GW14 REST Operations

This policy is where the business logic will be handled and appropriate functions are called by making external calls to the custom java class to perform very specific tasks in GroupWise system via REST calls. In this particular case, as explained before, the focus has been placed on demonstrating the ability to call the REST apis and not on the business logic to trigger the api call from the IDM actions. So when using this functionality please make sure that these policies are triggered based on your specific use case conditions and not the ones used in this demonstration.


(Note: If the calls have to be made from different policy sets, it is possible to do so. Move the policies into any policy sets in the driver, however ensure that the gwutils namespace is added as shown below so the extension becomes available.

NameSpace

)

RULE#1 : List groups that the user is a member of in GW


(In this demo a successful read to fetch all groups that the user is a member of will be triggered when the Given Name is triggered)

REST CALL : https://<serverip>:<port>/gwadmin-service/domains/<domain-name>/postoffices/<post-office>/users/<username>/groupmemberships

REST ACTION : GET

Java method : getGWGroupMembershipForUser(String userName)

Trace:
[02/17/16 23:49:40.670]:GroupWise 2014 REST ST:          token-xpath("gwutils:getGWGroupMembershipForUser($varUserName)")
[02/17/16 23:49:40.670]:GroupWise 2014 REST ST: == GWRestUtils ==> : Preparing to fetch GroupWise groupmemberships for user [gwuser50]
[02/17/16 23:49:40.688]:GroupWise 2014 REST ST: == GWRestUtils ==> : <?xml version="1.0" encoding="UTF-8"?><list xmlns:ns2="http://www.w3.org/2005/Atom"><object xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="membership"><domainName>GW14LAB</domainName><id>GROUP.GW14LAB.gw14PO.GWGrp1</id><name>GWGrp1</name><postOfficeName>gw14PO</postOfficeName><participation>PRIMARY</participation></object><object xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="membership"><domainName>GW14LAB</domainName><id>GROUP.GW14LAB.gw14PO.GWGrp2</id><name>GWGrp2</name><postOfficeName>gw14PO</postOfficeName><participation>PRIMARY</participation></object><resultInfo><outOf>2</outOf></resultInfo></list>
[02/17/16 23:49:40.689]:GroupWise 2014 REST ST: == GWRestUtils ==> : Successfully fetched GroupWise groupmemberships for user [gwuser50]

Output:
<?xml version="1.0" encoding="UTF-8"?>
<list xmlns:ns2="http://www.w3.org/2005/Atom">
<object xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="membership">
<domainName>GW14LAB</domainName>
<id>GROUP.GW14LAB.gw14PO.GWGrp1</id>
<name>GWGrp1</name>
<postOfficeName>gw14PO</postOfficeName>
<participation>PRIMARY</participation>
</object>
<object xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="membership">
<domainName>GW14LAB</domainName>
<id>GROUP.GW14LAB.gw14PO.GWGrp2</id>
<name>GWGrp2</name>
<postOfficeName>gw14PO</postOfficeName>
<participation>PRIMARY</participation>
</object>
<resultInfo>
<outOf>2</outOf>
</resultInfo>
</list>

Note: Once the XML ouput is obtained as a result of the REST call it will be parsed by the policy action for each object element node returned. In this instance the name element node is traced out for demo purposes. Similarly any child element node under the object node can be obtained to best suit the problem that is being solved. Here is the place you can add any of the custom logic that is required to further act on the output.

RULE#2 : Remove user from all GW groups if disabled in IDV


(In this demo, the group membership removal is triggered when the "Login Disabled" gets set to "TRUE" in IDVault)

REST CALL: https://<serverip>:<port>/gwadmin-service/domains/<domain-name>/postoffices/<post-office>/users/<username>/groupmemberships

REST ACTION: DELETE

Java method: removeMembershipFromAllGroups(String userName)

Trace:
[02/18/16 00:00:32.502]:GroupWise 2014 REST ST:          token-xpath("gwutils:removeMembershipFromAllGroups($varUserName)")
[02/18/16 00:00:32.502]:GroupWise 2014 REST ST: == GWRestUtils ==> : Removing user [gwuser50] from all group in GW
[02/18/16 00:00:32.502]:GroupWise 2014 REST ST: == GWRestUtils ==> : Successfully removed all groupmemberships in GW for user [gwuser50]

Output:

This function call returns the actual http response code.

RULE#3 : Remove GW directory link when user in IDV is deleted


(In this demo user dissociation is triggered when an associated user to GroupWise is deleted in IDV)

REST CALL: https://<serverip>:<port>/gwadmin-service/domains/<domain-name>/postoffices/<post-office>/users/<username>/directorylink

REST ACTION: DELETE

Java method: dissociateGWUser(String userName)

Trace:
[02/18/16 00:04:30.164]:GroupWise 2014 REST ST:        arg-string(token-xpath("gwutils:dissociateGWUser($varUserName)"))
[02/18/16 00:04:30.164]:GroupWise 2014 REST ST: token-xpath("gwutils:dissociateGWUser($varUserName)")
[02/18/16 00:04:30.164]:GroupWise 2014 REST ST: == GWRestUtils ==> : Dissociating user [gwuser50] in GW
[02/18/16 00:04:30.164]:GroupWise 2014 REST ST: == GWRestUtils ==> : Successfully dissociated user [gwuser50] in GW

Output:

This function call returns the actual http response code.

Proceed to view the Part 2 of this article https://www.netiq.com/communities/cool-solutions/example-calling-groupwise-rest-api-identity-manager-policy-part-2/ where a more generic approach is discussed to make more calls to GroupWise REST Api. The functionality discussed here will also be included in the binary attached to part 2.

Hope this might be helpful and also any feedback is accepted gladly.

Download GWRestUtils2.0

Download GWRestUtils_2.5 (This version has been compiled for java 1.8 )

 
Attachments

DISCLAIMER:

Some content on Community Tips & Information pages is not officially supported by Micro Focus. Please refer to our Terms of Use for more detail.
Top Contributors
Version history
Revision #:
1 of 1
Last update:
‎2016-02-19 15:24
Updated by:
 
The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.