Introduction

Novell Identity Manager has two main types of variables. There are local variables, which with the release of Novell Identity Manager 3.5 became a little less local, with the addition of scopes, either driver or policy. Then there are Global Configuration Variables, also known as GCVs. There are many places and reasons to use a Global Configuration Variable, instead of a literal string, and I would like to discuss some good examples of where you would do that.

The sort of things you would want to use a GCV for are location strings and the like. For example, the location of users in the eDirectory Identity Vault can be hard-coded to a string of "users.acme" if you want, or you could store that in a GCV, so that if you need to change it at a later date, it is nice and easy.

The same goes for the destination location in Active Directory. The Active Directory driver is probably the most commonly deployed Identity Manager driver. (I do not know this for a fact, but based on the number of comments in the forums, I feel reasonably confident in assuming the Active Directory driver is pretty common.) In the case of Active Directory it is a little trickier, since there are several different formats in which this information is needed.

For example: Suppose you need to specify the FQDN (Fully Qualified Distinguished Name) of the destination object when creating it. OK, that would be something like cn=Bsmith,ou=Active,Ou=User,DC=acme,Dc=com ... but then you would also need to specify the domain name to build the UPName (Universal Principal Name, I think) that Active Directory also stores. In this case it would be a string something like "active.users.acme.com". You would probably also need to specify the container in eDirectory where you want to look for users, and scope it so that users elsewhere (say an Inactive.users container) are ignored.

Before we begin, there are couple of things to discuss first. A Global Configuration Value can be defined in a number of places. The highest level, that inherits to all drivers underneath it, would be at the Driver Set level. In iManager, when you are in Identity Manager Overview mode, at the top of the driver layout screen you would see the name of the Driveset as a clickable link. GCV's are defined at that link. In Designer, you would right-click on the Driver Set icon and select Properties; one of the options in the list is Global Configuration Variables. You can also define it at the driver level, which would scope its usefulness to just that driver.

What is really nice and powerful is that if you define a variable acmeActiveUser for example, at the Driver Set level, with a value of say acme\Users\Active but then at say a Unix Linux Driver which needs to use a different container, you set a GCV of acmeActveUser to the value of acme\UnixUsers\Active then for all drivers in the driverset (except your Unix Linux driver) they will get the first value, but the Unix Linux driver will get the second value. This ability to override a Driver set GCV is quite useful.

A Global Configuration Value can be referenced at least two different ways. One is using a token Global Configuration Value in Arguement Builder. In Designer when you click the browse button next to the name field you get a popup showing the available Global Configuration Values, and more importantly, their current values. This is great in deciding which one to use.

The second way, which is quite powerful is as ~acmeActiveUser~ that is, tilde, the name of the GCV, then a final tilde (The squiggle key, on North American keyboards just below the Escape key, usually shift of the back tick key.) When used this way, the engine does a direct string replacement of the GCV value into the rule as the driver is starting. If you are missing a definition for the GCV, the driver with throw a fatal error and not start, so watch out for that one.

Test Case: Active Directory Driver

As an example of how we would do this, let's use the Active Directory driver as our test case.

1. Import a fresh Identity Manager 3.5 Active Directory driver configuration into a project, either in Designer offline, or in a test tree with iManager.

2. Answer all the prompts to get the driver imported. We will define our GCV's and walk through the policies that need to be touched.

3. Define the eDirectory container location:

<definition display-name="Container in eDirectory that holds active Users (Format is acme\users\active backslash notation)." name="acmeActiveeDirContainer" type="string">
  <description>Global variable to define references to the eDirectory container that Active users will be found in.</description>
    <value>acme\Users\Active</value>
</definition>

4. Define the FQDN of the Active Directory Users' locations:

<definition display-name="FQDN name where AD users are found (ou=Users,dc=acme,dc=com syntax):" name="acmeActiveDirFQDN" type="string">
  <description>GCV that defines where to locate and place users in Active Directory. Use LDAP syntax to specify the FQDN of the location.</description>
  <value>ou=Active,ou=User,dc=Acme,dc=com</value>
