Lotus Domino Server (Script)
Connector name |
|
Connector type | Executable |
Type (UI field value) | Lotus Domino Server (Script) |
Target system versions supported / tested | Lotus Domino 5, 6.x, 7.x, 8 and 8.5 databases |
Connector status / support | Customer-Verified Clients may contact Bravura Security support for assistance with this connector. Troubleshooting and testing must be completed in the client's test environment as Bravura Security does not maintain internal test environments for the associated target system. |
The Lotus Domino server script runs on a special applications and messaging server called the Lotus Domino Server. Lotus uses the Domino name to refer to a set of Notes server applications. Notes itself refers to the overall product.
There are two types of users for Lotus Notes:
Lotus Notes client users people who use the Notes client to access Domino servers and databases and have a Notes ID file, a Person document, and optionally a mail file.
See Lotus Domino Server to learn how to perform operations for this type of user.
non-Notes, Internet-only users people who do not own a Notes ID file and therefore cannot use the Lotus Notes client; these users may instead have web access to Domino servers and databases. Lotus Domino users have a Person document , and optionally a mail file.
This chapter details how to perform operations for this type of user in generic Domino databases, including the names.nsf database. If you only need to perform operations in a names.nsf database, refer to Lotus Domino Server for a simpler method.
The following Bravura Security Fabric operations are supported by agtgdmno for Lotus Domino 5, 6.x, 7.x, 8 and 8.5 databases. For Bravura Security Fabric to be able to successfully execute a particular operation on a specific Domino database, the operation must be defined as a LotusScript agent. The LotusScript agent is a script defined on the Domino server using the LotusScript scripting language. The Domino server script connector (agtgdmno) communicates with the LotusScript agents, then the LotusScript agents perform the actions on the Domino database.
user verify password
get server information
user change password
administrator reset password
administrator reset+expire password
expire password
unexpire password
enable account
disable account
check account enabled
add user to group
delete user from group
create group
delete group
lock account
unlock account
check account lock
expire account
check account expiry
unexpire account
move contexts
rename account
update attributes
list account attributes
move contexts
List:
accounts
attributes
groups
members
This chapter provides guidance about:
Configuring a target system administrator
Installing and configuring the client software
Targeting a Domino database
Setting up the agent database
Creating LotusScript agents
Configuring
agtgdmno
Preparation
Before Bravura Security Fabric can perform operations, you must:
Configure a target system administrator
Install and configure the client software
Create a template account
Configuring a target system administrator
Bravura Security Fabric uses a designated account (for example, psadmin) on the Domino server to perform Bravura Security Fabric operations. Create the account if one does not already exist, and ensure that it has the correct permissions.
Copy the designated administrator’s ID file to a directory on the Bravura Security Fabric server and note the password to the account. You will be required to enter the path to the ID file and its password when you add the target system to Bravura Security Fabric . You will also require this file to access the Domino server for configuration activities.
Installing and configuring the client software
Ensure that you have access to Lotus Domino Designer and Admin applications. These will be used to work on the Domino server hosting the database.
Install the Lotus Notes Client on the Bravura Security Fabric server. You will need the Notes ID file and password for the administrative account that you are going to use to connect to the Domino server with.
Update the system PATH on the Bravura Security Fabric server to include the directory where the Lotus Notes Client software was installed.
If you run IIS, reboot the Bravura Security Fabric server to ensure that the new path information is loaded.
Copy the
getpass.dllandpsynchpwd.dllfiles from the util directory into the Lotus Notes Client directory that contains the nnotes.dll file. The default location is normally C:\Program Files\lotus\notes.Edit the notes.ini file located in the same Lotus directory. At the end of the file, add this line followed by a blank line:
EXTMGR_ADDINS=psynchpwd.dllEnsure that the permissions on the notes.ini file allow all users to read and write.
Close any open Lotus Notes software, and restart it so that it re-loads the updated notes.ini file.
Note
Ensure that the Lotus Notes client is not used by human users on the Bravura Security Fabric server and that the last user to have logged in was the administrative account. Never log into Lotus Notes from the Bravura Security Fabric server using any login ID other than the one which is used by Bravura Security Fabric.
Creating a template account
Bravura Security Fabric uses template accounts as models or "blueprints" for creating new accounts on Lotus Domino Server targets. .
The following illustrates an example of how you can create a template account:
From a Windows workstation, select Programs > Lotus Applications > Lotus Domino Administrator.
Log into Lotus Domino Administrator by typing your user name and password in the appropriate fields.
Select the tab and expand Domino Directories .
Right-click People and select Register Person to view the Choose a Certifier dialog box.
Enter the Certifier password.
Click OK to view the Register Person – New Entry dialog box.
Type the new account’s names and password in the appropriate fields.
For Lotus Notes users, ensure that the Create a Notes ID for this person checkbox is selected.
Click the checkbox next to Advanced in the left section of the dialog box.
For a Lotus Notes user:
Click ID Info to view the Location for storing user ID section of the dialog box.
Ensure the checkboxes next to In Domino Directory and In file are selected.
Click Set ID File to search for and select the ID file location.
Click the check
mark button (add user).The account’s name displays in the User Registration Queue.
Click Register.
A message is displayed to confirm if the registration is successful.
Click Done to close the Register Person window.
Configure any additional attributes in the template account that you want to be automatically set for new accounts.
For non-Notes Internet-only users:
Double-click the user you just created.
The Person Record for:<User Name> window displays.
Click Edit Person to edit the user’s details.
Click the Basics tab.
Type an Internet Password for the user.
Click Save and Close to close the Person Record for:(User Name) window.
See your Lotus Notes system administrator or Lotus Notes documentation for more information if necessary.
Targeting a Domino database
For each Domino database, add a target system in Bravura Security Fabric (Manage the System > Resources > Target systems).
Type is Lotus Domino Server (Script) .
Address requires:
Server - Name of the database server
Config file - If specified, the file must exist in the \<instance>\script\ directory.
See Configuring
agtgdmnoto learn how to write the file.
The address is entered in the following syntax:
<server name>/<configuration file>
Administrator ID and Password is the path to the administrator’s Notes ID file on the Bravura Security Fabric server and password you configured earlier.
Setting up the agent database
The agent for Domino server script (agtgdmno) requires that a special agent database be created on the Domino server. The purpose of the database is to communicate with LotusScript agents that will be used to perform operations on the target Domino database. The agent database will relay commands, information, and return values between agtgdmno and the LotusScript agents.
To set up the agent database you must:
Create the agent database
Create a form for the agent database
Create a view for the agent database
Add LotusScript agents to the agent database
Creating the agent database
Create the agent database
Launch Domino Designer.
Select File > Database > New. The window appears.
In the Specify New Database Nameand Location area:
Select the Domino server that is hosting the Domino database you want to manage from the Server drop-down menu.
Name the agent database. Type an arbitrary name in the Title field. This also causes the File name field to be populated with a <name>.nsf value.
In the Specify Template for New Database area :
Select the Domino server from the Server drop-down menu.
Select
-Blank-for the template.
Click OK.
Creating a form for the agent database
Add the following form to the agent database.
On the tab for the new agent database, click the New Form button. A tab for the form opens.
Click to place the cursor in the top left of the workspace of the Form tab.
Use the following procedure to add each of the required fields to the form.
Type the name of the field then a space.
Right-click and select Create Field to bring up the Field dialog.
Type the name of the field in the Name field.
Close the dialog to save your changes.
Move the cursor past the newly created field then press Enter to advance to the next line.
Create the following fields. Note the extra configuration required for some fields.
UserId
FullName
AccountId
ShortId
NewPassword
OldPassword
ModelId
GroupId
GroupName
CreationAttributes – also check Allow multiple values in the Field dialog.
UserAttributes – also check Allow multiple values in the Field dialog.
ReturnCode
ErrorMsg
ReturnValue
ReturnAccountId
ReturnShortId
ReturnAttributes – also check Allow multiple values in the Field dialog.
ReturnGroups – also check Allow multiple values in the Field dialog.
Click File > Save and name the form.
Creating a view for the agent database
Add the following view to the agent database.
Select Views from the agent database’s bookmarks.
Click the (untitled view) bookmark icon to bring up the View dialog. Name the view. Close the dialog to save the changes.
Create the UserId column.
In the tab for the view, right-click the # column, and select Column Properties to bring up the Column dialog.
Change the title from
#toUserId. Close the dialog to save the changes.In the UserId (Column): Column Value pane, select the Field radio button then select UserId from the list of fields.
Use the following procedure to create the remaining columns.
Double-click to the right of previously-defined column header to create a new column and bring up the Column dialog.
Type the name in the Title field. Close the dialog to save the changes.
In the <name> (Column): Column Value pane, select the Field radio button then select the corresponding <name> from the list of fields.
Create the following columns. Ensure that you associate each column with the field of the same name.
FullName
AccountID
ShortID
NewPassword
OldPassword
ModelID
GroupId
GroupName
CreationAttributes
UserAttributes
ReturnCode
ErrorMsg
ReturnValue
ReturnAccountId
ReturnShortId
ReturnAttributes
ReturnGroups
Select File > Save.
Adding LotusScript agents to the agent database
A LotusScript agent must be created for each operation that is going to be performed on the target system database. See Creating LotusScript agents for details how to script an agent. Once the agents are scripted they need to be added to the database. The following procedure details how to add a LotusScript agent to the agent database. Perform the procedure for each agent that needs to be added to the database.
Launch Domino Designer.
Open the Shared Code bookmark folder for the agent database and click Agents.
Click New Agent in the workspace to bring up the Agent dialog box.
Name the LotusScript agent. It is recommended that you use the name of the operation that the script will perform; however, this is not mandatory, as the LotusScript agent will be mapped to an actual agent operation in the
agtgdmnoconfiguration file (see Configuring LotusScript agent operations ).In the Target drop-down menu select "All documents in database". Close the dialog.
Select LotusScript from the second drop-down menu in the <operation name> (Agent): Actions pane.
Select Initialize in the Objects tab.
Enter the script for the operation into the <operation name> (Agent): Actions pane between the "Sub Initialize" and "End Sub" commands.
Sub Initialize <enter script text> End SubSelect File > Save.
Creating LotusScript agents
This section assumes that you are familiar with scripting LotusScript agents. The purpose of this section is to highlight aspects of the script that are specific to working with agtgdmno. It covers:
Inputs given to the agent by
agtgdmnoOutputs given by the agent to
agtgdmno
Once the scripts are written they must be added as to the agent database as Shared Code > Agents . See Lotus Domino Server for a list of supported operations. Note that the List and UserAttributes operations are performed by agtgdmno ; agents do not need to be created for these operations. The scripts for two sample agents (reset.ls and verify.ls) are provided in the samples\* directory.
If you cannot find the sample file, try re-running setup to modify your installation. Sample files are automatically installed with complete (typical) installations. You can select them in custom installations.
For more information on LotusScript refer to the Lotus Domino Designer documentation specific to your version.
Inputs given to the LotusScript agent by agtgdmno
A subset of the following inputs are loaded into the agent database when agtgdmno runs a LotusScript agent:
UserId
FullName
AccountId
ShortId
NewPassword
OldPassword
ModelId
GroupId
GroupName
CreationAttributes
UserAttributes
Depending on the operation, some or all of the inputs are loaded. You can use the following LotusScript segment in your agent script to extract these inputs.
REM First thing to do is find arguments for the operation Dim session As New NotesSession Dim agentDoc As NotesDocument REM Parameters Dim userId As String Dim accountId As String Dim shortId As String Dim newPassword As String Dim oldPassword As String Dim modelId As String Dim groupId As String Dim groupName As String Dim creationAttributes As Variant Dim userAttributes As Variant REM Get the parameters from the operation document Set agentDoc = session.DocumentContext userId = agentDoc.GetItemValue( "UserId" )(0) accountId = agentDoc.GetItemValue( "AccountId" )(0) shortId = agentDoc.GetItemValue( "ShortId" )(0) newPassword = agentDoc.GetItemValue( "NewPassword" )(0) oldPassword = agentDoc.GetItemValue( "OldPassword" )(0) modelId = agentDoc.GetItemValue( "ModelId" )(0) groupId = agentDoc.GetItemValue( "GroupId" )(0) groupName = agentDoc.GetItemValue( "GroupName" )(0) creationAttributes = agentDoc.GetItemValue( "CreationAttributes" ) userAttributes = agentDoc.GetItemValue( "UserAttributes" )
Note that both CreationAttributes and UserAttributes are stored as property lists. A property list has the following form:
(Attribute_Name_1 Attribute_Value_1 Attribute_Name_2 Attribute_Value_2 .... Attribute_Name_N Attribute_Value_N)
Outputs given by the LotusScript agent to agtgdmno
This section details the fields that the LotusScript agents must use to return information to agtgdmno .
ReturnCode
LotusScript agents must always set the ReturnCode field; an error is triggered by agtgdmno if it is not set. This field tells agtgdmno if the agent successfully completed its operation. ReturnCode can be set to:
0 LotusScript agent was successful
1 LotusScript agent was unable perform its operation To set this field, use the following syntax:
Call agentDoc.ReplaceItemValue( "ReturnCode", "<value>" )
ErrorMsg
You can use the ErrorMsg field to inform agtgdmno of any error conditions encountered by the LotusScript agent. To set this field, use the following syntax:
Call agentDoc.ReplaceItemValue( "ErrorMsg", "<error message>" )
ReturnValue
You must set the ReturnValue field for the following operations:
ispwexpired
isenabled
islocked
isacctexpired
ReturnValue is set to the either true or false. To set this field, use the following syntax:
Call agentDoc.ReplaceItemValue( "ReturnValue", "<true|false>" )
ReturnAccountId
You must set the ReturnAccountId field for the following operations:
create
rename
movecontext
ReturnAccountId is set to the new account ID for the user. To set this field, use the following syntax:
Call agentDoc.ReplaceItemValue( "ReturnAccountId", "<account ID>" )
ReturnShortId
You must set the ReturnShortId field for the following operations:
create
rename
movecontext
ReturnShortId is set to the new short ID for the user. To set this field, use the following syntax:
Call agentDoc.ReplaceItemValue( "ReturnShortId", "<short ID>" )
ReturnAttributes
You must set the ReturnAttributes field for the following operations:
create
update
ReturnAttributes is set to the new attributes for the user. To set this field, use the following syntax:
Call agentDoc.ReplaceItemValue( "ReturnAttributes", <attributes> )
ReturnAttributes is stored as property list. A property list has the following form:
(Attribute_Name_1 Attribute_Value_1 Attribute_Name_2 Attribute_Value_2 .... Attribute_Name_N Attribute_Value_N)
ReturnGroups
You must set the ReturnGroups field for the following operations:
create
update
ReturnGroups is set to the new attributes for the user. To set this field, use the following syntax:
Call agentDoc.ReplaceItemValue( "ReturnGroups", <groups> )
ReturnGroups is stored as a property list. A property list has the following form:
(Attribute_Name_1 Attribute_Value_1 Attribute_Name_2 Attribute_Value_2 .... Attribute_Name_N Attribute_Value_N)
Saving field values to the agent document
After all the return values have been set, you must include the following LotusScript line. This saves the values to the agent document:
Call agentDoc.Save(True, True)
Configuring agtgdmno
The Domino server script agent (agtgdmno) uses a configuration file that is specified as part of target system address. It has the following form:
"" "" = {
"<operation_1>" "" = {
....
}
"<operation_2>" "" = {
....
}
.
.
.
"<operation_N>" "" = {
....
}
}where the supported operations are:
change Changes the password for an account, from a known current value to a desired new value. If the application supports the concept of intruder lockout, then the intruder lockout counter is cleared and the account unlocked. If the application supports the concept of password expiry, then the expiry date is set according to the expiry policy of the application.
reset Administratively resets an account’s password to a new value. If the application supports the concept of intruder lockout, then the intruder lockout counter is cleared and the account unlocked. If the application supports the concept of password expiry, then the expiry date is set according to the expiry policy of the application. Disabled accounts will remain disabled.
adminverify Checks if a given password is the correct, current password for an account without triggering an intruder lockout if the password is not correct.
verifyreset Verifies if the account’s password matches the new password, and if the verification fails, administratively sets it to the new password. If the verification succeeds, then the reset is not necessary, and the operation returns success.
resetexpirepw Administratively resets an account’s password to a new value and expires the account’s new password, so that the user is forced to change his password the next time he logs in.
expirepw Expires an account’s password.
ispwexpired Checks if an account’s password is expired.
unexpirepw Unexpires an account’s password.
list List users, groups, and/or attributes,each one defined as a KVGroup inside of list.
verify Checks if a given password is the correct, current password for an account. If the application supports the concept of intruder lockout and the verification fails, the intruder lockout counter is incremented.
userattributes Lists attributes for a specified account.
isenabled Checks if an account is enabled.
enable Enables an account.
disable Disables an account.
rename Renames an existing account’s short ID.
create Creates a new account on the target system. This operation creates the account (possibly using a template for some attribute values), then sets other attribute values – including the password for the new account.
This operation should return the group ID.
delete Deletes an existing account on the target system. The typical behavior is to first ensure that the account being deleted exists.
update Updates attributes for an existing account.
This operation should return the group ID.
expireacct Expires an account.
isacctexpired Checks if an account is expired.
unexpireacct Unexpires an account.
lock Locks an account (sets the intruder lockout).
unlock Unlocks an account (clears the intruder lockout).
islocked Checks if an account is locked.
groupuseradd Adds an account to a group.
This operation must return a status.
groupuserdelete Removes an account from a group.
This operation must return a status.
movecontext Moves an account to a new context or location on a context-sensitive target. This operation should return the account’s long ID and short ID.
groupcreate Creates the specified group.
groupdelete Deletes the specified group.
How the file is configured depends on whether the target system database is names.nsf or a generic Domino database. Guidelines for creating the configuration file are provided for both scenarios. A sample configuration file (agtgdmno.cfg) is provided in the <instance>\samples\ directory.
If you cannot find the sample file, try re-running setup to modify your installation. Sample files are automatically installed with complete (typical) installations. You can select them in custom installations.
The agtgdnmo.cfg file must be saved in the <Program Files path>\Bravura Security\Bravura Security Fabric\<instance>\ script\ directory with UTF-8 encoding.
Configuring agtgdmno for use with a names.nsf database
You must configure the following items in the configuration file:
List operations
LotusScript agent operations
Configuring list operations
List operations are programmed into agtgdmno ; they are not handled by a LotusScript agent. The form of the KVGroup for list operations for a names.nsf database is:
"list" "" = {
"user" "" = {
"database" = "<Domino server>!!names.nsf"
"view" = "People"
"sort-column" = "Name"
"search-field" = "Name"
"longid-field" = "FullName"
"shortid-field" = "ShortName"
"first-name-field" = "FirstName"
"middle-name-field" = "MiddleName"
"last-name-field" = "LastName"
"type-field" = "Type"
"type-value" = "Person"
}
"group" "" = {
"database" = "<Domino server>!!names.nsf"
"view" = "Groups"
"sort-column" = "Groups"
"search-field" = "ListName"
"groupid-field" = "ListName"
"member-field" = "Members"
"description-field" = "ListDescription"
}
"attribute" "" = {
"attribute" = "groups"
"attribute" = "<attribute name 2>"
.
.
"attribute" = "<attribute name N>"
}
}In order to list groups, the group KVGroup must be defined and one of the attributes must be set to "groups". In order to list other attributes, the attribute must be added to the attribute KVGroup as follows:
"attribute" "" = {
"attribute" = "groups"
"attribute" = "<attribute name 2>"
.
.
"attribute" = "<attribute name N>"
}where <attribute name#> is the name of a field in the names.nsf database; for example, <attribute name 2> could be replaced with ShortName. Add a key value to the attribute KVGroup for each attribute that you want to list.
By default, a generic Domino target has no defined attributes, so for each attribute listed in the attribute KVGroup, you must add a matching attribute to the target. See Account attributes in the Bravura Security Fabric configuration documentation to learn how to do this.
Configuring LotusScript agent operations
You must add a KVGroup for each LotusScript agent operation that has been defined using the following form. The KVGroup must be named using the the correct agent operation (see page Configuring agtgdmno ).
"<Agent Operation>" "" = {
"agent-name" = "<LotusScript agent name>"
"agent-database" = "<Domino server>!!names.nsf"
"agent-form" = "<Agent database form>"
"agent-statistics" = "<yes/no option for outputting
the log information from LotusScript agent>"
}Configuring agtgdmno for use with generic Domino databases
You must configure the following items in the configuration file:
List operations
UserAttributes operation
LotusScript agent operations
Configuring list operations
List operations are programmed into agtgdmno; they are not handled by a LotusScript agent. The form of the KVGroup for list operations for a generic Domino database is:
"list" "" = {
"user" "" = {
"database" = "<Domino server>!!<target database>.nsf"
"view" = "<Target database view>"
"sort-column" = "<Field which the view is sorted on>"
"search-field" = "<Name of the field to search on>"
"longid-field" = "<Long ID field>"
"shortid-field" = "<Short ID field>"
#The full name field does not need to be specified if
#first-name-field and last-name-field are specified
"fullname-field" = "<Full name field>"
#The first-name-field, middle-name-field, and last-name-field
#do no need to be specified if the fullname-field is
#specified.
"first-name-field" = "<First name field>"
"middle-name-field" = "<Middle name field>"
"last-name-field" = "<Last name field>"
"type-field" = "<Type field>"
"type-value" = "<Type value>"
}
"group" "" = {
"database" = "<Domino server>!!<target database>.nsf"
"view" = "<Target database view>"
"sort-column" = "<Field which the view is sorted on>"
"search-field" = "<Name of the field to search on>"
"groupid-field" = "<Group ID field>"
"member-field" = "<Group members field>"
"description-field" = "<Group description field>"
}
"attribute" "" = {
"attribute" = "groups"
"attribute" = "<attribute name 2>"
.
.
"attribute" = "<attribute name N>"
}
}By default a generic Domino target has no defined attributes, so for each attribute listed in the attribute KVGroup, you need to add a matching attribute to the target. See Account attributes in the Bravura Security Fabric configuration documentation to learn how to do this.
Configuring UserAttributes operation
The UserAttributes operation is programmed into agtgdmno . It is not handled by a LotusScript agent. The form of the KVGroup for the UserAttributes operation for a generic Domino database is:
"userattributes" "" = {
"user" "" = {
"database" = "<Domino server>!!<target database>.nsf"
"view" = "<Target database view>"
"sort-column" = "<Field which the view is sorted on>"
"search-field" = "<Name of the field to search on>"
"longid-field" = "<Long ID field>"
"shortid-field" = "<Short ID field>"
#The full name field does not need to be specified if
#first-name-field and last-name-field are specified
"fullname-field" = "<Full name field>"
#The first-name-field, middle-name-field, and last-name-field
#do no need to be specified if the fullname-field is
#specified.
"first-name-field" = "<First name field>"
"middle-name-field" = "<Middle name field>"
"last-name-field" = "<Last name field>"
"type-field" = "<Type field>"
"type-value" = "<Type value>"
}
"group" "" = {
"database" = "<Domino server>!!<target database>.nsf"
"view" = "<Target database view>"
"sort-column" = "<Field which the view is sorted on>"
"search-field" = "<Name of the field to search on>"
"groupid-field" = "<Group ID field>"
"member-field" = "<Group members field>"
"description-field" = "<Group description field>"
}
"attribute" "" = {
"attribute" = "groups"
"attribute" = "<attribute name 2>"
....
"attribute" = "<attribute name N>"
}
}By default a generic Domino target has no defined attributes, so for each attribute listed in the attribute KVGroup, you need to add a matching attribute to the target. See Account attributes in the Bravura Security Fabric configuration documentation to learn how to do this.
Configuring LotusScript agent operations
You must add a KVGroup for each LotusScript agent operation that has been defined using the following form. The KVGroup must be named using the correct agent operation. See Configuring agtgdmno .
"<Agent Operation>" "" = {
"agent-name" = "<LotusScript agent name>"
"agent-database" = "<Domino server>!!<agent database>.nsf"
"agent-form" = "<Agent database form>"
"agent-statistics" = "<yes/no option for outputting
the log information from LotusScript agent>"
}