Enabling IDM Mobile Approvals in IDM 4.0 SP2 and IDM 4.5

If you are using the IDM 4.0 SP2 Advanced Edition with additional toys like HPD, or if you are using IDM 4.5 AE with the same pieces, you may have the opportunity to use Mobile Approvals from an Android or other phone. This is basically a simplified mobile interface made to let those doing approvals complete those approvals from their mobile devices without doing anything with a regular computer or a web interface. This is a really nice idea for people who do a lot of approvals, and happen to be higher up in the org chart (thus the need to approve a lot of requests), and who may not be stuck in front of a computer all day.

While the application is neat, it's a bit of a pain to get it going, and this was particularly painful (really, terrible) in IDM 4.0 SP2. The reason is all about what was required to configure the UserApp to allow provisioning from mobile devices in the first place. Also, configuring the mobile app is a bit of a trick, but at least the user-facing part CAN be made very easy using a QR code or URL. The worst part, thankfully, is limited to IDM administrators who need to enable the functionality, and if you haven't had a good laugh all day then this should hopefully tickle your funny bone.

For reference, configuring the mobile application itself, once installed on your device via the Google Play store (or similar) can be seen here: https://www.netiq.com/documentation/idm45/ugpro/data/b12x5und.html Noteworthy is that the configuration CAN be done manually, and that's the way to probably do things at first. Helpfully, though, is the option to go to a custom URL that then signals the application to set the settings for you based on how the administrator set up that URL. You'll end up with something like this in the URL, either clicked-on directly or (preferably) accessed via the QR code:
FirstName LastName&vdxFirstNameAttribute=FirstName&vdxLastNameAttribute=LastName&

As you can see, there are a lot of options to configure either manually or via some kind of automation. The example above, as shown in the documentation, has username and password left empty; this means that the user will be prompted to enter those manually, and that same logic applies to any fields not set via automation, so it's possible to create a URL that is generic for everybody, or specific to individuals. Have a boss for whom you'd like to make things really helpful? You can do that. Have a pesky coworker who needs something else to do besides pester you? Send a simpler (fewer fields defined) URL and let them figure out the rest for a while.

To see more documentation on how to use the mobile app, so you know the kinds of benefits around it, check out the official IDM 4.5 documentation: https://www.netiq.com/documentation/idm45/ugpro/data/b1e4sug8.html#b1e5v0nk

The point of this article is to eventually describe the changes necessary for the User Application to work with mobile approvals, and specifically to show the differences between IDM 4.0 SP2 and IDM 4.5. Currently if you have setup both you may believe that the steps are identical, as the documentation states they are identical. For comparison:

IDM 4.5 instructions: https://www.netiq.com/documentation/idm45/agpro/data/b10qkkug.html
IDM 4.0 SP2 instructions: https://www.netiq.com/documentation/idm402/agpro/data/b10qkkug.html

Looking at those today, the pages are nearly identical, if not identical. The humorous part is in the steps themselves as they are documented. The steps follow:
1.  Stop the server
2. Create a backup of the existing IDMProv.war file.
3. Open the IDMProv.war file.
4. In IDMProv.war, open the file WEB-INF/lib/IDMfw.jar.
5. In IDMfw.jar, change the following configuration file properties to the specified values:
Configuration File - Property - Value
WorkflowService-conf/config.xml - WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly - false
WorkflowService-conf/config.xml - WorkflowService/soap/addComment - false
WorkflowService-conf/config.xml - WorkflowService/soap/getComments - false
VirtualDataService-conf/config.xml - VirtualDataService/soap - false
6. Save and close all files.
7. Restart the server.

Seven steps, mostly consisting of stopping/starting and backing up a file doesn't sound too bad, but the steps in that table are pretty crazy. Casually worded, open a war, then open a jar, then hack some XML files, then put the config files back in the JAR, and the JAR back in the WAR without any problems. If you have worked with the UserApp for very long you probably have dealt with concerns about supportability. The uaadmin user needs to be under a base data context; using the shipping Integrated Installer isn't supported in production even though it creates a reference installation; the use of anything labeled a "convenience installer" (using PostgreSQL and JBoss, or now PostgreSQL and Tomcat) is not supported at all, even though it's the only way to get things going without purchasing external software. Painful stuff that you'll likely catch when you're already in production and calling NetIQ to find out why your system is down, even though the issue is probably something not related to these components' supportability.

