IBM Tivoli Directory Integrator
The Domino HTTP Password Synchronizer can be deployed
in the following modes:
- Both administrative password resets and normal user password changes
are intercepted.
- Only normal user password changes are intercepted.
- Only administrative password resets are intercepted.
For deployment and configuration of the Domino HTTP
Password Synchronizer see the following sections.
To install the Domino HTTP Password Synchronizer
on Domino, run the installer on the machine where
the Domino Server is installed. The installer places
all required files in the appropriate directory structures.
The file paths of Domino Server directories are as follows:
- The Domino Server Program Folder is referred to as domino_program_directory (for example, C:\Program
Files\IBM\Lotus\Domino on Windows, /opt/ibm/lotus on Linux and
UNIX-based platforms).
- The Domino Server Data Folder is referred to as domino_data_directory (for example, C:\Program
Files\IBM\Lotus\Domino\Data on Windows, /local/notesdata on Linux and
UNIX-based platforms).
- The Domino Server JVM Folder is referred to as domino_jvm_directory (for example, C:\Program
Files\IBM\Lotus\Domino\jvm on Windows, /opt/ibm/lotus/notes/80000/linux/jvm on Linux and
UNIX-based platforms).
Setup of the Domino plug-in
Do the following to set up the Domino plug-in:
- Restart the Domino Server.
- Sign pwsync_install_r8.nsf and idipwsync.nsf with Server ID:
- Start Lotus Domino Administrator.
- Select Files.
- Right-click on the pwsync_install_r8 database
and select Sign.
- In Sign Database, under Which ID do we want to use?, select Active Server's ID.
- Right-click on the idipwsync database
and select Sign.
- In Sign Database, under Which ID do we want to use?, select Active Server's ID.
- Click OK.
- Update the design of the pubnames.ntf template:
- Start Lotus Domino Designer.
- Open the following items:
- Open pwsync_install_r8.nsf database.
- Open pubnames.ntf template.
- Copy Agents:
- In pwsync_install_r8.nsf, select Code/Agents.
- Select both IDIPWSyncClientAgent and IDIPWSyncWebAgent (press the Ctrl key
while clicking the two agents).
- Right-click on the selected agents and select Copy.
- In pubnames.ntf, select Code/Agents.
- Select Edit -> Paste to
paste the two agents.
If the Person form has not been modified with user-customized
logic, the Person form from the Password Synchronizer is used.
- Rename the Person form in pubnames.ntf:
- In pubnames.ntf select Forms.
- Open the Person form.
- Select Design -> Form Properties.
- Edit the Name field. Change the name to original_Person (or other name of the choice, other
than Person).
Make sure the
default alias Person is also unset from that field.
- Save the form.
- Close the form.
- Copy the Person form:
- In pwsync_install_r8.nsf select Forms.
- Right-click on the Person form and select Copy.
- In pubnames.ntf select Forms.
- Select Edit -> Paste to
paste the form.
If the Person form has been modified with user-customized
logic that needs to be kept, Password Synchronizer source code for
the Person form must be copied manually.
- Copy the Person form source code:
- Copy WebQuerySave event code:
- In pwsync_install_r8.nsf, select Forms.
- Open the Person form.
- Select the WebQuerySave event.
- Copy the lines starting with REM {start of IDI Password Synchronizer
code}; and ending with REM {end of IDI Password Synchronizer
code};
- In pubnames.ntf select Forms.
- Open the Person form.
- Select the WebQuerySave event.
- Paste the copied source code. Make sure the pasted code appears
before any other code in this event.
- Save the form.
- Copy QuerySave event code:
- In pwsync_install_r8.nsf, select Forms.
- Open the Person form.
- Select the QuerySave event.
- Copy the lines starting with 'start of Password Synchronizer
code and ending with 'end of Password Synchronizer code.
- In pubnames.ntf, select Forms.
- Open the Person form.
- Select the QuerySave event.
- Paste the copied source code. Make sure the pasted code appears
just before the end of the Querysave procedure.
- Save the form.
- Copy SyncPass event code:
- In pwsync_install_r8.nsf, select Forms.
- Open the Person form.
- Select the SyncPass event.
- Copy all code for the SyncPass function.
- In pubnames.ntf, select Forms.
- Open the Person form.
- Select the QuerySave event.
- Paste the copied source code. Make sure the pasted code appears
after all code in the event. A new event named SyncPass is
created immediately, and the pasted code is transferred there.
- Save the form.
If the $PersonInheritableSchema subform
has not been modified with user-customized logic, the $PersonInheritableSchema from
the Password Synchronizer is used.
- Rename the $PersonInheritableSchema subform
in pubnames.ntf:
- In pubnames.ntf, select Shared
Elements/Subforms.
- Open the $PersonInheritableSchema subform.
- Select Design -> Subform Properties.
- Edit the Name field. Change the name to original_$PersonInheritableSchema (or other name
of the choice other than $PersonInheritableSchema).
- Save the form.
- Close the form.
- Copy the $PersonInheritableSchema subform:
- In pwsync_install_r8.nsf, select Shared
Elements/Subforms.
- Right-click on the $PersonInheritableSchema form
and select Copy.
- In pubnames.ntf, select Shared
Elements/Subforms.
- Select Edit ->Paste to paste
the subform. If the $PersonInheriableSchema subform
has been modified with user-customized logic that needs to be kept, the Password Synchronizer source code must be copied manually.
If the $PersonInheritableSchema subform
has been modified with user-customized logic that needs to be kept, Password Synchronizer source code is copied manually.
- Copy the $PersonInheritableSchema subform code:
- Copy HTTPPassword field code:
- In pwsync_install_r8.nsf, select Shared
Elements/Subforms.
- Open the $PersonInheritableSchema subform.
- Select the HTTPPassword field (near the
bottom of the form).
- Select the Input Translation event.
- Copy the lines starting with REM {start of IDI Password Synchronizer
code}; and ending with REM {end of IDI Password Synchronizer
code};
- In pubnames.ntf, select Shared
Elements/Subforms.
- Open the $PersonInheritableSchema form.
- Select the HTTPPassword field.
- Select the Input Translation event.
- Paste the copied source code. Make sure the pasted code appears
before any other code in this event.
- Save the form.
- Copy Enter Password button code:
- In pwsync_install_r8.nsf, select Shared
Elements/Subforms.
- Open the $PersonInheritableSchema subform.
- Select the Enter Password button (near the bottom of the form).
- Select the Click event and make sure the Run field is set to "client".
- Copy the lines starting with REM {start of IDI Password Synchronizer
code}; and ending with REM {end of IDI Password Synchronizer
code};
- In pubnames.ntf, select Shared Code/Subforms.
- Open the $PersonInheritableSchema form.
- Select the Enter Password button.
- Select the Click event. Again the Run field on the right hand
side should be set to "client".
- Paste the copied source code. Make sure the pasted code appears
after the piece of code where the received password (tmpPassword)
gets verified and before the code that refreshes all the document
fields (@Command([ViewRefreshFields]);)
- Save the form.
- Copy FullName field code:
- In pwsync_install_r8.nsf, select Shared
Elements/Subforms.
- Open the $PersonInheritableSchema subform.
- Select the FullName field (near the bottom
of the form).
- Select the Input Validation event.
- Copy the lines starting with REM {start of IDI Password Synchronizer
code}; and ending with REM {end of IDI Password Synchronizer
code};
- In pubnames.ntf, select Shared Elements/Subforms.
- Open the $PersonInheritableSchema form.
- Select the FullName field.
- Select the Input Validation event.
- Paste the copied source code before any other code in this event.
- Save the form.
- Update the design of the admin4.ntf template:
- In Lotus Domino Designer open
the admin4.ntf template database and pwsync_install_r8.nsf database.
- Copy the IDIPWSyncAdminRequestAgent:
- In pwsync_install_r8.nsf, select Shared
Code/Agents.
- Select the IDIPWSyncAdminRequestAgent.
- Right-click on the selected agent and select Copy.
- In admin4.ntf select Shared Code/Agents.
- Select Edit -> Paste to
paste the agent.
- Configure the IDIPWSyncAdminRequestAgent:
- Open the IDIPWSyncAdminRequestAgent.
- Select Edit -> Properties.
- Click Edit settings from the Runtime section
of the Agent dialog box.
- In the Run on field select the name of the
current Domino server.
- Click OK.
- Close the agent dialog box.
- Select File -> Save to save
the new agent settings. You may get a warning message like "You
do not have execution access privileges for agent 'IDIPWSyncAdminRequestAgent'
on 'TDITest/IBM'; it will not run". The meaning of this message
is that the Domino account that we use currently in the Domino Designer
cannot "sign or run unrestricted methods and operations" on the Domino
server. This is perfectly normal and it is why we will be instructed
to sign the agents with a dedicated signer in the following steps.
- Sign the agents with a signer that can "sign or run unrestricted
methods and operations":
- Find the signer that is listed in the Sign
or run unrestricted methods and operations field on the Security
page of the Server document (to access the Server document, open the
Domino Administrator, select Configuration and in the left navigation
panel select Server/Current Server Document). If there are no existing
accounts with this privilege, you may need to add a new one (there
are sample steps to create a signer account in section Creating a signer for the Password Synchronizer agents. Beware that the privilege to "Sign or run
unrestricted methods and operations" should be given only to the most
trusted accounts. The signer that us choose must have Manager access
to the pubnames.ntf and admin4.ntf templates, so that it can sign
agents in them.
- Open the Domino Designer.
- Switch to the ID of the signer from step i. (File -> Security -> Switch ID...)
- Open the pubnames.ntf template.
- Select Code/Agents and open the list of all agents (at the top
of the agents window we should see buttons New
Agent, Enable, Disable, Sign)
- From the list of agents select IDIPWSyncClientAgent.
- Press the Sign button. (This will
cause Domino Designer to sign the agent with the current ID.)
- From the list of agents select IDIPWSyncWebAgent.
- Press the Sign button.
- Open the admin4.ntf template.
- Select Code/Agents and open the list of all agents.
- From the list of agents select the IDIPWSyncAdminAgent.
- Press the Sign button.
- Switch to the ID that you were using previously (File -> Security -> Switch ID...).
- Refresh the design of the names.nsf database:
- In Lotus Domino Administrator, select Files.
- Select names.nsf database.
- Go to File -> Application -> Refresh Design.
- select the name of the server from the With
Design from Server list.
- Click OK.
- Click Yes to continue.
- Refresh the design of the admin4.nsf database:
- In Lotus Domino Administrator select Files.
- Select admin4.nsf database.
- Select File -> Application ->
Refresh Design.
- Select the name of the server from the With
Design from Server list.
- Click OK.
- Click Yes to proceed.
- Setup secret key encryption infrastructure.
Secret key encryption
is used to protect passwords in the time slice in which they are temporarily
stored in a database on the Domino Server.
- Generate a secret key:
- In Lotus Domino Administrator, select File -> Security -> User Security.
- Select Notes Data/Documents from
the left navigation panel.
- Click New Secret Key.
- Enter IdiPwSync as secret key name and click OK.
- Click Other Actions and select Export
secret key.
- Enter a password to protect the exported secret key.
This step is optional but highly recommended.
- Save the key in a file named idipwsync.key.
- Click Close in the User
Security screen.
- Import the secret key in the Domino Server
ID file:
- Stop the Domino Server.
- In Lotus Domino Administrator, select File -> Security -> Switch ID.
- Open the server.id file for the Domino Server.
To do so use either a Lotus Domino Administrator
installed on the Domino Server machine, or copy the server.id file
to the machine where Lotus Domino Administrator
is installed. The server.id file is usually placed in domino_data_directory.
- Select File -> Security ->
User Security.
- Select Notes Data/Documents from
the left navigation panel.
- Click Other Actions and select Import
secret key.
- Open the idipwsync.key file.
- If the file is password protected, enter the password that was
created when you exported the secret key (see "Enter
a password to protect the exported secret key," previous).
- Click Accept to import the secret key.
- Click Close in the User
Security screen.
- Select File -> Security ->
Switch ID and switch back to the administrator ID file.
- If you edited a copy of the server.id file, copy it
over the original server.id file in domino_data_directory (you may want to backup
the original server.id before overwriting it with the new
one).
- Start the Domino Server.
- Import the secret key in the ID files of all Administrators or
users that can edit Person documents and change http passwords. For
each of these Administrators or users, do the following steps:
- In Lotus Domino Administrator, select File -> Security -> Switch ID.
- Open the ID file of the Administrator or user.
- Select File -> Security ->
User Security.
- Select Notes Data/Documents from
the left navigation panel.
- Click Other Actions and select Import
secret key.
- Open the idipwsync.key file.
- If the file is password protected, enter the password that was
created when you exported the secret key (see the steps for generating
a secret key in step 8a above).
- Click Accept to import the secret key.
- Click Close in the User
Security screen.
An Administrator or user whose
ID file does not contain the secret encryption key is not allowed
to change the HTTP Password field of Person documents.
- Setup port encryption (optional).
Port encryption encrypts the
communication between Lotus Domino Administrator
and the Domino Server, bringing an additional layer of
security to the network communication.
Port encryption
is recommended but not required. Prior to being sent over the network, the password is encrypted with the secret key, regardless of whether
port encryption is used or not.
Two options
are available:
- Setup the Domino Server to encrypt communication
ports. This is easier to set up (the Server settings only are configured)
but it affects the communication with all clients, including regular
users using Lotus Notes clients.
- Setup the Lotus Domino Administrator
clients to encrypt communication ports. This requires configuration
of each Lotus Domino Administrator client that is
used, but does not affect other Notes clients
if encryption is not necessary for them. Do this as follows:
- Encrypt Domino Server communication ports:
- In Lotus Domino Administrator select Configuration.
- Select Server/Server Ports from the right-side
panel.
- For each communication port in use, select the port in the Communication ports list and check the Encrypt
network data option.
- Click OK.
- Restart the Domino Server for changes to take
effect.
- Encrypt Lotus Domino Administrator communication
ports:
Do the following for each Lotus Domino Administrator
client that is to be used for password changes:
- In Lotus Domino Administrator select File -> Preferences ->-User
Preference.
- Select Ports from the left navigation panel.
- For each communication port in use, select the port in the Communication ports list and check the Encrypt
network data option.
- Click OK.
- Restart Lotus Domino Administrator for changes to
take effect.
- Setup SSL for Domino HTTP Server.
SSL is necessary
to secure the communication between the Web browser and the Domino HTTP
Server. If SSL is not set up, the password is transferred over the
network in plain text.
Consult the Lotus Domino Administrator
help documentation for more information about setting up SSL ("Setting
up SSL on a Domino server" is a recommended article).
- Configure the Domino Server
to automatically start and stop the Proxy Process:
Open the file domino_program_directory/notes.ini and
find the ServerTasks property. Add the following
value at the end of the ServerTasks property:
runjava com.ibm.di.plugin.domino.ProxyLoader
The
following is a sample ServerTasks property in notes.ini:
ServerTasks=Update,Replica,Router,AMgr,AdminP,CalConn,Sched,HTTP,runjava com.ibm.di.plugin.pwsync.domino.ProxyLoader
- Configure the Execution control list of Lotus Domino Administrator
clients:
Do the following for each Lotus Domino Administrator
client that is to be used for password changes:
- In Lotus Domino Administrator select File -> Security -> User Security.
- Select What Others Do/Using Workstation in
the left navigation panel.
- In the When code is signed by list, select
the name of the Domino Server, for example serverName/certifierName. If the name of the Domino Server
is missing, add it to this list.
- Under Allow access to:, check the current database option.
- Under Allow ability to:, check the read other databases and Modify
other databases options.
- Click OK.
- Configure Access Control:
- Create IDIPWSync group
in the Domino Directory:
- In Lotus Domino Administrator, select People & Groups.
- In the left navigation panel, select Domino Directories/your_domain's Directory/Groups where the_domain is the name of the Lotus Domino domain.
- Click Add Group.
- Type IDIPWSync in Group
name.
- In the Members field add all Administrators
or users that can change passwords by editing Person documents.
- In the Members field add
the signer that we used to sign the agents of the Password Synchronizer.
- Update Access Control List of the idipwsync.nsf database:
- In Lotus Domino Administrator, select Files.
- Select the idipwsync.nsf database.
- Select Database/Manage ACL from the right-side
panel.
- Click Add and select the IDIPWSync group.
- Set Access to Editor.
- Set the following options under Attributes:
- Check the Delete Documents option. The options Create Documents, Read Public Documents, and Write Public Documents must be checked as
well. This is done automatically when Editor access
is selected.
- Uncheck the options Create private agents, Create personal folders/views, Create
shared folders/views, Create LotusScript/Java
agents, Replicate or copy
documents.
- Select Default from the Access
Control List.
- Set Access to No Access.
- Click OK.
After the idipwsync.nsf database
ACL is changed, it is no longer possible to change this ACL from the Domino Server.
For security reasons, the most restrictive settings are used. If a
new change of the ACL is necessary, the database must be opened locally
and its ACL changed as needed.
- Delete the pwsync_install_r8.nsf database. After the
installation is complete, delete the pwsync_install_r8.nsf database
from the Domino server:
- In Lotus Domino Administrator, select Files.
- Right-click on the pwsync_install_r8 database and select Delete Database.
- Click OK in the Confirm
Database Delete screen.
Notes:
- The Domino HTTP Password Synchronizer ships with a template configuration
file (TDI_install_dir/pws_plugins/domino/pwsync.props)
that has all the required properties preset by default to enable out-of-the-box
usage.
- The default Password Store that is configured in the shipped pwsync.props file is the Log Password Store. This Password Store
will log all the captured passwords in the proxy's log file.
This password store should be used for diagnostic purposes only! Please
refer to the individual Password Stores for more information on configuring
them.
The table below explains the aforementioned steps in somewhat more
detail:
Table 5. Explanation of customization steps
Step
| Description
|
1
| Make sure that the Domino Server has read the
new files, which have been copied during the post-install phase.
|
2
| The external databases shipped with TDI need
to be signed by the Domino server in order it to be able to vouch
for their integrity.
|
3
| By editing the pubnames.ntf template
we change the behavior of the names.nsf database.
A code is placed on several key places in order for the plain password
to be intercepted. Once the password is captured it is passed to the
responsible Java Agent (IDIPWSyncClientAgent or IDIPWSyncWebAgent).
|
4
| By editing the admin4.ntf template we change
the behavior of the admin4.nsf database.
The copied Java Agent (IDIPWSyncAdminRequestAgent) is responsible
for periodically processing the Administration Requests, posted by
the various users when they change their passwords.
|
5
| Agents execute with the rights of their signer.
The agents of the Password Synchronizer need to perform restricted
operations (network access, file system access), so they need to be
signed by someone who can "sign or run unrestricted methods and operations".
|
6
| Refreshing the design of the names.nsf applies the changed template to
the existing database.
|
7
| Refreshing the design of the admin4.nsf applies the changed template to
the existing database.
|
8
| The various Java Agents use the database idipwsync.nsf to store documents which need
further processing. In order to protect the documents in this database
they need to be encrypted. The secret key created in this step is
used in the database encryption process.
|
9
| Port encryption encrypts the communication between
Lotus Domino Administrator and the Domino Server, bringing an additional
layer of security to the network communication.
|
10
| SSL is necessary to secure the communication
between the Web browser and the Domino HTTP Server. If SSL is not
set up, the password is transferred over the network in plain text.
|
11
| The Java Proxy is executed in the JVM shipped
with Domino. It is started as a Server Task when the Domino Server
is starting.
|
12
| Configure each Lotus Domino Administrator client
to enable Administrative password changing.
|
13
| The IDIPWSync group contains a list of the users
which have the rights to change other users' passwords. Usually
only the Administrators should present in this group. Regular user
will still be able to change their passwords through iNotes even if
they don't belong to this group.
Members of this group
are the only ones that can access the idipwsync.nsf database.
The idipwsync.nsf database is used to
transfer data between Lotus script and the Password Synchronizer agents.
The signer of the Password Synchronizer agents must also be added
in the IDIPWSync group, so that the agents will have access to idipwsync.nsf (agents execute with the rights
of their signer).
|
14
| The pwsync_install_r8.nsf database
is only used for distributing the required template objects. Once
the Domino HTTP Plugin is properly setup the database is no longer
required and can be safely deleted.
|
In environments with multiple Domino Servers
the Password Synchronizer is installed on each Domino Server
which is a Primary Domino Directory Server in the Domino Domain.
The Password Synchronizer is not installed on Domino Servers
which are Configuration Only Directory Servers.
The installation on the Primary Domino Directory Servers is performed as follows:
- On the Primary Domino Directory Server that is the
Administration Server for the Domino Directory, perform full installation of the password synchronizer as described
in the previous section, Deployment on a single Domino Server.
- For all the other Primary Domino Directory Servers, do the following steps:
- Run the Password Synchronizer installer to install the necessary
files.
- Force replication with the first Primary Domino Directory Server where a full setup is performed:
- In Lotus Domino Administrator select Server.
- Select Status.
- In the right-hand panel, select Server/Replicate .
- In the Which server do we want to replicate
with? field, enter the name of the first Primary Domino Directory Server where a full setup is performed.
- Click Replicate.
- Click Done.
- This step and all following setup instructions refer to the setup
steps from the section Deployment on a single Domino Server:
Skip steps 1, 2, 3 and 6. Domino Directory replication propagates the design
updates from the first Primary Domino Directory Server where a full setup is performed.
- Skip steps 4 and 7. The IDIPWSyncAdminRequestAgent is
triggered only on the Administration Server for the Domino Directory.
- Perform step 8, but skip step 8a. (creation
of a secret key). Use the secret key created when setting up the Password
Synchronizer on the first Primary Domino Directory Server.
- Perform steps 9, 10, and 11.
- Skip step 12.
- Perform step 13, skipping step 13a.
(the creation of the IDIPWSync group).
- Perform step 14.
The Domino Password Synchronizer intercepts both administrative
password resets (when an administrator edits a user's person document)
and normal password changes (when a user changes his own password
through the Change Password Web form from domcfg.nsf or
through iNotes).
Each one of these two features (intercepting administrative password
resets and user password changes) can be installed and used independent
of the other.
- Install Domino Password Synchronizer that only intercepts
administrative password resets (performed through the Lotus Domino Administrator
or through the Web browser interface):
To install a password synchronizer
that will only intercept administrative password resets, perform all
the steps from the Deployment on a single Domino Server section of this document, except steps 4 and 7.
On step 5, skip opening admin4.ntf and signing the IDIPWSyncAdminRequestAgent agent.
Steps
4 and 7 install the agent that intercepts normal user password changes.
When installing the solution on a Domino Domain
with multiple Domino Servers, follow the instructions
from the Deployment on a Domino Domain with multiple Domino Servers section of this document, but do
not perform steps 4 and 7 when installing the synchronizer on the
Administration Server.
- Install Domino Password Synchronizer that only intercepts
normal user password changes (performed through the Change
Password Web form from domcfg.nsf or
through iNotes):
To install a password synchronizer
that intercepts normal user password changes only, perform the following
steps from the Deployment on a single Domino Server section of this document: 1, 2, 4, 5, 7, 10, 11 and 14. On step 5, skip opening pubnames.ntf and signing the IDIPWSyncClientAgent and IDIPWSyncWebAgent agents. The steps skipped (3, 6, 8, 9, 12 and 13) are not performed because they are only necessary
for interception of administrative password resets.
When installing
the solution on a Domino Domain with multiple Domino Servers, it is only necessary to perform the previous subset of installation
steps on the Primary Domino Directory Server which is the
Administration Server for the Domino Directory.
No installation on the other Domino Servers
in the Domino Domain is necessary.
To minimize the scope of required privileges, in TDI v7.1 the
deployment procedure was modified to involve a dedicated signer account
to sign the agents of the Password Synchronizer. The pre-v7.1 deployment
procedure did not have such signer account, but instead required the
IDIPWSync group to be given the privilege to "sign or run unrestricted
methods and operations". The pre-v7.1 deployment procedure is still
supported (although not recommended), so existing customers are encouraged
but not forced to migrate.
To use the old deployment procedure apply the following modifications
to the steps from section Deployment on a single Domino Server:
- Skip step 5. (signing the agents)
- Skip step 13.a) vi) (adding the signer account to the IDIPWSync
group)
- After step 13.a) perform the following steps (in multi-server
topology apply these steps to all servers, where you deploy the Password
Synchronizer):
- Select the Security page.
- In the field Run unrestricted methods
and operations add the IDIPWSync group.
- Click Save & Close to save
the changes to the server document.