26.8 Lotus Notes

26.8.1 Overview

26.8.1.1 Two different passwords

Lotus Notes passwords may actually be one of two separate system types:

• Passwords stored on a Notes / Domino server. These are a straight-forward password hash in a field in an .NSF file on the server. P-Synch can be configured to verify, change and reset these passwords directly. See Section HERE to learn how to manage these passwords.

• Passwords used by users to decrypt their personal Notes ID files. These are much more difficult to manage, as detailed below.

ID files are containers of private and public encryption keys. The ID file itself is encrypted using the user's password. Users authenticate to a Notes server, and the databases it houses, using certificates found in their ID file. Users have access to their own private and public keys, while servers only know a given user's public key. Lotus Notes is therefore the first large, successful Public Key Infrastructure (PKI) system.

26.8.1.2 Managing ID file passwords

Notes ID files present these managment problems:

• By their nature, you cannot reset ID file passwords.

  You must know the current password to decrypt the file, and then you may re-encrypt the file using a new password. This is a password change (user operation), not a password reset (administrative operation).

• ID files are often stored on the desktop (c:\notes\data), or even on floppy disks. A server can't normally access them.

• Notes 4.x (every version prior to 5.0) has no API for changing ID file passwords. You must use the Notes GUI, interactively to change ID file passwords.

26.8.1.3 Simulating password resets for ID files

Organizations can solve these problems by storing Notes ID files in a master repository (normally a Lotus Notes NSF database) , along with their original passwords. While users may change the password on their own copy of their ID file, the copy of their ID file in the repository remains unchanged.

To simulate a password reset, P-Synch extracts a (possibly old) copy of the user's ID file from the repository, changes its password, and delivers the new, replacement ID file to the user. Most organizations already implement ``password resets'' for Lotus Notes using this technique, since the alternative solution for users who forget their password is to issue an entirely new ID file to the user.

26.8.1.4 Managing Notes ID file passwords with P-Synch

P-Synch can be used to simulate Notes ID file passwords in the same way that organizations do prior to its deployment:

1. Connecting to the NSF repository that houses user login IDs, initial passwords, and archived ID files.

2. Looking up the user's record, and extracting the user's archived ID file and matching password.

3. Using the Notes 5 API, which is available as a part of the Notes 5 client installed on the P-Synch server, P-Synch opens its copy of the ID file with the initial password, and changes the password on the ID file to a new value.

4. Executing a batch file which is responsible for delivering the new ID file to the user. A batch file is used since different organizations will use different techniques to deliver the ID file to the user:
   • If Notes is used for e-mail, then the new ID file can be mailed to the user as a message attachment.
   • If user workstations are standardized with a common share and login ID/password, then the batch file can connect to the user's workstation directly, and install the new ID file.
   • If users access their ID files on a network share - such as their home directory - then the batch file can install the ID file on that directory.
   • The batch file may store the ID file in a common location, such as a file share or on the P-Synch server itself (to be accessed later by HTTPS). A separate utility can be used as a part of the user's network login script to update the ID file on his workstation from this common location.

This process is illustrated in FIGURE: [NID_ARCH_RESET_1]:

1. The user accesses P-Synch through a web browser.
2. The web browser runs the NID password agent.
3. The password agent retrieves the user's old ID file, with a matching password, from an NSF database (the ID file repository).
4. The NID agent changes the password on the ID file it retrieved, and invokes a batch file to deliver the new ID file to the user.
5. The user logs into Notes using the new ID file.

Figure:Simulating Lotus Notes ID file password resets

Caution:

Any changes made to a user's ID file after it was stored in the repository and before a password reset will be lost in this process. This is true for Lotus Notes ID file password resets made without P-Synch. Because of this, we do not recommend this facility be used for routine password synchronization.

 

26.8.1.5 Constructing a Notes ID file password repository

26.8.1.5.1 User self-service

P-Synch can also be used to construct an ID file password repository. Once a repository has been installed, the process is as illustrated in FIGURE: [NID_ARCH_POP_1]:

1. The user accesses the P-Synch alternate login ID profile builder (nph-psl.exe) using a web browser. After the initial authentication, the user types his login ID and the current password for his ID file.
2. The P-Synch CGI program (nph-psl.exe) runs the Notes ID file agent, asking it to verify the ID (filename) and password.
3. The NID agent invokes a batch file to retrieve a copy of the user's ID file from his home directory, and verifies that the password provided by the user was correct.
4. If the password was correct, the NID agent stores a copy of the ID file, along with the verified password, in the ID file reposistory / NSF database.

Figure:Populating the Notes ID file NSF database

26.8.1.5.2 Administrative or batch load

The addnid program (See Section HERE) can be used to add individual ID files and passwords to the repository. Used in a batch file, it can be used to load large numbers of ID files and passwords into the repository.

