Many years ago I worked with a client who used Lotus Notes and wanted to send password changes to Notes. Out of that work, a number of articles got written.

• https://www.netiq.com/communities/cool-solutions/windows-remote-loader-tasks-lotus-notes-driver/

• https://www.netiq.com/communities/cool-solutions/setting-notes-id-password-idm-3-5/

• https://www.netiq.com/communities/cool-solutions/upgrading-notes-driver-shim-idm-3-5/

• https://www.netiq.com/communities/cool-solutions/configuring-lotus-notes-group-types-idm/

• https://www.netiq.com/communities/cool-solutions/setting-multiple-mailfile-path-idm-notes-driver/

• https://www.netiq.com/communities/cool-solutions/setting-passwords-notes-driver-remote-share/

• https://www.netiq.com/communities/cool-solutions/signing-dsrepcfgntf-file-domino-server/

• https://www.netiq.com/communities/cool-solutions/mapping-cn-full-name-notes-driver/

• https://www.netiq.com/communities/cool-solutions/handling-e-mail-addresses-objects-idm-notes-and-edirectory/

• https://www.netiq.com/communities/cool-solutions/scoping-delete-events-lotus-notes-driver-idm/

The thing about Lotus Notes, now called Domino, no more Lotus in the name, owned by IBM is that there are multiple passwords involved in the process. Now as an eDirectory fan, there is very much a throwing stones in a glass house vibe when I talk about number of passwords in a system.

After all, eDirectory has the NDS password, Simple Password, Universal Password (and technically the Distribution Password).

But Notes is a different beast because like the NDS passwords, it is not stored as a password per se that is used to login, rather an RSA Private/Public key pair. The Notes ID file, is the actual private key, and thus needs to be protected with a password. However the fun part is, you could take 5 copies of the ID file, set different passwords on all 5 (assuming you knew the old one to change it) and then all 5 ID files would be perfectly valid, would work with the appropriate password. The password is just the key to unlock the private key in the file.

There is a second password, the HTTP Password, which is used when you log in via the web interface to Domino. This is just a password stored hashed (I assume, but the key is, it is a stored password effectively).

What this means for Identity Management is that you need to be able to change the ID file password as well as the HTTP Password. The latter is easy, just send in a modify-password event and it sends and changes it. Great.

The ID file, not so much. The shim needs file system access to the ID file, the old password, and a new password. The old password is required, since the old password is used to unlock or decrypt the key, then the new password is used to re-encrypt it.

Recently I upgraded an IDM 3.5 (!) on Netware (!) system doing just this task, to IDM 4.5 on SLES 11. In doing it, I had to go remember all the specific steps needed to get it to work. But that was ok, I knew I had written it all down in articles over the year, just look at the list in the top. But as I did it, I realized that I had just started writing Cool Solution articles back then and they were short and to the point. I have since gotten much better at these things and figured it would be worth revisiting the topic and try to sum it all up in one place with better examples. (I managed to snag some trace samples that show what I was interested in, which I find very instructive in reminding myself what needs to happen).

The Notes shim sends a lot of command information as XML attributes of the event node. (The <add> or <modify-password> nodes). Thus most of the work involved is done by setting some XML attributes on the <modify-password> event.

There is an Engine Control Value that needs to be set, which defaults to off.

The shim needs file system access to the various files being used. This critical, as it won't work without it. I demonstrated that you can do this via CIFS or NCP. That is your ID file can reside on a Windows or OES shared directory. We tested with both. The driver needs to be able to find the file as well, so consistent naming is important.

