Book Review: IDM Tokens: A definitive guide to NetIQ’s IDM tokens


Author: Geoffrey Carman

Disclaimer to the reader: I have known Geoffrey for many years, have recently started working with him more-closely, and consider him a friend.  As a result, it is possible that this is a biased review; still, I am trying to be objective in the information shared.  Take it or leave it as you see fit.

"IDM Tokens: A definitive guide to NetIQ's IDM tokens" (hereafter, "IDM Tokens") is a book that fills in gaps left by every manufacturer of software that ever existed.  Once upon a time I learned Perl using the O'Reilly "Learning Perl" book by Randal Schwartz.  It was a great starter, and over a weekend I was able to get going in Perl, but that book was not the "Programming Perl" book by Tom Christiansen, in that the latter is the reference on everything Perl, going through operators, functions, quirks, nuances, and providing simple examples specific to each of those pieces.  "Programming Perl" is an authoritative reference manual that every programmer can use even after years of programming, while "Learning Perl" is a great weekend read to get started from ground zero.  One of the best things about "IDM Tokens' is that it bridges this gap.  It is beneficial for those of us who have used IDM for over a decade, but does not miss details that are necessary for those starting out today.

As a side note, this review is meant to provide a few examples of the way the book is beneficial specifically, which are meant to refer to the existence of several other examples of the same type which are not explicitly called out.  Recreating the book's contents in a review seems, well, not like a review but more like plagiarism, so for each example please know there are several times that the same benefit (or drawback) was evidenced in the full text.

This is not, in its current edition, a book to help somebody get started from ground zero with installing IDM and creating their first driver config.   The product's own documentation and others' CoolSolutions will help with those beginning points.  IDM is often described as being a framework.  Frameworks have a tendency to be filled with powerful tools that can be used to handle simple problems simply, while making hard problems possible to solve.  Developers creating these frameworks often do so without creating the kind of guide or documentation that is necessary to fully use the system, relying instead on consultants to use their experience to take full advantage of everything after the documentation gets the product installed.  This IS that guide.

As the title suggests, this is a book primarily about the tokens, or functions and features, of Identity Manager (IDM).  If you have not had the pleasure of using this product to integrate any number of systems, it really makes that task something of a joy.  The product has evolved substantially since its early versions in the form of Novell DirXML, both through the addition of more drivers (connectors to specific types of applications or environments, like JDBC, LDAP, Delimited Text, SAP, PeopleSoft, Microsoft Active Directory (MAD), Domino, GroupWise, Linux/Unix, Scripting, etc.), as well as through improvements to the engine, which handles the flow of events between the Identity Vault, or Metadirectory, and those applications.  The functionality of the drivers (aka. shims) is mostly outside the scope of this book, but this book covers the engine in depth, which is where most of a person's work takes place.  The only configuration really required for the shim side is usually which connection options need to be setup for the final data delivery or retrieval.  While there may be room for a book there, it is probably adequately covered already through the existing documentation or other CoolSolutions.

A quick intro into IDM may be a helpful.  The business case that IDM addresses, in case it is not clear by the product name, involves managing identities of people.  For example, most people have identifying numbers or strings which represent them to companies (employee ID), governments (unique ID for snooping), contacts (phone number) or family (name, order of birth, etc.).  Most of us have many of these, but all of these are just ways to identify us.   None of them, I would bet, truly defines our identity, but all of them belong to, and are part of, our identity.  I am often known by my name, but I am surely more than the sum of the syllables constructed to yell at me.  The same goes for all of the other data.  The point of the "Identity Management" field is, at a basic level, to manage the plethora of identities which are spread across disparate systems throughout an organization.

I was talking to a friend last week and he said that, until recently, he had fourteen (14) usernames and passwords, most different, and some of those passwords required different types of complexity, so one password could not be used for all systems.  When I asked how he personally managed all of that, he pointed to a notebook and said it was all in there, so he never forgot it.  This leads to another major area of Identity Management, specifically the need to manage credentials between systems.  Expecting IT folks to remember that many credentials is crazy, but expecting non-IT folks and other end users or customers to do the same is just irresponsible and negligent.  Thankfully this company is currently implementing IDM to help manage this so that users can have a single set of credentials which, then, they will not need to write down and tape to the bottom of their keyboard.