Now, in order to enable mobile approvals, we're being asked to extract a WAR, extract a JAR, hack XML files and then reassemble it without breaking things. A good zip-supporting utility can do this pretty simply, but every time humans get involved in tweaking this or that (instead of having a script do the same) there is a high potential for manual error. After all, our fingers invented typos, not scripts or other automated code-based solutions. What are the chances this will end well? It seems so simple, like so many things.

Now for the catch: the instructions above, which seem to be for 4.0 SP2 or 4.5, are actually ONLY for 4.0 SP2. IDM 4.5 has improved this significantly so that a properties file merely needs an update and the WAR is left alone entirely. Finally the age-old practice of putting configuration files outside of something like a JAR or WAR or EAR is being followed, and I suspect this is due to customer input (Novell has a history of listening to customers about this type of thing).

The IDM 4.5 file to be manipulated is under the tomcat/conf directory and is named ism-configuration.properties and is a nice simple text file. If you have used configupdate.sh lately you may have noticed it feels a bit faster, and the reason is that this too is now modifying ism-configuration.properties files here and there (another exists for the identity reporting service) and this means that the result of all of those values can be stored directly in the filesystem in a simple text file instead of being extracted from, and re-embedded into, a big WAR file which, by definition, is not supposed to hold configuration data. Hooray for progress as this is a very big thing for all of us.

For those of you still on IDM 4.0 SP2 and wanting mobile approvals to work you are not entirely out of luck. There are the steps in the documentation (and above) available to you now, but that is a bit painful. If you want a simpler solution, you can do the updates from the command line, but that's probably as problematic as doing it manually with a great zip editor. For you, I have created this simple script that will do the extraction, updates, and then freshening of the zip (JAR and WAR) files while creating a backup for you. It is up to you to stop and start the application service (JBoss) manually, mostly so you can tell people you worked hard by having to do more than one single command:
cd ~ || cd '/tmp';

#Get a passed-in provisioning directory from the user, if specified.
if -z ${1}; then

#Also set a variable for the WAR itself.

#Verify the file is there and can be read. If not, exit with a message stating as much.
if ! -r ${idmprovwar_path}; then
echo 'Unable to read the specified file; please be sure it exists and your user has read, if not read and write, rights.';
exit 1;

#Make a backup of the WAR automatically.
cp -a "${idmprovwar_path}" ./idmprov.war.orig-`date %s`;

#And the copy we'll extract; duplicated from the original so that we can use the freshen feature of the 'zip' command.
cp "${idmprovwar_path}" ./idmprov.war;

#Create somewhere to do the work
mkdir 'idmprov-mobile-enabling';
pushd 'idmprov-mobile-enabling';

#Extract, extract, extract
unzip "${idmprovwar_path}";
pushd 'WEB-INF/lib';
mkdir 'idmfw';
pushd 'idmfw';
unzip '../IDMfw.jar';
#cp WorkflowService-conf/config.xml WorkflowService-conf/config.xml-orig;

#The actual changes happen here in two quick commands.
sed -i -e 's#WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly:true#WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly:false#' -e 's#WorkflowService/soap/getComments:true#WorkflowService/soap/getComments:false#' -e 's#WorkflowService/soap/addComment:true#WorkflowService/soap/addComment:false#' 'WorkflowService-conf/config.xml';
sed -i -e 's#VirtualDataService/soap:true#VirtualDataService/soap:false#' 'VirtualDataService-conf/config.xml';

#Changes done, let's go ahead and freshen the zip with the changed files. Nice and quick...
zip -r -f '../IDMfw.jar' *;
zip -r -f '../idmprov.war' *;
rm -rf 'idmprov-mobile-enabling';

#Put the WAR back over the old one, replacing it, and warn if that fails.
cp './idmprov.war' "${idmprovwar_path}";
if 0 = $?; then
echo 'Copying the file back over the original failed. Please copy over the original before restarting the application service.';
echo 'Original file replaced with the updated version. Start the application service and the changes should be complete.';