For example, if an administrator has a copy of a user's current ID file, and knows the user's login ID on other systems as well as the user's current ID file password, he can type (on a P-Synch server command prompt, in a single line):

addnid
-s NID-target-address
-userid user-ID
-userp password
-idfile path$\cdots$file.id

For example, he might type (on a single long line):

addnid
  -s dom1.acme.com:psidfile.nsf:mainform:shortname:?password:$FILE:Userid:idgetput.cmd
  -userid joeuser
  -userp joepass1
  -idfile c:\notes\data\joeuser.id

Alternately, you can specify a directory with P-Synch database files, and use -s to give the NID system's target ID, rather than a full address:

addnid
  -c "c:\program files\p-synch\cgi-bin"
  -s notesids
  -userid joeuser
  -userp joepass1
  -idfile c:\notes\data\joeuser.id

26.8.1.6 Installation process

To install and configure a Lotus Notes ID file target system on P-Synch:

1. Install and configure the Lotus Notes R5 client. See Sub-section HERE.

2. Create an ID file repository. See Sub-section HERE.

3. Add the Lotus Notes client to P-Synch. See Sub-section HERE.

4. Configure P-Synch batch files. See Sub-section HERE.

5. Create or modify network login scripts. See Sub-section HERE.

6. Test the password reset procedure. See Sub-section HERE.

26.8.2 Pre-installation

Before you begin, you must:

1. Know the name of each Lotus Notes server on which P-Synch will manage HTTP passwords.

2. Install the Lotus Notes R5 client on the P-Synch server.

3. On the P-Synch server, update the system PATH to include the directory in which you installed Lotus Notes R5.
4. If you run IIS, reboot the P-Synch server to ensure that the new path information is loaded. If you're running Apache, you only need to restart the service.

5. Create an administrative account for each name and address book on each server where P-Synch will manage passwords:
   1. Register a user in the Lotus Notes server using Lotus Notes Administrator.

   2. Install this user's ID file on the P-Synch server.

   3. On the P-Synch server, choose File $>$ Tools $>$ Switch ID to set the new ID as the default user on the Lotus Notes client.

   4. Copy the files GETPASS.DLL and PSYNCHPWD.DLL from the c:\Program Files\P-Synch\utils directory into the same directory that contains the NNOTES.DLL file (The default location is c:\lotus\notes).

   5. Edit the NOTES.INI file in that same directory. At the end of the file add this line followed by a blank line:
      EXTMGR_ADDINS=psynchpwd.dll

   6. Close (if already open) the Lotus Notes client, and start it again so it re-loads the latest NOTES.INI file.
      

      Note:

      It is not necessary to have the Lotus Notes client running to have P-Synch manage passwords on it.

      
       

   If P-Synch will manage passwords on multiple repositories, or will also manage Lotus Domino / HTTP passwords (Section HERE), then the same ID file must have rights for each repository and each Domino name and address book.

Note:

Ensure that the Lotus Notes client is not used by human users on the P-Synch server and that the last user to have logged in was the administrative account. Never log into Lotus Notes from the P-Synch server using any login ID other than the one which will be used by P-Synch to manage passwords on Lotus Notes / Domino servers.

 

26.8.3 Creating an ID file repository

To set up the ID file repository on the Lotus Notes client:

1. Copy the Lotus Notes database PSIDFILE.NSF from the P-Synch SAMPLES directory to the Lotus Notes server. Alternately, you can use an existing NSF database or create your own.

   The ID file repository must have at least the following three fields:

   • Login ID (shortname).
   • Latest password (plaintext or encrypted by P-Synch).
   • Latest ID file (as an attachment - this is a rich text field).

2. Grant the administrative account (that you set up in Sub-section HERE) read access to the repository .NSF database.
   1. Open the server directory and select the Files tab.
   2. Right click on the repository .NSF database and select Access Control, Manage.
   3. Add the new user to the Access Control List, and grant the user the right to read from the database.
   4. If P-Synch will be used to update the repository, also give this user the rights to add, edit and delete records in this database.

26.8.4 Adding the Lotus Notes ID file target to P-Synch

Follow the procedure in Section HERE to add an entry to the P-Synch host database with the following field values:

1. Select Notes ID files as the Target type.

2. Type the Target address to the server's address. The address is composed of a sequence of sub-fields, separated from one another by a colon (:) character. The sub-fields are listed in TABLE: [NID-FIELDS].

   For example:

   domino1.acme.com:psidfile.nsf:MainForm:ShortName:?Password:$FILE:Userid:nidgetput.cmd

3. Leave the administrative login ID and password blank. P-Synch will use the default ID file for the Lotus Notes R5 client on the P-Synch server, which has no password and is able to reset passwords on every Lotus Notes / Domino name and address book.