In order to manage the connections between systems there needs to be an event-driven flow of events from one environment to another.  Being event-driven has its ups and downs, but without it the overhead to find what has changed since the last polling interval (in a non-event-driven setup) is grossly inefficient and does not scale well to millions of objects.  Some typical business rules may include, "Only synchronize users who need e-mail access as users into the e-mail system." meaning that contractors, temp workers, or part-time students do not get an e-mail account.  Other examples may include, "Only add certain entitlements to this user after their manager, or a VP, or somebody else in charge of the application specifically has signed off stating that it is authorized."  This nicely addresses political issues that often arise when integrating systems in large companies.  Managers and administrators of an application may be hesitant to give up control of that application, for legitimate reasons (such as they pay the licensing costs for the application and they are afraid you are about dump ten thousand users in unnecessarily) and IDM provides the framework around which that can be simply built.  Other features can be implemented to automatically link certain privileges with group or role membership, and can be setup to automatically remove those (or any other) attributes after a period of time if not used.  The Identity Management desire often starts with, "We do not want to manually do all of this work every day and introduce typos with every copy." and ends with providing a lot of power, flexibility, and security to the organization, meeting HR, CXO, and Compliance desires are met all at once.

Going back to the tokens, they are the pieces of the IDM engine that allow the administrator to define those rules.  NetIQ provides a "Document Type Definition" (DTD) which includes some details about the tokens, but it is only a basic starting point.  Because this is equivalent to defining how a "foreach" loop works, or how tokens within a regular expression are parsed, the details are usually left up to the customer to figure out via the abundant use of guessing, checking, pondering, and often, profaning.

The book is organized into several sections that work well with how development of the driver configs usually happens, describing nouns, verbs, conditions, actions, and then the Filter and Schema Mapping pieces.  Nouns are the who/what part of identity management, and the tokens access passwords, objects, attributes, and several other pieces. Verbs are the actions on the nouns and can encode, convert, search, replace, and do other useful things.  As with any programming language there are conditionals, and so the bulk of the tokens are in the section of conditions and actions, and there are a lot of them.  These include if statements like, "if class name", "if entitlement", and "If XPath Expression" to have a range from simple and intuitive to complex and very powerful.  The last token may hint at the use of XML within IDM to represent objects, states, and other data required for a robust identity management system, and with the ability to use XPath, XSLT, and ECMAscript in addition to the main tokens, the ability to manipulate events to meet business goals and requirements is present for anybody to use.

Actions probably deserve their own section in the review.  When developing the driver config behind IDM there is a bit of overhead stuff to get everything ready, and then it seems like the last few steps are taken and everything is done.  Those last few steps usually come in the form of the actions, and these are where the majority of the functionality really makes the environment soar.  Modifying entitlements for access or membership, manipulating associations between identities in the vault and accounts in other systems, automatically cleaning up attribute values to match the corporate standard, generating passwords on the fly for newly-created accounts, disabling or deleting users automatically at the end of their use... all of these are "actions" and while most of them seem, and are, intuitive, this area is where the book's value really shows.

Take, for example, something simple like a "Local Variable".  Like in any programming language it is often useful to store something temporarily for use in another rule or policy during the current event, or even in a subsequent event.  Simple enough, right?  Sure, it is, unless you want to use the variable in a context other than what the Policy Builder interface provides in drop-downs ("Do I use dollar signs, or tildes, and one or two, to refer to a local variable in XPath statements?").  Geoffrey covers some common use cases and pitfalls that make this a great reference.  Think of it as starting where the DTD ends (which is just after providing a parameter list for the tokens) and then going through use cases that have been implemented successfully in real life for real customers.  He doesn't limit the examples to "If you want to copy a value from here to there..." but instead goes all out showing how tokens interact, for example using a foreach to loop through a queried nodeset and then working with the values inside using built-in and custom local variables.  He then does this for not only simple tokens like "Local Variable", but does the same for more-complex tokens, and less-used tokens, and everything else within the engine.