</definition>

5. Build a GCV for the UPN Name. Here is an example:

<definition display-name="UPN Name for Active Directory (in DNS format, acme.com for example):" name="acmeActiveDirUPNName" type="string">
  <description>GCV that defines the UPN Name formatting in the target AD system.</description>
  <value>acme.com</value>
</definition>

Note that in each case, I mention the syntax in the Display name to use. While it may be completely obvious to me what format to use right now, someone else coming in to fix something after I am gone or away may not think that what I intended is so obvious. Also, I highly recommend a description that explains what it is for - the more detail, the merrier. It never hurts to be verbose here: the penalty for a long description is incredibly minor at driver load time, and never again.

Default Configuration Policies

Now let's walk through the policies in the default configuration and start cleaning up. On a side note, the Resource Kit for Identity Manager already uses GCV's for all these things, and that is one of its design goals. However, the configurations for the Resource Kit make a number of assumptions that are not yet true of most installations, so we will probably have to wait until we better understand the Resource Kit model before using it in production.

Subscriber Channel

Lets start in the Subscriber channel, where there is no default Event Transformation. Personally, I would add one that scopes events to the target container. I would name the rule object something [acme] Sub-Event-Transform, and the rule would look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<policy>
  <rule>
    <description>[acme] Scope Users to the Active users container</description>
    <comment xml:space="preserve">We only want users from the active container, using a GCV acmeActiveeDirContainer to be involved in this driver.</comment>
    <comment name="author" xml:space="preserve">Geoffrey Carman</comment>
    <comment name="version" xml:space="preserve">1</comment>
    <comment name="lastchanged" xml:space="preserve">Mar 16, 2007</comment>
    <conditions>
      <and>
        <if-class-name mode="nocase" op="equal">User</if-class-name>
        <if-src-dn op="not-in-subtree">~acmeActiveeDirContainer~</if-src-dn>
      </and>
    </conditions>
    <actions>
      <do-veto/>
    </actions>
  </rule>
</policy>

Note: I tested to be sure it was a User object (else we would veto the driver startup event!) and that it was not in the subtree of ~acmeActiveeDirContainer~ then Veto. So I used the tilde format, since there is no token for GCV's available with this type of test.

Matching

The first rule needs to be changed from:

<if-src-dn op="in-subtree" xml:space="preserve">acme\users</if-src-dn>

to:

<if-src-dn op="in-subtree">~acmeActiveeDirContainer~</if-src-dn>

Then in the last three rules, the driver tries to match on a path stored as a string like this:

<token-text xml:space="preserve">cn=user,dc=test,dc=com</token-text>

We want to replace all three instances with something like this:

<token-global-variable name="acmeActiveDirFQDN"/>

Create Rule

The third rule in the Policy object is "Map user name to Windows logon name". Here we want to replace the reference to "acme.com" with the GCV we defined, from:

<token-text xml:space="preserve">test.com</token-text>

to:

<token-global-variable name="acmeActiveDirUPNName"/>

Placement

Here we have to replace:

<token-text xml:space="preserve">cn=user,dc=test,dc=com</token-text>

with:

<token-global-variable name="acmeActiveDirFQDN"/>

Command Transform

In the Command Transform rule set, we have to work in the UserNameMap policy object. The sixth rule is:
"map rename to Active Directory Logon Name"

We must replace this code:

<token-text xml:space="preserve">test.com</token-text>

with this:

<token-global-variable name="acmeActiveDirUPNName"/>

Conclusion

There is one additional twist that might be relevant to you. You might not have Groups and Users in the same locations in either eDirectory or Active Directory. If that is the case, you would define similar GCV's to store the container in eDirectory and the Fully Qualified Distinguished name for Active Directory. Then when you modify the rules to match and place groups from different locations, you would use the GCV's instead of literal strings.

You can find the modified Driver configuration attached to this article. I changed only the Subscriber channel discussed so far in this article.

That's it for the Subscriber channel policies and rules that need to be updated. Stay tuned for part two, the next installment, where we will discuss what needs to be done to the Publisher channel to complete the process.