Name	Description	Example
Server	The DNS name of the Notes / Domino server where the ID file repository is housed.	domino1.acme.com
Database	The name of the ID file repository NSF database.	psidfile.nsf
Form	The name of the form in the repository that contains user login IDs, ID files and passwords.	MainForm
Short name column	The name of the column in the above form that contains each user's short name (login ID).	ShortName
Password column	The name of the column in the above form that contains each user's password for the stored ID file. This name may begin with a ? (question mark), in which case the passwords are encrypted by P-Synch, but the ? character is not a part of the column name.	?Password
Attachment column	The name of the column where the user's ID file is stored.	$FILE
Attachment name	The name of the attachment inside the attachment column. (an attachment column can house multiple files or attachments per record).	Userid
Batch file name	The name of a batch file in the <instance name>\bin directory that the P-Synch Notes ID file agent will use to retrieve a user's current ID file from his PC or network home directory; or store a new ID file, after a password reset. This batch file should take no more than 2 minutes to execute, and should output the following text only if there is an error condition: ``incorrect'', ``error'', ``cannot'', ``could not'', and ``fail''.	nidgetput.cmd

26.8.5 Configure P-Synch batch files

Write the batch file to match your local business process, and copy it into the <instance name>\bin directory. The batch file will be invoked by P-Synch with three arguments:

• %1 The word GET or PUT. GET means that P-Synch needs to retrieve an ID file from the user (e.g., to help construct the repository), and PUT means that P-Synch needs to deliver a new ID file to the user.
• %2 The user's network login ID (short name).
• %3 The file path and name where the ID file was put by P-Synch, and from which the batch file should copy the ID file to deliver to the user.

The following is an example of a batch file that P-Synch will run to publish ID files to a local website on the P-Synch server:

   @echo off

   rem Assume that users keep their ID files on a home directory..

   net use \\bigserver.acme.com\home /user:psadmin mypassword
   
   if /I %1==GET  (
     copy /Y "\\bigserver.acme.com\home\%2\%2.id" "%3"
     ) else (
     if /I %1==PUT (
       copy /Y "%3" "\\bigserver.acme.com\home\%2\%2.id"
       ) else (
          echo "Action must be GET or PUT."
       )
     )
   NET USE \\bigserver.acme.com\home /delete /yes

In the example, P-Synch retrieves ID files from the user's home directory when it updates the repository (e.g., using the alternate login ID profile builder), and installs new ID files in the user's home directory after extracting them from the repository and changing their password.

26.8.6 Creating or modifying network login scripts

26.8.6.1 Retrieving new ID files from a web server

Users can automatically receive new ID files from the P-Synch web server by adding the urlget command to their network login scripts, as follows:^26.1

  \\password\public\urlget
     -user %USERNAME%
     -url http://password/idfiles/%u.id
     -file c:\notes\data\%u.id

26.8.6.2 Retrieving new ID files from a home directory

The tcopy command can be used to synchronize a user's ID file on his PC with his ID file on a network home directory. If one of the files changes (e.g., due to a local or P-Synch password change), the other can be automatically updated. tcopy is normally invoked from the user's network login script, as follows:

   rem Replace \\psynch.acme.com\share\tcopy.exe with a suitable path
   rem to the tcopy.exe file.

   rem The following command should be made as a single line:

   \\psynch.acme.com\share\tcopy.exe
      "C:\notes\data\%USERNAME%.id" "H:\%USERNAME%.id"
  

26.8.7 Testing

Do the following to test your configuration:

• Before testing, ensure that:
  • The Lotus Notes client is not open on the P-Synch server and that the last user who did log into the Lotus Notes R5 client on the P-Synch server was on the administrative account.

  • You run the psupdate.cmd batch file before testing, to associate accounts with the new server.

• Use P-Synch's help desk program to reset the test user's password. See Section HERE.

• Verify that the new ID file appears in the expected location (which will vary depending on your batch file).

• If you use tcopy, verify that the network login script works with the changes you make, and automatically download/upload a new ID file from the network when one is created.

26.8.8 Troubleshooting

The following table lists possible P-Synch error messages and suggests resolution for each one:

Table:Troubleshooting a Lotus Notes ID files configuration test

For this message...	Do this...
Unable to find path to server	Ensure that: The server's address, and in particular the server name which is the first part of the address, is correct. The server is up: try logging into it with the administrative ID you created, using the Notes client installed on the P-Synch server.
No such user	Ensure that the user has an entry in the ID file repository.
Invalid server format	Ensure that the address for the Notes ID file repository's server is correctly formatted. See Sub-section HERE.
No such attachment	Create an ID file for the user in question. This error message means that no ID file exists, although the user does appear in the repository.
Wrong password	Ensure that the password associated with the ID file in the database matches the password (also in the database) used to encrypt the ID file.