To use this simply copy all of the contents into a file named whatever seems appropriate to you. One idea for a file name may be enable-mobile-approvals.sh

The resulting script file should probably be made executable for convenience:
chmod  x enable-mobile-approvals.sh

Now that this is done, run the file and specify the path to the extracted WAR's directory, wherever that is. This is likely something like /opt/novel/idm/jboss/server/IDMProv and must already exist. Be sure to match the case with the real file, as this is a computer and computers are case-sensitive by default.
./enable-mobile-approvals.sh /opt/novel/idm/jboss/server/IDMProv

If you get an error, try to correct it (be sure the file is specified correctly, that your user has rights, etc.). If you only have read rights the final step of copying back over the original file will not work, but you can do that manually after everything else. If you are using an odd application service like WebSphere which requires re-importing the WAR via something a bit more complex then you'll need to take that step manually, so go ahead and do that; start the application service and see if the changes are complete.

The script above backs up the original file using a timestamp (in seconds since the Unix epoch) so, no matter what, the original file should be backed-up before being tweaked (maybe not if you do not have disk space to complete this operation, but then you have a serious disk space problem).

For those of you on IDM 4.5, the manual steps will hopefully be released soon, but even then I think this should be something that you can script. For that reason, here is the one-liner to just do it without potential for typos, permissions errors, and all kinds of other human-introduced issues:
sed -i -e 's#WorkflowService/soap/addComment = true#WorkflowService/soap/addComment = false#' -e 's#WorkflowService/soap/getComments = true#WorkflowService/soap/getComments = false#' -e 's#WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly = true#WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly = false#' -e 's#VirtualDataService/soap = true#VirtualDataService/soap = false#' /opt/netiq/idm/apps/tomcat/conf/ism-configuration.properties

This isn't really a "script" per se, but it's something that you can easily adjust for your environment. The only change needed is to adjust the last argument which points directly to the ism-configuration.properties file which should (with a Tomcat-based install) reside in the tomcat/conf directory. Be sure you have read and write rights to this file by the user running the command or, at best, nothing will happen. Feel free to backup the file first and then compare differences. If your environment is like mine, those differences look like this as compared by the 'diff' command:
< WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly = true
> WorkflowService/SOAP-End-Points-Accessible-By-ProvisioningAdminOnly = false
< WorkflowService/soap/getComments = true
< WorkflowService/soap/addComment = true
> WorkflowService/soap/getComments = false
> WorkflowService/soap/addComment = false
< VirtualDataService/soap = true
> VirtualDataService/soap = false

With that one command completed, restart your application service (/etc/init.d/idmapps_tomcat_init start) and the system should come back up.

The benefits of this type of scripted installation are pretty clear, but there may be drawbacks depending on how you view the situation. Thankfully it looks like any of those potential "advantages" have been outweighed by the large amount of pain caused to administrators leading to the new, Java-endorsed model of configuration data outside of the archive (JAR/WAR/EAR) files. This means simpler patching, better support (easier to verify things are changed only where they should be), easier management of changes between "lifecycles" (dev/test/stage/prod), and generally a better experience for everybody. Just because we are focusing on the area of Identity Management does not mean that we should forget the lessons learned over the past several decades in the area of Patch Management. Thankfully, because we are working on a solid platform with a myriad of powerful tools available to us, we can still find ways of making the required changes safely and reliably to avoid our own failures to which we are inherently prone.

If you have come up with your own solution to this problem, particularly for the problematic UserApp/HP/D/Reporting patch process in IDM 4.0 SP2, feel free to share comments. A supported option may not be available to us, but the current 4.0 situation makes it very tempting to NOT patch the user-and-Internet-facing application at all for fear of breaking things or voiding support, which is a terrible way to view things. If something works for you to remedy this, comment below.

Happy Computing!


How To-Best Practice
Comment List
  • I remember working with you on the first release of the UserApp, roughly 2006-2007. You helped write a script that automatically enabled UA restart upon reboot. Within 5 years, that feature was rolled into UA version 4.0.2, I believe "out of the box".

    It is great that you are willing to offer these amazing articles and solutions. It is sad that these simple aggravation relievers are not built into the product from day 1.

    Thanks AB! You remain astounding!