So stumbling along toward a potential rights issue I had to try this to verify it worked. How do you REALLY know what rights you IDM driver has? I mean really? Okay in theory you should be able to do something like open iManager/ConsoleOne and view trustees of an object and go for Effective Rights. In this way even if you don't have explicit rights to an object the inheritance should be calculated properly. That works well, but what if you want to know if the driver will actually be able to DO something despite rights (for example, creating a home directory on a remote server that could have more involved than simple rights like NCP communication)? Well it turns out that you can actually login as a driver. Yes, that's right, a login via your favorite client as the driver itself. Give it a shot in iManager or ConsoleOne and, once you're in there, try to do something that your driver should be able to do.
As an example I have an Organizational Role assigned to manage ONLY things in the dc=testwo-1workorder.dc=idm.dc=service.dc=system container because its entire purpose life in life is to give rights to my WorkOrder driver and that is the container for WorkOrders. The Security Equivalence is setup between the driver and the Org Role properly (or so I believe, but that's why we're testing after all) and now I'll login as that driver.
Once in my favorite administration tool I try to create an object under o=system and get an error quickly. I do the same under dc=org and get another error. Now I try to create something under my dc=testwo-1workorder.dc=idm.dc=service.dc=system container and happily can continue.
This could also be useful when management asks if it was IDM that blew up a container of servers. In a tree designed with servers in one part and users in another there's no reason for the driver to have rights to servers. If they aren't assigned and you can prove it that will be one less thing for you to worry about on the IDM front.
Submitted by: aburgemeister on Tue. 12.18.2007
Recently I was in a training talking about the semi-new Novell Identity Manager (IDM) Resource Kit. One of the concepts introduced (to me at least) was that of drivers geared toward business logic and those for application-synchronization logic. It's one of those things that is so simple and obvious I'm surprised it hasn't been pushed sooner but I was stuck in a rut all this time trying to combine both.
So what is this all about? Historically IDM drivers have synchronized data from somewhere (eDirectory, Identity Vault (IDV), Metadirectory, whatever you want to call it) to somewhere else. That somewhere else could be another eDirectory system, microsoft active directory (MAD), SunOne, iPlanet, a database like Oracle or MySQL, MS ADAM, SIF-compatible systems, Unix/Linux/Mainframe systems, PeopleSoft, SAP, flat files.... you name it. Current systems that are not synchronized with their own driver can be customized to the nth degree using the Scripting driver. The options never cease. Typically the logic of whether or not a user went to a specific system was done in one of these same drivers.
After people realized all of this great stuff extra little things started being added. For example to synchronize objects to eDirectory you only need to have cn and sn but other systems require other attributes. Linux/Unix want uidNumber and gidNumber. MAD wants to have a Full Name. E-mail systems may want to have a unique e-mail address come ahead of time. Other systems want to have their own unique identifiers or other mandatory attributes set. It has always made decent sense to add these bits of logic into existing drivers. Adding a rule to create Full Name from a Given Name and Surname was done around IDM 3.0. Adding other IDV attributes from other drivers has come as well. Each system can be the provider of its own data (unique IDs or application-specific values) usually sending it back to the IDV for global reference. Everything works nicely. All of your attributes are bieng filled in by various drivers that are all up and running. There is nothing to go wrong, right?
One day you take out your MAD system so Full Names are no longer populated by default. Another day your e-mail system changes and the format of e-mail addresses changes. You start synchronizing data somewhere new and your expected default password of the user's Surname is now 'DirXML1'. You remove your third eDirectory system which was deleting users that were expired for a year or so and now users stick around forever unless the admin kicks them manually. Your MAD system (previously removed) was also determining if a user was in an HR group and setting giving access to that system at the same time via an entitlement. Not huge changes, but still things that weren't expected. Losing one of these attributes can cause anything depending on them to stop working as expected as well. All of these little bits of "business logic" were being carried out in an application driver. So here is where I had my lightbulb moment during the explanation. The task of setting all these default values, unique identifiers, and carrying out regular tasks is best left to driver devoted to the task. A driver devoted to a specific task will do the job better than one doing it as a side thought. Perhaps just as important as how well the task is accomplished is that a driver devoted to certain tasks is remembered for doing those tasks specifically. When it comes time to make changes it's natural to think that driver A synchronizes to application A, driver B to application B. It's not natural to think that driver A also happens to influence application C by way of setting Q.
It so happens the drivers to do all of these little business tasks already exist. The Loopback and Null drivers have been around for years. The WorkOrder driver is new to IDM 3.5 and carries out all kinds of time-delayed tasks and can be customized as much as possible. There is a driver devoted to setting up uidNumber, gidNumber and other Posix attributes for the *nix systems out there. The Entitlement Service Driver is made for doing role based entitlements so you don't need to have another driver worrying about that either. The UserApp has always been devoted to these types of tasks so this improved way of thinking has already been underway even though I didn't see it until it was handed to me.
In the end we have two types of drivers. Business drivers that do everything the application-specific drivers don't do, and application-specific drivers that are concerned entirely with synchronizing data perfectly to their respective applications. When a user is created a loopback driver creates the Full Name and, until that happens the MAD driver just drops the event. The Full Name being populated is enough of an event to start synchronization back to MAD again. When a uidNumber is missing the Bidirectional drivers drop the event until the NX Settings driver does its job. When an object is disabled all of the application drivers synchronize the fact it is disabled but it is the WorkOrder driver's job to actually create a WorkOrder to delete the object in 360 days, or move it to an inactive container, or reset the password to something random. When a user is created the Null or Loopback driver can be used to generate a random password and e-mail it to the manager. The WorkOrder driver can also leave the account disabled (or make it disabled) until the day the employee actually starts. The PeopleSoft driver synchronizes data from the HR system to start all this craziness so it's up to the HR guys to just get that entered properly. In the end the IT department sets thing up properly doing a lot of research and testing and documentation like they would do anyway and then they can continue doing their job instead of worrying about attribute population, application provisioning, and all kinds of other day-to-day stuff that could consume their time.
So it's not a huge change but it's something I'm trying to do more and more with my drivers. The IDM Resource Kit (available from download.novell.com) gets into this a bit. Designer has the Resource Kit drivers in there as well and has all of the aforementioend drivers built into it. Many of these Business/Service drivers (like WorkOrder) are free to use if you already have IDM so this is just going to make life easier in the long run. Little work now, a lot less work later.
Submitted by: aburgemeister on Wed. 11.28.2007
Does determining which TAO file goes with which driver object on which server cause you grief? Let's work on that a little bit.
Here's a quickie for all of you who are on a real OS. For those stuck on windows you'll need to find a decent command-line calculator to have the same fun. For everybody everywhere you can always use any calculator app (gcalctool, kcalc, calc (windows), bc (this example), etc.).
So what we're going to learn today is how to interpret those pesky TAO files. If you don't know already each driver has a TAO file which stores events from the engine that are pending for that driver. For example if a user's given name changes it needs to be sent to the eDirectory and microsoft active directory (MAD) systems. If the driver is busy doing something else that event is written to the TAO file to prevent it from getting lost (technically I think it's written there regardless but I'm making a point here). As the engine gets finished the new event is read from the TAO file, processed, and eventually removed (various algorithms exist across IDM versions for when the TAO file is rewritten).
So the problem many administrators find quickly is determining which TAO file goes with which driver. They are all in the eDirectory DIB directory and they all have decimal-number names which don't go with the object name at all. Several TIDs explain that the TAO file name is actually the eDirectory object's Entry ID (EID) converted from hexadecimal to decimal (base 16 to base 10). This conversion is trivial in a calculator but having one open and then comparing them with the EIDs in iMonitor just makes for a lot of steps. To do the conversion in one less window a simple script can be whipped up. SLED/SLES come with `bc` which is 'An arbitrary precision calculator language' according to its man page.
Create a new file ('d2h' will be my file's name) in a part of the filesystem that is in your user's path. This could be the 'bin' directory in your user's home directory or it could be something as universal as /usr/bin or /usr/local/bin (you'll need 'root' rights to do this in a univeral path). Make the file executable (`chmod +x /path/to/theFileYouCreated`) and then edit it placing the following line inside the file:
echo "obase=16;$1" | bc
Save the file and now test it:
Tada... you gave the command-line file a parameter (the TAO file name was 45050.TAO) and it gave you the EID to find in iMonitor. From here all kinds of fun things can happen. First let's get the reverse down just in case it's useful (it's a little more-tricky):
New file again, called h2d (hex to decimal) with the following contents:
echo "obase=10; ibase=16; $1" | bc
So now we do the opposite of the command above:
Wonderful, so we have the basic conversion licked. Playing with 'bc' on your own time can be a very rewarding experience so I recommend it. It is important at this point to note that EIDs are server-specific (unlike GUIDs which are universally-unique) so if you have drivers on multiple servers (one active, one dormant) they will probably have a different EID on every server. Also two drivers on different servers (whether the same driver object or not) could have the same EID between those two servers. Just make sure you realize that the EID is only unique on that one server. When using iMonitor to view the EID of the driver object be sure you have pointed iMonitor to the server on which you are viewing the TAO file (in case multiple servers have the driver as mentioned above) or you'll pull your hair out trying to figure out why the values don't match up.
For somebody who is a scripting wizard it wouldn't be too difficult to write something like 'lstao' that, when it found a file like 45050.TAO, automatically converted it to the hex number while leaving the other data behind. I may work on this but it's late so not tonight.
Submitted by: aburgemeister on Mon. 10.01.2007
Lately it seems there have been a bunch of new people getting started with IDM, especially with the microsoft active directory (MAD) driver, who need to have a quick explanation of what all the settings are for and how they will affect operation of a MAD driver. While I've never been accused of being quick or brief in my explanations I'm going to try to present something outside the documentation that is possibly useful to people who understand what they read which is written like I write. Those people may be few and far between, and are possibly in state hospitals, but in case some of you are evading the white-coat-clad officials like myself here we go.
First as a couple brief reminders about the nature of Information Technology (IT... yes I'm trying to go from the ground up) and this product you had better be in a test environment. Blah blah blah, Novell doesn't take responsibility for your irresponsibility, blah blah blah. Okay that's through and I assume you know enough to not play with unknowns in the bread and butter environment of your company. Also Novell Identity Manager (IDM) is a bit of a fun product to support because so much of support is not working with Novell products. In this case we need to have some knowledge of the MAD environment which I'm assuming you have. If you are a super-rockstar MAD administrator that's great for you and will help you understand what is going on and, in fact, you'll probably know more than me by the time you have this set up. Some functionality like Signing and Sealing have not been adequately explained to me so I'm going to avoid them. Others like RPC are a nightmare and we'll take for granted it is all enabled and working in your system. Other nuances like Remote Registry should be enabled for maximum comfort during part of this deployment but are not required for things to work as long as you are decent in MAD.
Finally this post is going to focus on the “best” way to implement this driver to maximize performance, security, and ease of deployment. In a world where things are setup properly and simply this driver can be deployed in ten to fifteen minutes including getting the SSL stuff working between the driver and the Remote Loader (RL). Take out that component and it should take five minutes if you know what you're doing. We're going to take a lot longer but mostly because of my own verbosity as I mentioned earlier. So let's dive in.
Because it would waste a lot of space and be redundant I'm not going to go over the quirks of getting iManager setup for this. I think I'll write another post before too long (or maybe before I post this one... who knows) on how to setup a Mobile/Workstation instance of iManager specifically for IDM's purposes as it's very easy and people ask about it a lot. Setting that all up is something you should become familiar with especially as you are changing versions from 2.x to 3.0.x to 3.5.x since some functionality of the plugins does not work across versions. Having multiple iManager instances makes this a non-issue and, since they're all local to your workstation, nobody cares about having to upgrade the servers while doing IDM stuff which is often a critical component of your infrastructure. After all why have the worry of changing one system's administration piece during the upgrade of that system all at the same time? I don't have the health for stress like that and assume you're in the same boat.
As a note about my environment I'll be using SLES 10 with eDirectory 8.8.x and iManager 2.6 SP3. IDM 3.5 is on the server and the plugins are already installed in my Mobile/Workstation version of iManager. This is the easiest setup I know of and would recommend you have your own. I say it is the easiest and, though I am a Linux user full time, I really think this presents the fewest headaches of the platforms available (possibly followed by NetWare). Because of this setup I can download all my media directly to my workstation or my server and get them installed without having to leave the comfort of my bed which is important to me. Any ISOs can be mounted without burning media (the servers are ten miles away and it's midnight, so I'm not going to go to them for sure) and any other files can be transferred via scp which is 'secure copy' and works over the SSH protocol (which is installed and running on almost every OS I've ever used, except windows, by default). For those of you working with virtual machines of some sort you are probably able to enjoy the same volume-mounting benefits and I would encourage you to do so for reasons beginning with “verifying burned CD integrity is harder and slower than verifying the ISOs used to burn them” and continuing through “burning CDs for one installation is a waste of plastic and money and isn't helping the environment”. Do what you like, but I'm lazy by nature and having this be as easy as possible is good for me. No matter which platform you use the install should look almost identical and the steps the same as what I'll be using except for which files are run to start the installations. See the documentation for differences as they are likely to be more up-to-date and possibly more-complete.
So first the basics of getting the media start with http://download.novell.com/ which is where all Novell stuff is housed. Go there, choose Identity Manager from the drop-down, and click 'Search'. This will take you to everything Novell-ish that is related to Identity Manager including the installation media and IDM plugins.
If you don't have the IDM plugins in iManager 2.6 you can also download them directly into iManager from within iManager. There is documentation on using this new feature of 2.6 and it's beyond the scope of all this so find other blogs or read the docs. It's also a well-covered process in the support forums which are available online for free to all. For this example I'll download the DVD ISO because I may use it all at some point in time. Most people doing this install will probably be able to stick with the 'Identity_Manager_3_5_Linux_NW_Win.iso' file which has the engine and RL installations for Linux, NetWare and windows. No matter what you use download it and get it into your server either mounted or burned to a CD/DVD. If you are licensed for Open Enterprise Server (OES) whether it be NetWare or Linux, or if you have Zen 7+ (as of the time of this writing) you are entitled to the 'Bundle Edition' of IDM which is a good thing for you. The MAD, NT, and eDirectory drivers all come for free with this package (instance-based licensing) so you can have it and use it for as many users as you want for free. Credentials still come from Novell but they are provided since you are licensed via OES or Zen. Also if you have an older version of the Bundle Edition you get newer ones by default (probably as long as you have OES still). Once the media are in there we can all proceed fairly simply.
To review some quick terminology we have an 'engine' which is where the IDM engine is running and is where eDirectory is, and we have a Remote Loader which is often used and is recommended when possible for a couple reasons. First this installation will put the RL on a Domain Controller (DC) in the MAD environment. With this planned having eDirectory, IDM, and a DC all together means an over-worked box. The RL lets us leave eDirectory and IDM somewhere else on a happier box (my Linux server in this case) and keeps the utilization of the DC to a minimum which is good for it. The Remote Loader is simply a bare-bones extension of the engine and loads the driver shim (regularly referred-to as the 'driver') which is the interface to the application (in this case, MAD). The engine will establish a Secure Socket Layer (SSL) connection between itself and the RL because we are transferring information that is important and probably sensitive. The RL will receive data via this connection and, via the loaded driver, send it on to the application. The RL will also use the driver to receive new data from the application when applicable for bidirectional communication (that's what I'll be setting up here as well since it is a common implementation and is just a checkbox to change). Besides reducing the workload of the server running the engine and eDirectory the RL also saves a lot of pain and suffering should the driver shim have a problem or bug that is not handled. Instead of dying and taking eDirectory with it (since the engine is a module of eDirectory and, without the RL, it loads the shim as part of itself) the RL can live or die all day long and eDirectory won't care. Failures of this type on the part of shipping drivers isn't a big problem but it's entirely possibly to develop your own unsupported drivers and doing so as part of the engine would not be advised.
Another bit of terminology to be aware of is the 'driver configuration' which is often called the 'driver' as well but should not be since it is just the configuration for the connection to the application. Most of the settings in this configuration apply to the engine though some affect the operation of the driver shim. This configuration is stored in eDirectory and can be exported via iManager or Designer at any point in time. It is purely XML so it's easy to save forever, modify on your own, or send to others for review/sharing. When you have a working happy driver configuration you should ALWAYS have an export of it saved away somewhere safe just in case as, without it, you get to recreate this config (depending on customization you have inserted this could be painless or heartbreaking). The initial driver configuration comes from a 'preconfig' shipped with IDM which is importable via iManager. It also comes with IDM's Designer product. It is with the IDM 3.5 MAD driver preconfig that we will build this example. Preconfigs come with default rules that make sense getting you going and whose details we will skim over but, especially for the AD driver, they usually get you going out of the box. Still, every environment is different which is why you are in a test environment right now.
So going to my iManager installation and looking in my directory I have created the following container for IDM in eDirectory:
Underneath this container I will create a DriverSet which is a special container built for holding a bunch of drivers and other IDM objects. For those who have been using eDirectory since its inception this may not look like a “normal” environment and that's fine. I build my trees different from many others because it simplifies things significantly. I'm sure I'll write about it at length someday. In the meantime if some of you have a native LDAP background it probably looks familiar. A 'DC' is an administrative domain and is just a container that can go anywhere and be anything. It's basically just for dividing up the tree and does a particularly good job for IDM and me.
Another environment note for me is that my administrative user and server are, respectively, at the following locations:
The double-name for the server is because each server has its own DC to contain all of its objects. This is really nice when it comes time to give each server a copy of itself without having 100 replicas of a given partition floating around. Anyway just be aware of it.
On my Linux box I have downloaded all of my various installation files to my user's home directory in a 'dnlds' directory which works out to be:
For example the IDM 3.5 installation ISO is in /home/aburgemeister/dnlds/idm35 and eDirectory is in /home/aburgemeister/dnlds/edir88sp1 . While the ISO is physically in that location I also go ahead and mount it there because it's easy and keeps me from losing files or having to remember a million mountpoints. The following command does the job:
mount -o loop /home/aburgemeister/dnlds/idm35/Identity_Manager_3_5_DVD.iso /home/aburgemeister/dnlds/idm35
So this means my 'DVD' is completely available to me in the same location it was downloaded to and the original ISO is sort of “hidden” behind the new mountpoint. This is, if nothing else, a great way to play tricks on your friends with diskspace utilization.
To start the installation run the './install.bin' file at the root of the DVD. Those of you on windows run the 'nt/install.exe' file if it hasn't started for you (and if it did you really should disable autorun). Those on NetWare go into `nwconfig` and choose to install a new product and point to the DVD's volume or extracted contents' directory followed by '\nw\nisetup.ips'. The installation can also be started from the GUI by choosing the 'product.ni' file in the same\nw' directory. Either way for those on windows and NetWare you will be given a GUI installation. Those on Linux using the GUI will also have a GUI installation but the *nix platforms that are starting this from a command-line will receive a command-line installer. Since I'm ten miles away I definitely prefer the command-line since it's much faster than any GUI regardless of potential compression or optimization possible on the source and destination sides.
As the installer begins keep in mind this is still the engine component and should be done on the machine running the eDirectory instance holding all the users/groups/etc. you want synchronized. We'll do the Remote Loader installation later on a windows server. The first prompt during the installation is for language and I'm guessing you can figure that part out. The next few screens (at the console) are for the End User License Agreement (EULA) which I'll click through since I've already agreed to it a few times before. In all actuality this time I forgot to become 'root' but that's a good thing for me to note in case you have this issue as well. If you are presented with a screen saying you are not 'root' this is an indication that you should become 'root' on the system. NetWare people won't have this issue (if you're at the console you're good enough) and windows people should be Administrator-equivalent to do this install. Just for completeness here's my error:
User cannot Install
User does not have sufficient rights to install? Login as root to install Identity Manager
So let me catch up now after going in as the 'root' user and getting back to my directory.
For those of you using eDirectory 8.8.x as well be sure you have run `ndspath` to get the environment set properly for eDirectory and IDM on the server. TID# 10100008 covers this in a related issue and will get you close. If nothing else the following should work:
. /opt/novell/eDirectory/bin/ndspath #notice the space between the dot and the path to the command
This implies you are using the root-based eDirectory installation. Currently that is required so if you are using a non-root install of eDirectory (you are probably not) you'll need to change that. In the future this could be different but I have no idea when that may come to fruition.
So now we're past the first-child-requiring EULA (yes, it's a joke... I'm not a serious person while awake or breathing) and we're being prompted to choose what to install. I'll do the bare minimum so you know what that is for you in this case. It's fine to install extra since as it is just libraries and driver shims. Because only the one you configure will be used do not panic if you have extra... just be sure to have the minimum. To do this choose option '4' to Customize the installation. At this point I'll leave on 'Metadirectory Engine' (option 1) only by “deselecting” all other options with the following line (GUI users just uncheck the boxes, or leave them to have them all installed):
There are some options in there I'd like to cover here briefly as they are probably important to some of you. If you have a server-based installation of iManager on this same server the options 19 and 20 are interesting. The first one mentions 'Plug-Ins' which are the binary files that let iManager know how to work with IDM in your environment. The second one labeled 'Identity Manager Driver Configuration' are those preconfigs I mentioned earlier. Without them setting up a new MAD will be interesting so, for those of you on 3.5, I'll attach one to this article so you don't need to do the full install. If you have iManager on this server with eDirectory or do this same “install” on another server you can choose that/those component(s) (even without the engine installation) to have those available to you directly from the media. This makes the setup go a bit easier and makes it feel more-integrated but doesn't work well with Mobile iManager. I guess this may be a good point to put in a plug for Designer (2.0+ for IDM 3.5) which comes with these configurations built in by default.
So we've deselected everything except the engine (optionally adding plugins and preconfigs) and will now be prompted for administrative credentials for our eDirectory environment. If the installer detects eDirectory is not running on this server that will need to be fixed. After entering the user's DN in LDAP format (as I showed it above) along with the password a final summary is shown. Now the installation will take place. At the end of the installation a screen will pop up saying all went well (we hope anyway) and that, if you installed the iManager Plug-Ins (option 19) you need to restart your application server (Tomcat). Do so if you did that. A similar restart of Mobile iManager was required after adding the plugins but this installer would not have done anything along those lines for the Mobile version.
At this point we have installed the engine as a module of eDirectory, we should have plugins in some version of iManager that can reach the tree via TCP/IP, and we have a preconfig (attached to this post or in Designer if nowhere else). The next step is to create a DriverSet. As a note for those on the console of a server we're done with that for now and you should be back on your workstation.
Logging into iManager I see the following screen which should be similar to yours. The important things to note are that you have the 'Identity Manager', 'Identity Manager Utilities', and 'Passwords' roles present.
Click on 'Identity Manager', then 'Identity Manager Overview', and then click on the 'Search' button to search the entire tree for a DriverSet. I'm assuming you don't have one so we'll choose the option to create one. Name it whatever you want, but I'm going to have mine named 'DefaultDrvrSet35' since it actually exists in my tree already and does other things for me. This makes the full context of this DriverSet:
You will need to choose a server to associate this DriverSet to and that server should be the one you installed the IDM software on in the previous step. After you have created the DriverSet (I chose not to partition it and ignored the prompt though you can go either way as long as you treat a DriverSet like any other partition and always have at least three replicas of it or its parent containers) you will be prompted with a screen that may have a drop-down box with driver configuration options. For those of you using Mobile that box will be greyed out. For those using an installed version of iManager who installed the Driver Configurations you'll have a long box with a lot of options. Choose Active Directory (the top one as I recall) and continue. For those who downloaded the preconfig from this post be sure it's extracted (if it was compressed) and is just plain XML if you view it. Choose to 'Import a configuration from the client (.XML file)' and browse to your XML preconfig. Mine is at the following location:
Continue to the next screen where now we get into the good stuff. First things first with any directory object creation, give it a name. I'm going to be using 'testmad0' since it's a test driver just for you that I'll be getting rid of in a few hours but you should call it something that makes sense to you. This name needs to be unique to this DriverSet but otherwise it can be almost anything. I would advice against making it overly long or complex but rather something to remind you of its purpose. Many drivers are named for their Subscriber channel (the channel that sends data rather than receives it) so it may be named 'vaultToMAD' or 'eDirToMAD' or something along those lines.
The next option to configure is very important and is called 'Authentication Method'. You will want to choose Negotiate as it is by far the best way to go. This method uses microsoft authentication (Kerberos or NTLM chosen by default) to authenticate to MAD. This means it should be a simple setup, a trusted setup, and a setup with the fewest points of failure (not using excessive boxes or connections to get into MAD). The documentation covers this setting in more detail but, for the most part, you should always use Negotiate. There are exceptions but using Simple is a lot harder to setup. It is a connection made for Simple functions and lacks some abilities but it can be used in more cases. For 99.99% of the environments out there it is not appropriate though since it lacks certain key functionality.
The next field is also vastly important and often confused. It is called the 'Authentication ID' and is the username of an entity in MAD that has rights to do all kinds of things including changing users' passwords, creating and deleting users, modifying groups, etc. Anything you want the driver to do this user needs to be able to do in this domain. The format of this should also be noted. The preconfig and iManager screens show you how it should be formatted. We chose 'Negotiate' above so you need to put either 'Administrator' or 'domainName/Administrator' for your Authentication ID. Do NOT try to put in an e-mail address ever as it is just wrong. Also do not in this case try to use an LDAP DN as we are not doing anything related to a 'Simple' bind. The screen shows examples so be sure to read and follow them.
The next screen is simply the password for the user listed above. Enter it twice and be sure it's the same both times. This should be obvious of course.
The next field is also a bone of contention for many and is called the Authentication Context. What this wants is connection information to a server which can be authenticated against in MAD. The examples on the screen show a DNS name, an IP address, or 'blank' and, in our case, we're going to leave it blank. This is the server (DC) in MAD which would be accessed for authentication of the user mentioned in the previous paragraphs. If we were not on a DC we would need to fill these in but because we're using the best configuration possible with the RL on a DC this is not needed and leaving it blank is correct. If you were using Negotiate at any time when the driver was on a member server you would be required to enter the DNS name of the DC and not just the IP address. If you are using just an IP address you had better be using Simple and then you're in an entirely different example. In all cases where you do have a value be sure it's just a DNS name or IP address. Do not include other protocol stuff like 'ldap://' or anything since it is not valid at all for this field and will cause errors.
Now we start getting into more MAD-specific stuff. The first option is the name of the MAD domain managed by this driver. This should be in LDAP format like the following:
With this done the next option is exactly the same but in DNS format like the following:
Usually these two options match each other closely except for syntax. These are critical for the driver to work so be sure they are correct. The domain in use can usually be found quickly via the Properties page available by right-clicking on 'My Computer' or going to System information. Also if you open 'Active Directory Users and Computers' from the Programs menu the domain usually shows up at the top of the screen showing the MAD environment's structure.
The next option is the password timeout and five minutes is usually fine.
The next option is 'Local' or 'Remote' depending on where the driver (shim) is going to be run. In our case we'll choose Remote though you could do otherwise if (and only if) the engine and eDirectory were running on a windows box. In that case the installation of IDM should have included the driver earlier.
This next page asks about the Remote Loader configuration. This is where we tell the engine how to find the RL (which we'll install on a DC before too long). In the first field put in the IP address or DNS name of the box running the Remote Loader. In the next field the default port is 8090 so we'll leave it like that. Later we'll see that these are joined with some other text to create the following line in the driver configuration:
Now we have a couple more passwords to fill in. First these passwords can be literally anything. They can be as complex or as simple as possible, but you really should keep them safe. The Driver Object and Remote Loader passwords are meant to have the engine and RL authenticate to each other. This helps ensure that you are only sending data to or from a device that you know is configured by you and not by Joe down the hall trying to intercept passwords. These can be changed on both the engine and RL sides at any time but whenever one side is changed the other must be changed to match. There is no complexity rule on these possible but as the administrator you can make it as hard as desired and making it fairly complex is a good idea once you're in production. In the meantime I'll use 'novell' for both passwords (all four fields).
Clicking 'Next' we're now on a screen that asks us about a 'Base container in eDirectory' whose description says this is where objects that come from MAD will be synchronized-to and objects from eDirectory will be allowed-from. I've created a special container in my tree just for this at the following location:
In this case the format desired for the field is just the Full Distinguished Name as follows:
In my example I'm opting to do Flat placement because it is simple and it makes MAD people happy since they don't need to worry about creating special containers. In this drop-down 'Flat' is the option to choose for this. Note that the default is 'Mirrored' which means that, by default, hierarchies in MAD will be preserved as objects come into eDirectory. This 'Publisher Placement' refers to the placement of objects as they come into eDirectory ('Publisher' channel).
The next option is the base container in MAD to which users will be synchronized. If you are not fairly familiar with MAD this could be a bit tricky. The example shown is 'CN=Users,DC=MyDomain,DC=com' which means the default 'Users' area of MAD. It should be noted and stressed that this pseudo-container has a CN naming attribute because it is not a true Organizational Unit (OU). For this reason you cannot create objects that are not users or groups underneath it. If you choose the base location in MAD for objects to synchronize-to as 'OU=Users,DC=MyDomain,DC=com' it will not work. Similarly if you create a new 'Users' container somewhere else in the MAD environment and try to refer to it as CN=Users you will be wrong. Anything you create will almost-definitely be an OU and the defaults are largely OUs and CNs. Because we're going for an easy setup I'll just use the default here:
This setting has to do with Subscriber (eDirectory to application) placement and in this case I'll choose 'Flat' also. Note that if you choose to synchronize to CN=Users which is not a true OU you will not be able to do Mirrored since the Users area cannot hold non-User/Group objects. Had we chosen to put objects under OU=IDMSyncLocation,DC=testad0domain,DC=com we could do Mirrored easily enough by changing the drop-down option.
The next option is to configure the data flow and, to show off everything maximally, we'll leave the default of Bi-Directional.
The 'Password Failure Notification User' is not important at this point since I don't need to have a user from whom password notifications originate so leave this blank.
'Configure Entitlements' will be set to 'No' and this is advisable for all until they become somewhat familiar with Entitlements.
Now we're starting to get into some advanced things. If you have Exchange 2000 or 2003 you may enjoy some of the next settings but I don't have those so I'll disable some of these. 'Exchange Policy' is now set to 'None' for me.
Because I want to synchronize group memberships I'm going to leave the next option at the default. This option says that group memberships will be synchronized if groups are being synchronized (they are by default). This is probably something you want and is a neat feature when it works in your environment.
The next screen talks about naming of objects in MAD related to their eDirectory counterparts. We could do this stuff manually but for the purposes of this introduction leave it at 'Accept'.
The next screen talks about managing the MAD login name. I have grown to enjoy the 'Follow Identity Vault name' since it creates a user's information in MAD based on the user's username and a domain-specific string I specify in the driver configuration. This is so users created via the IDM driver all have consistent names which are complete and ready to be used.
The last screen we reach before the summary asks us about rights the driver should have as well as the exceptions to the driver's synchronization. This is fairly straight forward but I'll cover it a little. For the driver to do almost anything in the engine (eDirectory side of things) it must have rights. Without rights it cannot synchronize changes from the application (MAD in this case) and often it can't even read changes happening in eDirectory to synchronize over to the application. Without rights this driver is fairly harmless. With that said once we give the driver rights to the tree it will likely become very powerful. In order to synchronize user creations, deletions, and password changes (among many other things) the driver must be given the ability to do this.
Because of security concerns regarding users who are seldom used by administrators I always use Organizational Roles when setting up any driver in IDM. The reason for this is that you cannot login as an Organizational Role though an Org Role is just as valid as anything else when it comes to security equivalence. Creating an Org Role with rights to do whatever this driver will do lets the driver do its job. If you have somebody malicious trying to find the user with all this power to login as that user and do their own changes they will be frustrated by a lack of any ability to login. It's impossible to login as an object of type Organizational Role so there's no need to worry about passwords on it or even being silly and “hiding” the object somewhere in the tree. For this case I'll create one with the following name and specify it as my security equivalence in the driver object.
I name these and put them in the same container with all my other IDM service-related stuff because it keeps my tree neat. This also guarantees that any server running the DriverSet is likely to have the security information handy to prevent tree walking unnecessarily. The role's name resembles the driver's and driverset's name which is on purpose in case I have multiple drivers with the same name in multiple driversets (this happens because I do a lot of testing). Because of the layout of my tree this object only has administrative rights to this driver's portion of the tree meaning the OU=testad0,O=suse,O=org portion of the tree. There is no reason to worry about somebody taking over this account and owning my tree because, despite this object's power in the tree, it doesn't have the ability to change itself or much of the tree above its one context. Defense in Depth is always a good concept to practice just in case you forget something at some point in time.
The next field below Security Equivalence deals with 'Excluded Users' and other objects which should not be synchronized by the driver. Even though my 'admin' user is not eligible for synchronization by this driver (it is in a completely separate part of the tree) I always add my administrative roles in here just in case something changes and I forget to do it exclude these roles at that point. What this specifically does is creates an 'association' for these objects (users, groups, containers, etc.) that is explicitly disabled so any attempt to change the object from eDirectory or from the application is blocked. Imagine if you will what many others have done in their environments. They setup this system (not always in a test environment) and gave the driver full rights to the entire tree. They then synchronize everybody over to their application and see it working. After doing a little dance they decided to start over and do more tests but not before deleting the objects from the application. When the synchronization of those 'delete' events came back to eDirectory the poor unfortunate admin user was included in the brutal carnage caused by the administrator. They are left without control of the tree all because of a simple thing like synchronization the admin of the tree. As a general rule do not synchronize administrative roles as it is just asking for trouble. On another note it is always good to have a backup admin of your tree though that doesn't help if you synchronized and deleted it like the original.
After clicking 'Next' and 'Finish' we now have the driver imported to our DriverSet which is a good thing. The testad0 driver shows up in the upper-right hand corner of the screenshot:
Notice the little red circle with a white line across it. This means the driver is stopped. Now compare the little squiggly arrows in the lower-right hand corner of this driver with the one below which also has a red/white circle on it. The testad0 driver is set to 'Manual' start while the one below it is set to be 'Disabled'. The third option for starting is 'Auto-Start' and appears with a lightning bolt across that lower squiggly-line section of the driver configuration in eDirectory.
So as a quick recap of what we've done so far a few steps are out of the way. First the engine software is installed on the eDirectory server. We have iManager working with the plugins and the MAD driver configuration has been imported to the DriverSet. If we were to start the driver right now it would sit there and run and try to connect to the Remote Loader forever. With that in mind let's get the Remote Loader configured and then we'll try starting the driver.
The first step to getting a Remote Loader going is to install it. On a windows server (W2K, W2K3, etc.) put the CD/DVD into the driver or copy the extracted installation files to the box. Run the './nt/install.exe' file and start the installation similar to how it was described above. This time, instead of deselecting all of the stuff except the Engine we'll deselect everything except the 'Remote Loader Service' and 'Active Directory' driver. The RL must be there to connect to the Engine and receive/send instructions. The driver (shim) must be there to convert those instructions to/from the application. This installation should be a fairly quick and painless process. It should probably be noted now that we're definitely working on a windows box due to some limitation of RDP. First, if you are on Windows 2000 you cannot use RDP for everything as it has limitations regarding some secure components of the system. This installation may work but certain access to the Registry as well as configuring various components of MAD, the password filters (which we'll come to shortly) or eDirectory (in windows) cannot be done via RDP. For those on windows 2003+ you can use the command that follows to connect to the local console session to do work there that was not possible in windows 2000:
After the RL installation you should have an icon on the desktop which is named 'Identity Manager Remote Loader Console' as I recall. It will have a Yin-Yang icon like other parts of IDM and be on the user's desktop by default. Run that shortcut to load the RL console which is an interface to help you create RL configurations quickly and easily in windows. Clicking 'Add' to add a new session will get you started. Section 3.3 of the current documentation covers this rather well with screenshots galore.
A few of the settings follow. First the description which is really the title in the RL console you'll see as you administer this connection. Chose one wisely, possibly named the same as the driver configuration in eDirectory.
The next field in the RL is the 'driver' which means the driver shim. In this case we want 'addriver.dll' since that is the shim to interface with MAD.
The 'config file' can be left at the default since it is automatically filled in as you create the driver description.
The IP address(es) chosen to be used for the connection are up to you. Using a single IP address (if multiples on the system) or listening on all IPs for a connection from the engine is fine. The connection port here must match the port entered for the Remote Loader in the driver configuration stored in eDirectory and 8090 is still the default. The Command Port is something that must be unique on the localhost interface that does not ever connect to anything else or allow anything to connect directly to it. For this reason it must be unique on this box.
The next few fields should remind you of the similarly-named fields in the eDirectory configuration of the IDM drivers. The driver object password here must match with the driver object password in eDirectory. The Remote Loader password here should also match the counterparts in eDirectory. As a reminder I used 'novell' for both fields previously.
The last section we MUST configure here is the Remote Loader's SSL certificate between itself and the engine. Section 3.2 in the Identity Manager documentation talks about how to setup a certificate. For the most part it is trivial but it does take up some time. The certificate's name needs to be specified in eDirectory on the Remote Loader line after the ;hostname=blah port=8090' part. The last parameter should be 'kmo=shortNameOfCertificate'. For a certificate named 'testad0 – idm0lin-1a.idm0lin-1a.server.system the short name required would just be 'testad0'. Section 3.4 of the IDM documentation covers the last bit of configuring done between the engine and the RL.
So now at this point you should be able to start your RL instance. At the prompt regarding running this process as a service go ahead and choose 'Yes'. I would also choose to start it automatically as a service on the windows box. Once this is done we can start the driver on the engine side to see if it will connect. Click on the Yin-Yang. to see a list of options of what to do with this driver and choose 'Start Driver'. At this point it should start and stay running and, with a little luck, passwords will even synchronize.
Now in regard to password synchronization a couple settings are required in eDirectory. First you must have a Universal Password policy to use the Password Synchronization 2.0 (the default) functionality. Setting one up is trivial. Basic steps in iManager include:
Name and settings
Assignments: Login Policy.Security or, in your case possibly just testad0.suse.org
Login with the user via an NMAS-enabled client or optionally have their password changed to populate the Universal password for synchronization in the future.
The quickest way to test the connection is to create a user in the base contexts on either side to see if it works by flowing to the other side. If this works, great. If not we need to troubleshoot it by reading error messages found in a trace (currently TID# 10098620 will help).
One more component left to be setup includes the password filters in MAD. On the box with the shim installed a Control Panel applet named something like 'Identity Manager PassSync' exists in the Control Panel. This is an applet to simplify the installation of the filters on various DCs in the MAD environment. Launching this applet will present you with a dialog about whether or not this server is running the driver to which you should reply 'Yes' since the driver shim is on here. You will also be prompted to enter the domain name probably from a drop-down box and, optionally, a server name. Leave the optional field blank and choose the appropriate domain from the drop-down. On the resulting screen select your domain and click 'Filters'. In this window you can select all of the DCs in the domain and install the filters as well as reboot them. Once that's done and they are rebooted (required) they should all forward password changes to the Remote Loader box.
Note when setting this up that every DC from which a password may originate must have the filter installed and windows will then require a reboot. Until this is done the filters may be installed but no passwords on that DC will be captured and sent to eDirectory though passwords should be able to go the other way (eDirectory to MAD).
So now we've gone through the entire configuration of a MAD driver to our eDirectory tree. No troubleshooting has been done at this point in case there were problems but for the most part this should cover all the steps. This is the long drawn-out version for sure so hopefully most of it made sense reading the documentation and IDM's prompts and, once you know the settings, an explanation will not be required to get going.
Hope that helps.
Submitted by: aburgemeister on Wed. 07.25.2007
Okay, where did we leave off? Ah yes, I believe we are working with the WorkOrder driver. The order (haha.. bad pun) of the day was to get a couple of these beauties working together to manage the beginning and end of a user's life but let's skip the beginning for now (people asking for demos now, not later). Eventually my plan (possibly revised from before) is to get it all in one driver. The developer says this will help things out. He also mentioned efficiency in keeping all WorkOrders for a given driver in their own container rather than having multiple drivers' objects per container. So it is possible, but apparently not recommended by people who know things, to have those objects clumped together. Sorry for any misinformation. I'm trying to get this all done properly the first time but apparently my perfection is wearing thin these days.
So in the previous post I gave the example of how this could be used when a user is created having them enabled a couple weeks later when they officially started work or school. The other example was of a user being terminated for one reason or another. Setting their 'loginDisabled' attribute to TRUE should take care of them, but maybe deletion should not be done right away for some kind of legal/compliance reason. Working around this is what we'll demonstrate today with disturbing amounts of detail. As one mentor of mine likes to say, “I hear and I forget; I see and I remember; I do and I understand.” As we work through this do it on your own as well. This is a free driver that comes with a product that has a 90-day evaluation and can run on eDirectory (no license required for this kind of thing) on Linux (again, free). You can even use various tools for the setup that aren't command-line tools like iManager and Designer which are both $10,000,000,000 per CD at AB's Shopping center (comes with setup and technical support), but free if you get them online.
So let's move into the driver. I'm including the export of my current driver (testWO-0) with this entry for any who are wanting to use it directly. All examples will be from this example with its current policies. Importing the preconfigured driver is as simple as almost any other driver though, unless you name your driver 'WorkOrder' (case-sensitive), you must change a few things after the fact. With my first shot I did not name my driver 'WorkOrder' and it was a good learning experience so I'll be passing that all along. To start with let's import a default driver and look at the options in there.
Actually, let's start at the very beginning, a very good place to start. For this walk-through I'm using Mobile/Workstation iManager 2.6 SP3 with the IDM 3.5 plugins. The same driver import can be done with Designer with a few differences but those should be fairly minimal. Open iManager, login as somebody with power, choose 'Identity Manager' and then 'Identity Manager Overview'. Go ahead and search for a DriverSet in your tree. If you don't have one go ahead and create one. If you just created a DriverSet you'll be prompted to import a driver configuration. If not click 'Add Driver' and then choose the WorkOrder-IDM3_5_0_V1.xml. This is the driver preconfig which has the default settings in it. Moving to the next screen rename the driver to testWO-0 (case-sensitive for these examples). Choose a container for WorkOrder objects. At this point I need to explain my tree a little bit.
Many organize their trees by hierarchy or geography, which is a great model to follow. There are some problems that arise with these models, though, like where to put things that aren't people. Where do servers go? Where do printers go? Where do IDM objects and DriverSets go? IDM especially does not lend better or worse when placed geographically and most of the time neither do non-users/groups, at least in my limited experience. With this in mind my tree tries to work around all that. At the root of my tree instead of an Organization I have Security along with two domains (DC) called 'org' and 'system'. 'system' contains everything that isn't a human or group and 'org' contains all of my organizations ('novell', 'suse', etc.). Having multiple Organizations underneath this common non-Tree object is really nice with IDM because you have a starting place for various queries that is not the Tree object. Rights can be assigned without affecting servers through inheritance. Life is generally good. Underneath the Os it's fairly typical and broken down by whatever is best (geography, company hierarchy, etc.).
On the 'system' side is where the beauty lies. Under 'system' are 'user', 'service', and 'server' Domains. Under 'server' is a container (Domain) for each server in the tree (named the same as the server instance) which holds all of the server-related objects. Underneath 'service' is a Domain for each service in my tree including 'lum', 'idm', 'rbs', 'mail', and whatever else I throw in here. Finally under 'idm' exist all of my IDM-related objects including DriverSets, Organizational Roles (from which drivers receive their privileges), and for this driver the various WorkOrder and WorkToDo containers. See another blog entry later on for more benefits of the tree design.
So with this driver import my containers are dc=testwo-0workorder,dc=idm,dc=service,dc=system and dc=testwo-0worktodo,dc=idm,dc=service,dc=system. These containers are where the physical WorkOrder and WorkToDo objects will live in eDirectory while waiting for processing or after completing all processing and waiting for deletion or administrator action. Note that the import actually wants these in dot notation and not LDAP format as I'm specifying them (for simplicity understanding the levels).
The default polling method is 'By Interval' which is great for this test. Set the Driver Heartbeat to 'No' because we don't need it at this point. We'll also be running this driver locally. On the next screen enter a polling interval in minutes. In real life this should probably be something like 60 but in this example we'll use something from one to five (your choice).
On the next screen define the driver's security equivalence. I created an Organizational Role called cn=testwo-0defaultdrvrset35,dc=idm,dc=service,dc=system specifically for this driver. It was given supervisor to Entry rights to a container under my suse Organization (cn=testwo-0,o=suse,dc=org) and also the same for the WorkOrder and WorkToDo containers specified earlier on. In a production environment the Organizational Role may need rights to more of the tree but, as I said, I do lots of testing so having things with rights assigned all over just for kicks leads to anomalies that are a pain to troubleshoot. Be sure to exclude administrative accounts. Having granular rights assignments and good tree design minimizes the impact of forgetting this step (my admin accounts are all separate under dc=user,dc=system) but excluding your own user is always a good idea when testing.
Finally complete the import. At this point a driver should be in the tree with the start option of Manual. If you are using the import I've included the start option is set to Disabled so you don't inadvertently cache events. As with any IDM driver there is a TAO file caching events if the driver is in Manual or Auto-Start mode but not running, or when running but not keeping up with the incoming work load.
Go ahead and open the driver properties for this driver. First on the scren should be the driver class of 'com.novell.nds.dirxml.driver.workorder.WorkOrderDriverShim'. The next few fields are, as far as I can tell, not really used. Like the Loopback driver this doesn't have an application against which it needs to authenticate so the 'Driver Object' and 'Application' passwords don't do anything. Similarly the authentication ID and context don't do anything (I have no idea why they have values in them by default but, as in most things XML, extra doesn't hurt). Below the Startup Options are some Publisher Settings. My 'Work Order Objects DN' is 'system\service\idm\testwo-0workorder', 'Poll Interval (minutes)' is 5, 'Poll Time' is blank, and 'Heartbeat on' is 'No'. Feel free to look around the rest of the options in here as most things are fairly standard. A lot of fields are not present because that is the nature of the driver. While looking around go to 'Misc' and set the trace level to 3 and write the trace file to something like '/var/opt/novell/idm/testwo-0/trace.log' after running `mkdir -p /var/opt/novell/idm/testwo-0` on your server or creating the appropriate directory structure some other way. Change these back before going into production but for now having the trace ready will probably help more than hinder.
Now finish up in the driver properties and move to the Driver Overview by clicking on the driver object itself. You should now be at the 'fishbone diagram' with both the Subscriber and Publisher channels shown. Here we are going to make some slight modifications. Choose the Filter and add the User class and, underneath that, the Login Disabled attribute. Set the class to Synchronize and the attribute to Notify on the Subscriber channel leaving the Publisher set to Ignore for both class and attribute. The WorkOrder and WorkToDo classes should be in there properly already.
Notice there is not Event Transformation policyset included nor is there any Matching policyset. There's nothing to match here so that's gone of course. The Creation policyset has one simple rule that verifies any WorkOrders coming in via the Subscriber channel are valid with all required attributes present.
Moving along to the Placement policyset is some important stuff that you MUST change for things to work currently. As the default driver was setup the placement policy looks like it will put WorkOrder objects in some \WorkOrder container with the name of the object moving through. This is not really the case and can be a cause for confusion so don't let it do that. The Placement policy simply marks the object with the driver name which is case-sensitive and then the name of the WorkOrder object in the channel (which can be anything unique to that container where WorkOrder objects go). So if you had not renamed your driver it would be named 'WorkOrder' and the placement policy of \WorkOrder\Source Name() would work properly; however, the instructions were to rename the driver to testWO-0 so now things do not work and you will get a nasty error in the trace about how you have 'No Destination DN'. Right before that shows up the trace actually tries to help you know what is expected so that was a nice addition from the developer. For some fun let's look at a trace with this in it:
[05/02/07 17:19:01.474]:testWO-0 ST:Submitting document to subscriber shim:
[05/02/07 17:19:01.477]:testWO-0 ST:
<nds dtdversion="3.5" ndsversion="8.x">
<product version="184.108.40.20670315 ">DirXML</product>
<add class-name="WorkOrder" dest-dn="system\service\idm\testwo-0workorder\wotest06" event-id="idm0lin-1a#20070502231901#1#2">
[05/02/07 17:19:01.494]:testWO-0 ST:##WorkOrder Sub -----:: WOSubscriptionShimm execute
[05/02/07 17:19:01.496]:testWO-0 ST:##WorkOrder Sub -----:: commandClass = class com.novell.nds.dirxml.driver.xds.XDSAddElement
[05/02/07 17:19:01.498]:testWO-0 ST:##WorkOrder Sub -----:: WOSubscriptionShim addHandler driverDN = \testWO-0\Object DN =system\service\idm\testwo-0workorder\wotest06
[05/02/07 17:19:01.502]:testWO-0 ST:SubscriptionShim.execute() returned:
[05/02/07 17:19:01.503]:testWO-0 ST:
<product build="20070301_0812" instance="testWO-0" version="3.5">DirXML WorkOrder Driver (Java)</product>
<status event-id="idm0lin-1a#20070502231901#1#2" level="error" type="driver-general">
<description>No Destination DN</description>
So we can see that this is the end of the document's life on the Subscriber channel. It is off to the shim and it has a dest-dn that I ever-so-cleverly set to where my WorkOrder objects should go. The only problem is that I didn't understand what was going on at all. The trace shows what is wrong at 17:19:01.498. It states that driverDN=\testWO-0\Object and then the actual DN which is system\service\idm\testwo-0workorder\wotest06. The part about driverDN is what it wants, only with something unique in the place of 'Object'. So here we have worked past our first error that would probably catch most people new to the WorkOrder driver up for a fair chunk of time. It's not very intuitive at all but if I hadn't wanted some naming scheme for this driver it wouldn't have happened. We'll see what happens to this object on the Publisher side.
So we're past the placement policy. The next thing to do is to get to the Command Transformation policyset. This is an important place for our driver because, as you may recall, the idea is to have a WorkOrder created when a user is disabled and to cause the WorkOrder to be used after a period of time finally deleting the user who was disabled. We have allowed the User object into the channel but we still don't have a WorkOrder. It will be created in the Command Transformation policyset.
Note that a lot of the code to do this is actually in the WorkOrder driver documentation. One of the links with code doesn't open very nicely in a browser that bothers to verify the XML but the files do work and can be viewed if you go after the source from the browser or save them directly to your system.
The first policy in the policyset creates the WorkOrder from the user synchronizing through.
<?xml version="1.0" encoding="UTF-8"?><policy xmlns:jdate="http://www.novell.com/nxsl/java/java.util.Date" xmlns:jformat="http://www.novell.com/nxsl/java/java.text.SimpleDateFormat">
<description>Convert User object Add to Work Order object add</description>
<if-op-attr name="Login Disabled" op="changing-to">TRUE</if-op-attr>
<do-add-dest-object class-name="DirXML-WorkOrder" when="after">
<do-add-dest-attr-value class-name="DirXML-WorkOrder" name="Description" when="after">
<do-add-dest-attr-value class-name="DirXML-WorkOrder" name="DirXML-nwoContent" when="after">
<do-add-dest-attr-value class-name="DirXML-WorkOrder" name="DirXML-DueDate" when="after">
<token-xpath expression="round(jdate:getTime(jdate:new()) div 1000)+60"/>
<do-add-dest-attr-value class-name="DirXML-WorkOrder" name="DirXML-nwoDeleteDueDate" when="after">
<token-xpath expression="round(jdate:getTime(jdate:new()) div 1000)+21600"/>
This first policy works for add events for objects of the User class which have a loginDisabled attribute changing to TRUE. Once that is established a new object is created with a proper dest-dn (see previous paragraphs), a DirXML-DueDate set to one minute from the current time (when the WorkOrder will be processed on the Publisher channel, one minute isn't the most-practical example but it does lend itself to faster testing), Description and DirXML-nwoContent attributes which both happen to have the DN of the original user object in them (for use later), a DirXML-DeleteDueDate set to 6 hours in the future, followed by a veto of the original User-add event. So the end document is a full DirXML-WorkOrder object with the required attributes set to process in one minute and to be deleted in six hours. So far so good.
The next policy finishes making the DirXML-WorkOrder object complete by adding a source DN (src-dn) as well as the object's first status of 'pending' which is important. The publisher polling that takes place every few minutes looks for WorkOrders of different types. A 'pending' WorkOrder is ready to be worked on immediately assuming the DueDate has been reached. Other statuses include 'error' which are WorkOrders that will not be processed until somebody intervenes or the driver deletes them if the driver is set to delete erring WorkOrders. Anyway it's a tangent I don't want to explore right now but just keep the status in mind. The next policy in the Command Transformation policyset follows:
<?xml version="1.0" encoding="UTF-8"?><policy>
<description>Set Synthesized WorkOrders Source DN</description>
<do-add-dest-attr-value class-name="DirXML-WorkOrder" name="DirXML-nwoSendToPublisher">
<do-add-dest-attr-value class-name="DirXML-WorkOrder" name="DirXML-nwoStatus">
So we can see that if src-dn is not available one is added. The src-dn that is assigned is the one from the User that started this whole mess. Also the DirXML-nwoSendToPublisher is set to true so this document will be sent to the publisher. What does that mean specifically? When a subscriber WorkOrder is “sent to the publisher” it means it is written to the container you specified way back in the beginning. If we also added a rule that said 'DoItNow=TRUE' the Publisher would also fire up and process all WorkOrders, but that's not the case for us now (doesn't make much sense really since we're planning on everything happening in one minute, not immediately, and this would probably be set to do things in thirty to ninety days in a production system).
That's it for the Subscriber channel. We have told the new WorkOrder to go to eDirectory where it is waiting for some kind of action from the Publisher channel's polling. That polling is where more fun takes place. Looking at that channel you may have noticed it is quite sparse. There is nothing populated except for the Schema Mapping policyset and the Placement policyset. Let's skip over to the Placement policyset and see how mine has changed slightly from the default.
<;?xml version="1.0" encoding="UTF-8"?><;policy>
<;description>Work Order Placement<;/description>
<;if-src-dn op="in-subtree" xml:space="preserve">\WorkOrder\<;/if-src-dn>
<;if-src-dn op="not-equal" xml:space="preserve">\WorkOrder\<;/if-src-dn>
<;description>Work Order To Do Placement<;/description>
The first rule should catch your attention. It has that pesky driver name in there again. We have already modified the placement policy for WorkOrders on the Subscriber side to have the correct driver name and we should do the same here or anything coming back from the shim on its way to be written in eDirectory will fail. The first rule is designed to give WorkOrder objects a valid placement policy in eDirectory. This path came straight from the preconfig back in the beginning when we were asked for it which is why it has that in there already. With the proper conditional statements WorkOrders can now safely make it into the holding cell in eDirectory.
The second rule is geared toward the WorkToDo objects that come from the polling cycles the driver is set to do already. As a WorkOrder object is brought in from eDirectory it is made into a WorkToDo object containing the same attributes that the original WorkOrder object contained. It is this object that will cause all the fun to happen after the user has been disabled for thirty to ninety days (or one minute in our case). Note that the Publisher is polling regularly for objects whose DirXML-DueDate attribute is in the past. When that time is in the past and the polling cycle runs and the object is 'pending' it is processed. So after the period of time the Publisher Placement policyset eventually ends up with this object and by default puts it in the WorkToDo container specified back when originally setting up the driver. This is fine but doesn't do anything for anybody. It is possible you could then have other drivers act on objects created in this container. You could also write scripts or applications in other languages that watched this container for additions and did things based on those additions. In this case, as this is a simple example, we'll just delete the object of the user who was disabled. What follows is the Publisher Placement policy from my driver. Granted I have hacked it up a little because I didn't know exactly what I was doing in the beginning but it still works nicely. Most of the hacking seems to be on the conditions for the placement policy for WorkOrder objects, not WorkToDo objects.
<?xml version="1.0" encoding="UTF-8"?><policy>
<description>Work Order Placement</description>
<!-- <if-src-dn op="in-subtree" xml:space="preserve">\WorkOrder\</if-src-dn>
<if-src-dn op="not-equal" xml:space="preserve">\WorkOrder\</if-src-dn> -->
<rule disabled="true" notrace="true">
<description>Work Order To Do Placement</description>
<description>Work Order To Do Placement</description>
<do-set-op-dest-dn disabled="true" notrace="true">
So what is happening is that I have commented out some conditions for WorkOrder object placement. This doesn't have much effect since I left the one condition to be sure it was a WorkOrder object in there and I only have WorkOrders coming from one location. The second rule is a disabled original rule for WorkToDo objects with tracing turned off. I prefer disabling rules I don't use rather than removing them because I make a fair number of mistakes and it's faster re-enabling than it is re-creating.
The final rule is the one that finishes off dead users. If the source DN (src-dn) is correct and if the class is correct then normally the dest-dn is set properly so the WorkToDo object can go out to eDirectory. That action is disabled, though, and instead a new action exists which tells IDM to (directly) delete the object whose DN is stored in the DirXML-nwoContent attribute of the WorkToDo object. As you may recall we set that to the original user's DN way back in the first Command Transformation policy on the Subscriber channel. The last action is to veto the current event because I didn't want to fill my tree with WorkToDo objects. This could be allowed to proceed as long as there was a valid dest-dn (the other action I disabled).
As the polling picked up the WorkOrder and turned it into a WorkToDo object the Status changed to Configured (as I recall) and there were more notes written to the initial WorkOrder object about the status of everything taking place. The ProcessLog attribute has this log built into it and the driver writes to it automatically. This is a neat little audit of this particular WorkOrder's events. The WorkOrder should be around for another five hours fifty-nine minutes (give or take a minute) so you should be able to see things in there. You could also probably write rules to add notes in there directly due to your own custom logic. Hands-free auditing of each event could be very helpful.
Now there is a significant amount of potential for this driver in the DirXML-nwoContent and other attributes. Many of them haven't been covered at all in these blog posts because they aren't essential but do not limit yourself for just that reason. Knowing the basics will get you going but there is more to be done. For example making a driver do multiple things should be as simple as including something in the WorkOrder and/or WorkToDo object that has an action. We didn't tell this driver to do the delete. It was just programmed to only delete disabled user objects. It should be trivial to put an action of some kind in Description ('add', 'enable', 'reset password', 'changeGivenNameTo', etc.) upon which you could base a lot of logic. The placement policyset could have a dozen different rules for different types of events that came through so this WorkOrder driver could handle dozens or hundreds of different types of regular activities. Entire XDS operation documents could be included and executed from a WorkOrder object.
So that leads me a little bit to scalability. What happens when you want to use this in an educational environment where users are added and removed each year, or group memberships based on a class schedule arechanged every semester/quarter. How long does it take for 1,000 WorkOrders to be processed? A commenter to my previous post asked that and I did a humble test with the driver we just went through. The test was to create 10,000 users in the container and then to disable the logins. Those disabled logins caused 10,000 WorkOrder objects to be created and, after the creates of those events was complete, the polling interval fired off (twenty minutes later) and took care of deleting the original user objects. Less-than six hours later all of the WorkOrder objects were also automatically deleted.
A note regarding my environment is due. I am running three servers. One Optiplex GX1 500 MHz server with 512 MB RAM is running Linux OES SP2 with eDirectory 8.8.1 and IDM 3.0.1 (not running this driver though, obviously). Another Dell desktop (one of those thin skinny things that goes under the monitor) with a 667 MHz processor and 512 MB RAM is running SLES 10, eDirectory 8.8.1, Security Services 2.0.4 (SS204) and IDM 3.5 with the WorkOrder driver that did all this work. The import and disabling of logins were both done via LDAP with the 'user.pl' script (a CoolSolution on Novell's website). A third Dell workstation was also in the mix with eDirectory 8.8.1 and two instances of eDirectory, both in this same tree. So even with old hardware and four replicas (of the entire tree) spread out this test ran and impressed me a little bit.
The test of creating 20K objects (10K users, 10K WorkOrders), polling for objects, modifying the WorkOrders, and deleting the users took about one hour and forty minutes. This included replication to all other instances of eDirectory in the tree (the other three) across my awesome 10 Mbit hub. Granted the poor little desktop was really working hard during that time period and I probably should have disabled the trace file to help, but it all finished rather nicely. I had a hiccup at the beginning because I had my DeleteDueDate set to five minutes. The problem with this is that the WorkOrder objects weren't finished being created within those five minutes so once they were finished the Polling took place and found all those expired WorkOrders and deleted them without taking care of the processing that would have deleted the original User objects. This is why you do testing, why you use better hardware, and why you don't decide to delete disabled users immediately. It was a good learning experience in logic errors and timing issues if nothing else.
Now with all this under your belt and with a decent understanding of all things WorkOrder it is probably a good time to go read the documentation. Please provide suggestions in there to improve it. This driver is not terribly (in my opinion) intuitive to veteran IDM engineers and having some content in there that would help bridge the understanding would be great for all.
The driver mentioned in the post follows. It is a GZipped XML driver export. With the .gz extension most compression utilities should have no problem opening it. Linux has utilities to do so built in. For those on windows please use something like 7-Zip or WinZip or some other freeware with this built in.
Recently I came across a new driver that has been added in Novell Identity Manager (IDM) 3.5. The name of the driver is the 'WorkOrder' driver. Not to be confused in any way with 'Workflow' or the User Application (UserApp) and what those do, the WorkOrder driver is a completely new type of driver that will probably throw those familiar with IDM and its existing drivers for a loop. During my first implementation I relied a bit too much on my past knowledge and it bit me fairly hard. With that in mind I want to make this useful driver as easy-to-understand as possible for others out there.
So what is the WorkOrder driver? First let's go over what it is not for those who are already familiar with IDM. It is not a driver that connects to another application or system by default. Therefore, similar to the Loopback driver, it is not a driver that synchronizes identities from one environment to another. This will become overly-obvious when you notice the filter does not have any User or Group classes in it by default. Without users Passwords become fairly dull so this driver doesn't do any Password Synchronization. Similarly a lack of users means a lack of roles, so Role-Base Entitlements (RBE) are out as well. This isn't a lack of functionality for the driver but, as a special driver, it's just outside the scope of what the driver needs to do. This driver also primarily does its heavy lifting on the Publisher channel similar to the eDirectory driver. The driver's object placement is not what you think if you have any experience with IDM and you will get errors if you try to treat it like a normal driver with regard to object placement.
So now hopefully the experienced IDM people are making few if any assumptions about the driver, and people newer to IDM are where they would be anyway. With this lack of presumptions let's continue. The WorkOrder driver is made to handle odd little objects new to IDM 3.5 with a class of DirXML-WorkOrder. These classes have a few predefined attributes that meet the objects' needs and that are needing some good explanation. We'll explain this more later on but here's some information to start with:
DirXML-DueDate: The date and time the workorder is to be executed
DirXML-nwoProcessLog: A log of things that happen related to this WorkOrder. Having this log means you get automatically (really, no configuration) logging with regard to this WorkOrder's history from the WorkOrder driver.
DirXML-nwoStatus: The status of the current WorkOrder object. Pending, configured, resolved, canceled, error.
DirXML-nwoDeleteDueDate: When to delete the WorkOrder. This also works with the next attribute for situations when an error occurs.
DirXML-nwoDeleteOnError: If an error occurs (status = 'error') specify if the WorkOrder should be deleted when the DueDate comes. A WorkOrder with the 'error' status is done as far as automatic operations are concerned so manual intervention is now required. Without being deleted these will sit forever.
DirXML-nwoSendToPublisher: Specify if this WorkOrder should be sent to the Publisher channel immediately. Can be true or false and, if false, the WorkOrder waits until the next polling cycle or heartbeat for it to be processed on the Publisher side. If true it goes immediately.
DirXML-nwoDoItNowFlag: Interesting name for an attribute but it tells the Publisher channel that this WorkOrder must be processed now. As a result the documentation indicates that ALL WorkOrders that are ready to be processed (by DueDate) will be processed immediately.
DirXML-nwoDependentWorkOrder: DN of a WorkOrder object on which this WorkOrder depends. This WorkOrder won't go until its dependency has a status of Configured.
DirXML-nwoContent: An attribute used to store custom information specific to this WorkOrder. It is passed through to the WorkToDo object.
There are quite a few other attributes but most of them are fairly self-explanatory (creator's name, creation timestamp, a few other fields for miscellaneous data, etc.).
DirXML-nwoDN: The DN of the WorkOrder from which this WorkToDo object originated.
DirXML-nwoContent: Look familiar? This holds the data that was in the same attribute on the WorkOrder object that led to this WorkToDo object.
There are quite a few other attributes for this class as well and most of them are copied directly from the WorkOrder object. We'll see why before this is all through.
So let's move on to the default driver filter to see what happens there. As mentioned a large change for this Filter is what it works with (no Users, Groups, etc.).
What is interesting here is that WorkOrder objects are used in both channels, while WorkToDo objects are only sent out from the Publisher channel. We'll see where they come from before this is all through.
So let's try to get our minds wrapped around the driver's functionality. The WorkOrder driver is made to create and process an object of type WorkOrder, possibly ending up with a WorkToDo object. Let's use an example that fits with this driver. Imagine you have a driver from your Human Relations (HR) system, PeopleSoft. This driver creates users in your Identity Vault (IDV) as employees are hired on. What happens in the two weeks or months between when the user is added into PeopleSoft and they start working? Jack the evil cracker in marketing is trying to break into the new employee's account. It's out there, might have a default password, and is ripe for exploitation. To prevent this type of malicious user from having weeks to months with access to things they shouldn't the account is logically disabled but now a new administrative chore surfaces. Who enables the account on the first day of employment? Does the new employee wait around while the administrator who would have enabled the system is out sick or do you give managers rights to enable and disable accounts and hope they remember how to do it, have the tools to do it and the ethics to be honest?
Enter the WorkOrder driver to save the day. When the user is provisioned from PeopleSoft a WorkOrder is created by that driver and placed where the WorkOrder driver will find it. This object is made to be processed by the WorkOrder driver and has some data relevant to the WorkOrder's task in the object. DirXML-nwoContent has the DN of the user who was just hired. DirXML-DueDate has the date and time when the user should be officially enabled. The driver detects this object and processes it much like a normal driver would process a user creation.
The WorkOrder object is placed in a container where it is held until the DueDate comes along. In this first example we know this is the first day of work for the new employee. The WorkOrder driver differs slightly from others at this point in that it implements a Polling Interval, Heartbeat, or both to regularly check on the objects in the pending area. The polling interval can be a time period or a time of day (or both). An appropriate value for this example may be 0030 (12:30 a.m.) so that new users are enabled in time for their first day. The DueDate is set for the first day of work, sometime before 0030, and when the polling takes place the WorkOrder object is finally processed by the Publisher Channel.
The WorkOrder shim is sent a WorkOrder object (mapped in Schema Mapping policyset from DirXML-WorkOrder). A difference between this driver and others appears here. There is no application for the shim to send the object to so, if DirXML-nwoSendToPublisher is set to true this new WorkOrder object is sent right back into the Publisher channel where it is eventually written back into eDirectory. The object has an association to this driver in the Engine and subsequent polling intervals will affect it.
The WorkOrder driver shim picks up the new DirXML-WorkOrder object (through queries), verifies it should be worked on at this time, and starts it through the Publisher channel. On its way through the object is treated as a 'WorkOrderToDo' object (not DirXML-WorkOrder') which is then mapped to DirXML-WorkToDo. When was the DirXML-WorkOrder object made into a WorkOrderToDo object? Once the shim determined that the DueDate had arrived and passed it built this new WorkOrderToDo object with the values from the original WorkOrder. From here on out the WorkOrder is simply used to log processes as they take place.
A normal DirXML-WorkToDo object is short-lived. It basically goes into the Publisher channel as an add-event, is optionally evaluated for things to do by the custom policies, and is written to a container in eDirectory made for WorkToDo objects. This object-creation could kick off a Loopback driver designed to do the actual enabling of the user along with a number of other tasks but in an example like this we could just as easily do this in the WorkOrder driver. For instance there is a Placement policyset created by default that really isn't needed for our example. The desired behavior is to have the new employee's account enabled. To do that a simple rule can be placed in a policy to set the destination-attribute of 'Login Disabled' for the user specified in DirXML-nwoContent to FALSE (was set to TRUE before as you might recall), effectively enabling the account. The actual creation of the DirXML-WorkToDo object can be vetoed as it's not needed for this example and we are finished. A quick recap may be in order:
Create disabled User object with PeopleSoft in Identity Vault
Also create WorkOrder object at the same time setting its DueDate to the employees start date and the nwoContent to the new employee's DN
Driver processes WorkOrder placing it in a directory made for WorkOrders. Polling available WorkOrders does a check to see if they are due.
When WorkOrder is due it is read and sent to the Publisher channel as a WorkToDo object.
Custom processing can be done here if desired to actually enable the user in the nwoContent attribute or it can be left to another driver.
Optionally write WorkToDo object to eDirectory for other processes to use.
Here we have seen one example of what the WorkOrder driver can do. Another practical example I am going to demonstrate in my next blog post will be a driver that ends a user's lifecycle. Many companies may not have PeopleSoft or SAP or some other large HR system, but most companies terminate employment of users at some point and a few I have come across want to delete the users but not until a period of time has elapsed. This can be in case the employee comes back, for legal reasons, for auditing, or many other reasons. No matter what the reason there is a need for somebody with a fair amount of authority to spend time cleaning up users after a period of time. Again, do we have the senior administrators do this instead of hunting for bad guys or fixing the payroll system? No, this is something to automate and is a good example of a WorkOrder driver's task.
This new driver will probably not depend on something else for the initial workflow creation. A simple way to work past this is to let the driver itself detect when a user is disabled or moved to a container for terminated employees. After detecting a disabled user a small amount of IDM policy (written via a GUI because that's my kind of option today) creates the DirXML-WorkOrder object which then is sent through the remainder of the Subscriber channel. The biggest difference between this example and the previous example is what happens on the Publisher side. When the user is disabled and the WorkOrder is created its due date attribute is set for 90 days into the future. When those 90 days have elapsed and it's time for the user to be deleted the polling picks up the WorkOrder and determines this is for a delete. A rule is added which sees a WorkToDo object coming back through the Publisher channel and has enough brains to know what the WorkToDo object is all about. Knowing it's been 90 days since the employee was terminated the driver deletes the object from eDirectory and could optionally do other operations to clean the employee from other systems. Because this was the completion of an employee's lifecycle in eDirectory the administrator determines there's no need to leave the WorkToDo object around and veto's the placement to prevent these objects from building up. It could have been allowed through but with no reason to store it we'd might as well save space.
So far we have seen what the WorkOrder driver can do and hopefully a few ideas for your own environment come to mind. For instance this is a fairly simple and customizable cron job built into eDirectory. IDM 3.5 also has “Jobs” but those are meant for other things. This driver can save a lot of time with tasks every administrator currently has assigned and always forgets because they are out of the office or the time delay causes forgetfulness. Policies for keeping the environment clean can be written once and run forever with minimal monitoring. Imagine the audit where your boss or a SOX auditor comes and asks for a forensics trail regarding users' data removed from a given system. Picture yourself confidently referring to one little WorkOrder driver doing all your mundane tasks as needed all because of a process started by somebody over in HR who didn't know a thing. Sounds like a good way to make life easy, and so I must get you ready for the price for all this functionality. All good things come with a price but thankfully this one is not that bad if you use a simple equation.
Calculate dozens of uses for this driver. Keep track of the time required to do this.
Multiple the amount of time it took to do that, plus some time to implement it, by your hourly wage.
Subtract the amount of time you would have wasted doing this work yourself.
Subtract the amount of stress received from your higher-ups over completion of various mundane tasks.
Add in a negative number for your personal bonus for meeting all your mundane-task objectives so well.
Add in a negative number arbitrarily chosen by yourself representing your job security's worth to you.
If you are anywhere above $0 I'll be surprised. As an IDM customer you already have full access to this driver. As one of the many IDM service drivers this one has no additional fees required. Labor is required of course but I think the benefits will make it worth your while.
Anyway, that's all for today. Another post with at least the latter example above will be coming before too long.
If you have any interesting comments on this driver or uses you have found please post them. Any great implementations you want to share can be submitted as CoolSolutions to help others enjoy life more and to earn you points (so you can enjoy life more, up to and including a cruise for two to Hawaii).
Submitted by: aburgemeister on Tue. 05.22.2007