Years ago, when I worked at a University that switched email systems to Domino, one of the things we did was run the Notes client from a server which saved us installing it on thousands of computers and allowed us to update pretty easily as well. (Even better, we found, if we installed to a new version to a second directory, tested it, we could swap over by renaming the old directory, then renaming the new directory to the known path. Users still running the old ones continued. New users started using the new ones. We ran it on a two node cluster and it was very reliable. To do that, we also required that the Notes ID file be in a predictable location for the same reason.

But you can imagine a home directory, say root of the mapped F: driver, and a Notes directory, with a file named either username.id (like geoffc.id) or notes.id would be a system you could manage.

So assuming you have those basic requirements set, of file system access to the ID files, what else is needed? Let me summarize then talk through them all.

• Setup the Domino IDM driver with a Remote Loader
  

• Run the service as an account with access

• Set the XML attributes in the modify-password event

• Change the ECV to send old-password nodes

• Enable ID file password changing in Driver Configuration

Setup the Domino IDM driver with a Remote Loader

This step is the generic process of getting the Remote Loader working. That is, install on Windows workstation (Not supported on a Windows server, but it does seem to work) with Client32 or CIFS/SMB access.

Install the IDM Remote Loader, select the proper Java shim for Notes. There are several tricks here. Make sure you install the right bit depth, which should be 64 bit these days, that matches the Notes client. If you are running on the Domino server itself (which per the docs is not supported since you should be running on a workstation not a server, and you should not run Domino on the workstation) then the notes.jar file is there as part of Domino. You need to copy this file into the drivers class path. The Windows path has to include the Domino executable files that the JAR calls out too. Thus the bit depth is critical. So stay 64 bit across the board.

Remember to copy the right version on ndsrep executable. There versions for the supported platforms. Domino 9 is 64 bit only it seems and thus you need the 64 bit version.

Remember to get your Domino admin to sign the dsrepcfg.ntf file so that Domino will use it.

Run the service as an account with access

Run the Remote Loader service as a username and password, local or domain, that has the same values as the user in eDirectory (or AD) that has the file system permissions. That is, the client will try and write to path you provide, as if it were this username. Thus for Client32 make sure the context of the client configuration is properly set to allow just the username in the service configuration to allow them to log in.

Make sure the account has the needed file system permissions. This is different than almost every other driver where you are concerned that the account has directory permissions (Notes, AD, eDir, LDAP, whatever) but here file system matters as well.


Set the XML attributes in the modify-password event

Once the password policy rules are done, you need the event to look something like this.

<nds dtdversion="3.5" ndsversion="8.x">
	<source>
		<product version="3.5.0.20070315 ">DirXML</product>
		<contact>Novell, Inc.</contact>
	</source>
	<input>
		<modify-password allow-adminp-support="true" allow-http-password-set="true" allow-userid-password-set="true" class-name="Person" event-id="subscriber-password-set-1" src-dn="\IDM\US\NYC\idmusers\AHitchcock" src-entry-id="37020" user-id-file="\\acme_srv1\DATA1\ACMEW\USERS\AHitchco\user.id;\\acme_srv1\DATA1\ACMEW\USERS\AHitchco\AHitchcock.id;\\acme_srv1\data1\acmew\users\AHitchcock\user.id;\\acme_srv1\data1\acmew\users\AHitchcock\AHitchcock.id">
			<association>D55452444A3F6E24852578C70054B80A</association>
			<password><!-- content suppressed --></password>
			<old-password><!-- content suppressed --></old-password>
		</modify-password>
	</input>
</nds>

This means that you need to add the XML attributes as needed, after the password policies fire. This is because the event coming out of eDirectory starts as a modify of the attribute nspmDistributionPassword, but the password policies follow the instructions of the password GCV's convert it to a <modify-password> event. This is true of most drivers. You can read more about these policies in these articles I wrote on the topic.

Breaking down the <modify-password> node you can read it more easily as follows:

<modify-password 
	class-name="Person"                              //
	event-id="subscriber-password-set-1"             // These are standard in events
	src-dn="\IDM\US\NYC\idmusers\AHitchcock"         //	
	src-entry-id="37020"                             //
	allow-adminp-support="true" 
	allow-http-password-set="true" 
	allow-userid-password-set="true" 
	user-id-file="\\acme_srv1\DATA1\ACMEW\USERS\AHitchco\user.id;\\acme_srv1\DATA1\ACMEW\USERS\AHitchco\AHitchcock.id;\\acme_srv1\data1\acmew\users\AHitchcock\user.id;\\acme_srv1\data1\acmew\users\AHitchcock\AHitchcock.id">

I am not 100% sure if you need the attribute allow-http-password-set and allow-userid-password-set true here or not, but it did not stop it from working for me, and maybe the driver level setting was all I needed and I implemented some overkill. If someone is trying this and notices it is not needed, please let me know and I will update this.

But the key here is the user-id-file value. Here you can see I specify UNC paths, which happen to be to OES servers, and in fact cluster nodes on an OES 11 cluster. You can see that you can use a semi-colon to separate values. In this case we needed to send in a couple of possible paths, since there were two different naming methods and it was a pain to go back and fix them all to one standard. This way, we try all four possibilities and get three failures and a success.

Speaking of which, here is what a success and a failure should look like. Immediately following the submission of the event the remote loader traces the following:

DirXML: [07/08/11 11:49:42.76]: TRACE:  Notes: NotesSubscriptionShim: Connected to CN=dkdomadmin.dkintl.com/O=Acme Inc
DirXML: [07/08/11 11:49:42.76]: TRACE:  Notes: NotesSubscriptionShim: Connected as CN=IDMUSR SYSTEM/O=Acme Inc
DirXML: [07/08/11 11:49:42.76]: TRACE:  Notes: NotesSubscriptionShim: Reading from names.nsf
DirXML: [07/08/11 11:49:42.76]: TRACE:  Notes: NotesSubscriptionShim:  Input Document contains 1 Identity Manager commands
DirXML: [07/08/11 11:49:42.76]: TRACE:  Notes: processModifyPasswordEvent: changeIDFilePwd: user-id-file: \\acme_srv1\DATA1\ACMEW\USERS\AHitchco\user.id failed: return code=6402 Could not open the ID file.
DirXML: [07/08/11 11:49:42.77]: TRACE:  Notes: processModifyPasswordEvent: changeIDFilePwd: user-id-file: \\acme_srv1\DATA1\ACMEW\USERS\AHitchco\AHitchcock.id succeeded.
DirXML: [07/08/11 11:49:47.76]: TRACE:  Notes: processModifyPasswordEvent: changeIDFilePwd: user-id-file: \\acme_srv1\data1\acmew\users\AHitchcock\user.id failed: return code=6402 Could not open the ID file.
DirXML: [07/08/11 11:49:57.76]: TRACE:  Notes: processModifyPasswordEvent: changeIDFilePwd: user-id-file: \\acme_srv1\data1\acmew\users\AHitchcock\AHitchcock.id failed: return code=6402 Could not open the ID file.
DirXML: [07/08/11 11:49:57.76]: TRACE:  Notes: processModifyPasswordEvent: UNID = D55452444A3F6E24852578C70054B80A
DirXML: [07/08/11 11:49:58.87]: TRACE:  Notes: processModifyPasswordEvent: AdminP changeHTTPPassword for CN=Al Hitchcock/O=Acme Inc request returned: 123DB6
DirXML: [07/08/11 11:49:58.87]: TRACE:  Notes: processModifyPasswordEvent: SUCCESS: AdminP modified HTTP Password for CN=Al Hitchcock/O=Acme Inc (UNID=D55452444A3F6E24852578C70054B80A)

So it tries all four files, 1 works, 3 fail, and it also sets the HTTP Password. The Status event is returned as follows:

DirXML: [07/08/11 11:49:58.87]: TRACE:  Remote Loader: SubscriptionShim.execute() returned:
DirXML: [07/08/11 11:49:58.87]: TRACE:  <nds dtdversion="2.0" ndsversion="8.x">
	<source>
		<product build="20110525_152103" instance="Notes" version="3.5.7">Identity Manager Driver for Lotus Notes</product>
		<contact>Novell, Inc.</contact>
	</source>
	<output>
		<status code="6402" event-id="subscriber-password-set-1" level="error" type="password-set-operation">
			<code>6402</code>
			<description>processModifyPasswordEvent: changeIDFilePwd: user-id-file: \\acme_srv1\DATA1\ACMEW\USERS\AHitchco\user.id failed: return code=6402 Could not open the ID file.</description>
		</status>
		<status code="0" event-id="subscriber-password-set-1" level="success" type="password-set-operation">
			<code>0</code>
			<description>processModifyPasswordEvent: changeIDFilePwd: user-id-file: \\acme_srv1\DATA1\ACMEW\USERS\AHitchco\AHitchcock.id succeeded.</description>
		</status>
		<status code="6402" event-id="subscriber-password-set-1" level="error" type="password-set-operation">
			<code>6402</code>
			<description>processModifyPasswordEvent: changeIDFilePwd: user-id-file: \\acme_srv1\data1\acmew\users\AHitchcock\user.id failed: return code=6402 Could not open the ID file.</description>
		</status>
		<status code="6402" event-id="subscriber-password-set-1" level="error" type="password-set-operation">
			<code>6402</code>
			<description>processModifyPasswordEvent: changeIDFilePwd: user-id-file: \\acme_srv1\data1\acmew\users\AHitchcock\AHitchcock.id failed: return code=6402 Could not open the ID file.</description>
		</status>
		<status event-id="subscriber-password-set-1" level="success" type="password-set-operation">
			<description>processModifyPasswordEvent: HTTPPassword set successfully for CN=Al Hitchcock/O=Acme Inc</description>
		</status>
	</output>
</nds>

Obviously you have to do some similar things during a create of a user, so that the <add> node has the ID file created in the proper place. What we did was have everyone create in one location with a known default password, then as the new user gets their desktop configured and the Notes client configured for them, the tech would copy the file over and get them to do a password change to the current password they just changed as their login password. This gets us started in sync.

If your ID falls out of sync with the IDM password process, intervention is needed. You need to get the password on an ID file to a known state that matches an IDM password, so that changes going forward will work.

Change the ECV to send old-password nodes

This one I knew, but forgot. Enable the ECV dirxml.engine.use-password-event-values setting (Use Password values) to true.

I was getting <modify-password> events and my rules were not firing. I looked at my rule, and I was watching for an <old-password> node or a <remove-value> on the password event. That is, the old password being sent. Well it turns out this is not a default in IDM drivers. It is actually set in an Engine Control Value. I find that Designer has issues with setting this properly. Part of the issue seems to be that the engine adds in new ECV's when available (say when IDM is updated and a new ECV is added) and then when you compare, Designer has a different value. Then sometimes a Designer update seems to decide that the wording of some of these are different and changes them. Very annoying.

Anyway, remember these are per-replica attributes, which means that the version on Server1 can be different from Server2. They do not replicate. What I would recommend is doing it in Designer, then double check in iManager and finally, if needed fix it in iManager. (My concern is that on a future deploy you could write back a bad value).

The difference between the two events would be shown in how the <modify-attr attr-name="nspmDistributionPassword"> looks like. Alas, because the flag is-senstive is set to true, you cannot see the nodes. But they would look like:

	<modify-attr attr-name="nspmDistributionPassword">
		<remove-value>
			<value>OldPassword</value>
		</remove-value>
		<add-value>
			<value>New Password</value>
		</add-value>
	</modify-attr>	

But because it is protected you cannot see it. (Try Strip by XPATH expression modify-attr[@attr-name="nspmDistributionPassword"]/@is-sensitive and then you can see what is going on.)

This will get converted by the password policies to look like:

<nds dtdversion="3.5" ndsversion="8.x">
	<source>
		<product version="3.5.0.20070315 ">DirXML</product>
		<contact>Novell, Inc.</contact>
	</source>
	<input>
		<modify-password src-dn="\IDM\US\idmusers\AHitchcock" src-entry-id="37020">
			<association>D55452444A3F6E24852578C70054B80A</association>
			<password><!-- content suppressed --></password>
			<old-password><!-- content suppressed --></old-password>
		</modify-password>
	</input>
</nds>

This of course is critical as discussed in the beginning, you need the old password to decrypt the private key, and the new password to reencrypt it again as the ID file.


Enable ID file password changing in Driver Configuration

This looks in the remote loader (and engine trace) as part of the init-params event as the driver starts up. (I trimmed this example for size, there are lots more settings).

<init-params>
	<subscriber-options>
		<allow-http-password-set display-name="Allow HTTP password to be set">true</allow-http-password-set>
		<allow-userid-password-set display-name="Allow Notes ID password to be set">true</allow-userid-password-set>
	</subscriber-options>
</init-params>

In the driver configuration, there are allow-http-password-set and allow-userid-password-set controls. Make to sure to enable them both, or as you desire.

Beyond basic setting up Domino driver stuff that is pretty much all you need to do to get the ID file changing.