Another piece of the book that I did not expect, but definitely appreciate, is the appendix for ECMAscript.  The IDM engine can handle the proprietary IDM policy, but also can use ECMAscript (often known as JavaScript) in place of a policy in order to do processing that may be outside what the base tokens provide or make simple.  Understanding all of the built-in methods (or even finding them) can be a bit of a chore, but the book includes a list and has examples along with how they work and where common caveats may be.  An example I used recently was with the stripChars function.  Like its name suggests, you can use it to strip characters from a string.  The function, though, ignores some ASCII characters and this was biting me with a customer using some of those characters as delimiters for CSVs.  In the end another way was used to modify the data but having the book to let me know I was on the right track saved me a lot of time in reproducing the issue, verifying the characters manually, and possibly calling the vendor to get confirmation from them.

ECMAscript is one of the semi-hidden gems of IDM, in my opinion, for a few reasons.  First, most technical/IT folks know, or can trivially figure out, JavaScript/ECMAscript, so the work that is required to make IDM do something can be assigned to employees who may not necessarily be IDM experts.  Second, ECMAscript is a full programming language, and it can be used to call Java functions available to the IDM engine, which means you can find libraries that meet your needs and call them in your own scripts (you can do this without ECMAscript too, but it is not very intuitive).  Finally, it kind of feels like cheating when breaking out of policy to use ECMAscript for a task, particularly when that task gives you access to the same data but with others ways of manipulating it.  An example is the ability to query a directory (the local Identity Vault or a remote system) using LDAP, meaning having the ability to use the advanced filtering techniques available to LDAP which the IDM engine may not be able to do without a bit more work.  Shortcuts are great, and the appendix's reference of the functions available via this shortcut are very useful.

Another asset is partially embodied in Appendix B.  This includes, at the time of writing, a full list of the author's online articles.  In some form, these were a large part of the source for the book, but the book's organization adds a lot of value to what the articles already have out there.  Even more importantly, while this book is specifically about tokens, the links in the book to the articles are contextually relevant and provide more background on topics outside of tokens. A quick example may be an article on generating audit events, and then linking to an article where that was done in the past for a specific purpose, or in a section on a particular feature, linking to another article that covered a driver which specifically used that feature in a clever way.  Not only is this book a reference to get you from just above ground zero to a good understanding of a function, but it also links to other examples that are in use by other customers every day.

This book is not without its flaws, but they are basically cosmetic and the result of writing a couple hundred pages on a complex topic.  Being a person who relishes in the details I know he has already cleaned many of those and the latest is probably fixed.  Some readers may find the prose throughout a bit long-winded (like some book reviews) but, at least in the book's case, it does a good job of really calling out all of the details present around the tokens.  If you are a fan of stating something with as much brevity as possible, stick to the DTD, and product documentation, but realize that they do not cover the full set of tokens as well as this book.... or even come close (because that is not their purpose).

In the end this is a book well worth its cost.  It is available in electronic format (a searchable PDF), hard copy, or via a nice site-license option so that a company can purchase it for multiple employees at one cost.  The link to get the book in whatever form is available at the top of this review, and is recommended for any implementer, whether starting out or already neck deep in identity management, to make the most of the time given for development.


How To-Best Practice
Comment List
  • Hi  Geoffrey ,


    interesting post,  and you are rally hard to contact.

    i need just some help from you on a very very particular things.   im not sure if the problem is on SSPR or eDirectory but im stuck with the utilization of IDM TOTP Token,  

    we are trying to put the seed from another app based on base32 google auth rfc's  and the sspr with the same configuration ( base32 ) dont recognize the secret.  because this secret have 26 chars,  and only read 16 chars secrets.   the base32 supouse works with 16, 26, 32 chars.  why this product of netiq just doesnt works like any other base32 otp ?

    this kind of tokens can be configured on IDM ?