Securing an IBM Lotus Domino Web server: Using the new Internet lockout feature

Internet password lockout lets administrators set a threshold value for Internet password authentication failures for users of Lotus Domino applications, including Lotus Domino Web Access. This lockout helps to prevent brute force and dictionary attacks on user Internet accounts by locking out any user who fails to log in within a preset number of attempts. Information about authentication failures and lockouts is maintained in the Internet Lockout application, where the administrator can clear failures and unlock user accounts.

Note, though, that this feature is subject to denial-of-service (DoS) attacks. A DoS attack is one in which malicious users explicitly prevent legitimate users of a service from using that service. In the case of Internet password lockout, legitimate Internet users could be prevented from logging in to a Lotus Domino server by attackers who intentionally make failed login attempts.

There are some usage restrictions for Internet password lockout:

  • You can use Internet password lockout only with Web access. Other Internet protocols and services, such as LDAP, POP, IMAP, DIIOP, IBM Lotus QuickPlace®, and IBM Lotus Sametime® are not currently supported. Internet password lockout, however, can be used for Web access if the password that is used for authentication is stored on an LDAP server.
  • You might not be able to leverage the functionality of the Internet lockout feature if custom DSAPI filters are in use, as the DSAPI filter is a way to bypass Lotus Notes® and Domino authentication.
  • For single sign-on (SSO), the Lotus Domino server on which the Internet password lockout feature is enabled must also be the server that issues the single sign-on key. If this key is retrieved from another source (another Lotus Domino server or an IBM WebSphere® server, for example), the SSO token is always valid on the Lotus Domino server, even if Internet password locking is enabled.

Keep in mind that Internet lockout requires a Lotus Domino 8 server and a Lotus Domino 8 address book template.

Configuring Internet lockout

Internet lockout is not enabled by default on a Lotus Domino server. In this section, we document the steps that you can take to enable Internet lockout on a Lotus Domino server.

To enable Internet lockout using the configuration settings, follow these steps:

  1. Open Lotus Domino Directory with the Lotus Notes client.
  2. Click Configuration - Servers - Configuration.
  3. Edit the default server configuration document or an individual server configuration document.
  4. Click the security tab.
    • Change the option Enforce Internet password lockout to yes.
    • Set the log settings. Log both lockouts and failures.
    • Set the default maximum tries.
    Specify the maximum number of bad password attempts allowed before users are locked out. The default value is 5. After a user is locked out, the user account must be unlocked before any new values for this setting are in effect for that user.

    If users hve a different value for the setting in the user policy, that value overrides the one set in the server configuration document.
  5. Set the default lockout expiration.

    Specify the period of time for which a lockout is enforced. After the specified time period expires, the user account is automatically unlocked when the user next tries to authenticate. In addition, all failure attempts are cleared.

    NOTE: If this value is 0, the lockout does not expire automatically. The account must be unlocked manually.
  6. Set the default maximum tries interval.

    Specify the length of time failed password attempts are retained in the lockout database before they can be cleared by a successful authentication. The default value is 24 hours.

    This setting does not apply to users who are locked out. If a user is locked out, the only way to clear failure attempts and unlock the account is to do so manually, in the Internet Lockout database, or when lockout expiration occurs.

    NOTE: If this value is 0, every successful login, for a given user who is not locked out, clears all failed password attempts by that user.

    Figure 1. Internet lockout setting
    Internet lockout setting
  7. Save and close.
  8. Restart the Lotus Domino server.

Internet lockout can also be configured using security policies. This approach enables administrators to enforce Internet lockouts for only a subset of users. Note that security policies can overide the server's Internet lockout settings.

To enable Internet lockout using security policies, follow these steps:

  1. Open Lotus Domino Directory.
  2. Click Configuration - Policies - Settings.
  3. Open the security policy. If one does not exist, create a new security policy.
  4. Click the Password Management tab and enter these values as shown in figure 2:
    • Set the option Override Server's Internet Lockout settings? to yes.
    • Set the option Maximum Tries Allowed to 5.
    • Set the option Lockout Expiration to 60 minutes.
    • Set the option Maximum Tries Interval to 1 day.
    • Set all settings to Enforce.
    Figure 2. Setting security policies
    Setting security policies
    Setting security policies

After the security settings are configured, they can be assigned to a policy and the policy can be assigned to individual users or to organizational units. For more information on setting policies, refer to the Lotus Domino Administration Help database. Note that Internet password lockouts must be enabled in the server configuration document for the Internet password lockout policy settings to be enforced. This approach allows administrators to have different settings for individual user groups.

After these settings are configured, an inetlockout.nsf database is created. This database records and tracks locked-out users and failed logins. Replicate this database between Web-enabled servers to ensure that locked-out users remain locked out for the entire infrastructure. The inetlockout.nsf database is created from the inetlockout.ntf database template. All users should be listed as having no access to the database. Only Internet password administrators should be able to access this database.

Figure 3 shows the message that users receive when they have been locked out. This message displays with the default login form. Later in the article, we change to a custom login form.

Figure 3. Locked-out message
Locked-out message

The inetlockout.nsf database also allows administrators to track which users have been locked out. Administrators have the option of unlocking the users as well. Figure 4 shows the information available in the Internet lockout database. This database can also record all user login failures. This fact can be useful when security administrators try to detect password hacking attempts.

Figure 4. The Internet lockout database
The Internet lockout database
The Internet lockout database

Custom login form

In this part of the article, we discuss a sample customized login form. This login form provides an improved user interface (UI) and password reset functionality. We created a custom database with a new login form. We modified domcfg.nsf to point login requests to our customized login form.

Instructions for the Lotus Domino Web server configuration database

By default, a Domino Web server configuration database is not created. You might need to create this database by using the domcfg5.ntf template.

To modify the Domino Web server configuration database, follow these steps:

  1. Open the domcfg.nsf database on the server.
  2. Click the Add Mapping button. In the Applies to field, enter All Web Sites/Entire Server.
  3. In the Target Database field, enter the name of the database containing the customized login form.
  4. In the Target form field, enter the name of the target form in the database. In our sample, the database is called PwdMgt.nsf and the form is called CustomLoginForm.

    Figure 5. Setting the 'Sign in' form mapping
    Setting the 'Sign in' form mapping
    Setting the 'Sign in' form mapping
  5. Click the Save and Exit buttons.
  6. Restart the HTTP task on the server.

When users request a database that requires authentication, they now see the customized login form.

The customized login form is shown in figure 6. It includes a password reset button. After users enter their User IDs in the User ID field and clicks the Password Reset button, they receive an email with a new password.

Figure 6. The customized logon form
The customized logon form
The customized logon form

Figure 7 shows the email that users receive after the password is reset.

Figure 7. Email notification of password reset
Email notification of password reset
Email notification of password reset

The password reset tool

The sample code that follows can be used to demonstrate how the HTTP password can be updated from a custom logon window in a browser client. This code is not meant to be put directly into production, but it obviously could catalyze a development effort and potentially shorten the development life cycle of a related implementation.

The code provided in this article allows users to click a Password Reset button located on a Custom Logon window in the custom password management application. The Password Reset button runs a PwdQuery agent that creates a unique random password, updates the person document in the Lotus Domino directory, and creates and sends an email to users with the new unique password.

Outlined in table 1 are the design elements included in the sample code. The agents provided as sample code should be signed by the server on which they run. This signing gives the agents the correct rights to run on the server and the appropriate access to the address book.

Table 1. Design elements of the sample code
Design element nameTypeDescription
Custom password managementApplicationThis element is a custom NSF file that contains a Custom Logon form and the agent that runs the majority of the transaction.
CustomLogonFormFormThis element is a custom logon form that is located in a password management (PwdMgt.nsf) Lotus Domino application. This functionality and form could be located in the Lotus Domino Configuration database if desired. The form is displayed to users when an HTTP authentication request is sent to the Lotus Domino server.
Reset PasswordButtonThe Reset Password button is located on the CustomLogonForm and is displayed to users. When users click the Reset Password button, JavaScriptâ„¢ code constructs a URL that invokes the PwdQuery agent.
PwdQueryAgentThis agent is written in LotusScript® and does the following:
  1. Retrieves the user name from the URL.
  2. Creates a new random password.
  3. Locates and updates the HTTPPassword and HTTPPasswordChangeDate fields on the associated Person document in the Lotus Domino Directory.
  4. Sends an email to the user with the new password.
  5. Displays an output screen to users conveying that the password has been reset.

PwdQuery Agent: Invocation

The agent is to be invoked using a URL. The URL must contain the user's name appended to the URL in a QueryString. Here is a sample URL to execute the agent:
/PwdMgt.nsf/PwdQuerySave?OpenAgent&QueryString=Scott Rice/ibm

PwdQuery Agent: Input

Input of the agent is the user name of the person whose HTTP password is to be updated. For the implementation of this sample code, the user name needs to be the abbreviated Lotus Notes name for that user; it is passed to the agent using the QueryString method in the URL. The agent code can be changed to be mapped to a different view if desired, or a new view can be created in the Lotus Domino Directory so that the Lotus Notes common name be used.

PwdQuery Agent: Output

Output of the agent displays either text to users stating that the password has been successfully changed to a new random password or an error message in the browser window if an error occurs during agent execution.

Sample code

Here is the sample code that we wrote to support this article.

Password Reset button in CustomLogonForm

The following code initiates the password change from users. When the user clicks the Password Reset button, the JavaScript changePwd() function is started.


Form JS header code in CustomLogonForm

This JavaScript function is located in the JS header of the Lotus Domino form and runs the PwdQuery agent using ?OpenAgent in the URL. This code is invoked by the Password Reset button.

function changePwd(){
var uname = document.forms[0].Username.value;
window.location = '/PwdMgt.nsf/PwdQuery?OpenAgent&QueryString=' + uname;

PwdQuery: Agent Initialize code

The code shown in listing 1 is the agent code invoked by the changePwd() JavaScript function that performs most of the transaction. This agent creates a random password, sets the password and date and time on the person document in the Lotus Domino Directory, and sends an email to users with the new HTTP password.

Listing 1. Agent initialize code
Sub Initialize
Purpose - This agent is for demo/sample purposes only and is not intended to be 
implemented in a production environment.  This agent createsa random password and sets 
the HTTPPassword and HTTPPasswordChangeDate fields with appropriate values. Then an 
email is sent to the user with the new password.  Please note that it may take a few 
minutes for the user to use new password after the agent has be executed.

Input. Abbreviated Lotus Notes name that is used to look up the person document in 
the Lotus Domino Public Directory.

Output.  The Print statement in this agent writes to the browser and shows the user 
that the agent has been processed as the password has been changed.  The output of 
this agent is only a sample and is limited in nature but could be expanded on greatly.

Instantiated.  This is agent is to be executed by a URL with the user name of the 
person to have the password change appended to the URLusing  QueryString.  
The URL should conform to this standard for the agent to execute properly:
http://domain/PwdMgt.nsf/PwdQuerySave?OpenAgent&QueryString=Abbreviated Name
' Setup the Agent Log
Dim errStr As String     'Error string variables
Dim agentLog As New NotesLog("Agent log")     'Used to write to the Agent Log
Call agentLog.OpenAgentLog
Call agentLog.LogAction("Entering the Initialize")
On Error Goto ErrorHandler
' Setup the variable to be used to process the Admin P Request
Dim session As New NotesSession     'Domino Session object
Dim dbDirectory As NotesDatabase     'Database object for the Domino directory
Dim db As NotesDatabase     'Database object for this database
Dim viewDirectory As NotesView	     'View object in the Domino Directory to look up 
the person document
Dim personDoc As NotesDocument     'Person document related to the User 
Name password to be changed
Dim userName As String     'User Name of the end user to be processed
Dim dirName As String     'Domino Directory file name (normally names.nsf)
Dim vwName As String     'View name used in the Domino Directory to 
look up the person document
Dim password As String     'New random password to be used on the 
Person document in the HTTPPassword field
Dim docContext As NotesDocument     'Web document used to get the 
QueryString / User Name variable
Dim queryString As String     'Variable from the URL that executes 
this agent containing the user name	
'set variables for the agent
Set docContext = session.DocumentContext
If Not(docContext Is Nothing) Then
	queryString = docContext.QUERY_STRING(0)
	agentLog.LogAction("QueryString = " + queryString)
	agentLog.LogAction("There is no docContext for
	QueryString variable. 
	Must execute this agent from a URL with 
	'/PwdMgt.nsf/PwdQuerySave?OpenAgent&QueryString=Abbreviated Name'")
	errStr = "There is no docContext for QueryString variable. Must execute this 
	agent from a URL with 
	'/PwdMgt.nsf/PwdQuerySave?OpenAgent&QueryString=Abbreviated Name'"
	Goto ErrorHandler
End If
'get the username to be processed
userName = getUserName(agentLog, queryString)
'variables to run code below
dirName = "names.nsf"
vwName = "($VIMPeople)"
'create a unqiue password to be reset
password = createUniquePwd(agentLog)
'open the directory and the custom pwd change mgt tool
Set dbDirectory = session.GetDatabase("", dirName)
Set db = session.CurrentDatabase
If dbDirectory.IsOpen Then
	'set the vew to lookup the person document with
	Call agentLog.LogAction("Opened the directory")
	Set viewDirectory = dbDirectory.GetView(vwName)
	If Not(viewDirectory Is Nothing) Then
		Call agentLog.LogAction("Set the Directory View")		
		'set the person document in the view
		Call agentLog.LogAction("viewName is " + viewDirectory.Name)
		Set personDoc =  viewDirectory.GetDocumentByKey(userName, True)
	If Not(personDoc Is Nothing) Then
		Call agentLog.LogAction("Set the person document")
		'set the HTTP Password field to a unique random value
		personDoc.HTTPPassword = password				
		'set the date time value that the HTTP Password was set
		personDoc.HTTPPasswordChangeDate = Now
		'save the person document
		Call personDoc.Save(True, False)		
		Call agentLog.LogAction("Saved the persondocument")
		'send email using the DisplayName field in the person document
		Dim emailDoc As NotesDocument				
		Dim sendToName As String
		sendToName = personDoc.InternetAddress(0)
		Call agentLog.LogAction("SendTo:  " + sendToName )	
		Set emailDoc = New NotesDocument( db )
		Call agentLog.LogAction("Created new email document")
		'create the email fields and associated values
		emailDoc.Form = "Memo"
		emailDoc.SendTo = sendToName
		emailDoc.Subject = "URGENT:  HTTP Password Change Request"
		emailDoc.Body = "Your HTTP Password was changed to: " + password
		Call agentLog.LogAction("Set fields on email document")
		'route the document to the end user
		Call emailDoc.Send( False )
		Call agentLog.LogAction("Sent the email to " + sendToName)
		'couldn't open the person document
		errStr = "Could not get the person document in the Directory.  Probably 
		need to use the Abbreviated name instead of Common Name."
		Call agentLog.LogAction("Could not get the person document in the 
		Directory.  Probably didn't use the Abbreviated name.")
		Goto ErrorHandler
	End If		
	'couldn't open the view in the directory
	errStr = "Could not get the view in the directory"
	Call agentLog.LogAction("Could not get the view in the directory")
	Goto ErrorHandler
End If
	'could not open the Domino Directory
	errStr = "Could not open the Domino Directory"
	Call agentLog.LogAction(errStr)
	Goto ErrorHandler
End If
' Close out the Agent
Call agentLog.LogAction("Existing Intialize")
Call agentLog.Close
'Print out to the browser to notify the end user
Print "Password has been changed for " + UserName + ".  Please check your 
email via a Notes Client for the password."
Exit Sub
	If errStr = "" Then
		errStr =  "Error in Initialize: " & Err() & ": " & Error()
	End If
	Call agentLog.LogAction(errStr)
	Call agentLog.Close
	Print "An error occured please check the Agent Log for details.  
	<br><br> Description of what occured is: <br>" + errStr
End Sub

PwdQuery agent: createUniquePwd function code

This LotusScript function creates a new unique password by leveraging the @Unique @Function using Evaluate in LotusScript. The return value is a new and unique password to the initialize subroutine that invokes this function. See listing 2.

Listing 2. createUniquePwd function code
Function createUniquePwd(agentLog As NotesLog) As String
Call agentLog.LogAction("entering createUniquePwd function")
Dim pwdunique As Variant     'contains the new unique password to be created
from the @Unique @function
Dim password As String			'contains the string form of the unique password
Dim i As Integer						'counter
Dim r As String						'used for string parsing
Dim l As String						'used for string parsing
Dim errStr As String				'used for error handling
On Error Goto ErrorHandler
'create the unique password for the end user
pwdunique = Evaluate("@Unique")
password = pwdunique(0)
Call agentLog.LogAction(password)
'parse the password to remove the - character
i = Instr(password, "-")
Call agentLog.LogAction(i)
l = Left(password, i - 1)
r = Right(password, i + 1)
Call agentLog.LogAction("l = " + l )
Call agentLog.LogAction("r = " + r )
'return the new unique password back to the main function
createUniquePwd = l + r
Call agentLog.LogAction("exiting createUniquePwd function")
Exit Function
	errStr =  "Error in createUniquePwd: " & Err() & ": " & Error()
	Call agentLog.LogAction(errStr)
End Function

PwdQuery agent: getUserName function code

This LotusScript function is invoked by the initialize subroutine of the agent and returns the actual user name of the user for whom the password is to be changed. The query string is passed in, for example, as &QueryString=Scott%20 Rice/ibm and outputs in the example Scott Rice/ibm. See listing 3.

Listing 3. getUserName function code
Function getUserName(agentLog As NotesLog, queryString As String) As String
	Dim i As Integer				'used as a counter
	Dim strTemp As String	'used to get the username as a string without %20 
	and replaced with blank spaces
	Dim qStr As Variant		'used with the @ReplaceSubString @function to 
	replace any %20 's in the string with black spaces
	Dim errStr As String		'used for error handling
	On Error Goto ErrorHandler
	'retrieve just the username from the QueryString
	agentLog.LogAction(queryString + " - in getUserName function")
	i = Instr(queryString, "=")
	agentLog.LogAction("i = " + Str(i))
	queryString = Right(queryString, Len(queryString) - i)
	'used for testing the @function so that the agent log
	agentLog.LogAction(queryString + " - In getUserName")
	agentLog.LogAction("@ReplaceSubString(""" + queryString + """, ""%20"", "" "")")
	'use the @ReplaceSubString @function to replace the %20 with black spaces
	qStr = Evaluate("@ReplaceSubString(""" + queryString + """; ""%20""; "" "")" )
	strTemp = qStr(0)
	agentLog.LogAction(strTemp + " - after Evaluate")
	'assign the name with appropriate blanks as a string
	queryString = strTemp
	'return the user name back to the main routine
	getUserName = queryString
	agentLog.LogAction("exiting getUserName function")
	Exit Function
	errStr =  "Error in getUserName: " & Err() & ": " & Error()
	Call agentLog.LogAction(errStr)
End Function

PwdQuery agent: deleteLockoutRecord function code

We include this LotusScript subroutine, shown in listing 4, in the agent here as sample code, but it is not invoked in the sample. If users exceed the maximum tries to log in based on the policy and if a locked-out record is created for that user, this code removes all locked-out documents for that user in the locked-out user application (interlockout.nsf). This routine is not invoked at this time in the agent, but you could include it in the initialize subroutine if you like.

Listing 4. deleteLockoutRecord function code
Sub deleteLockoutRecord(session As NotesSession, agentLog As NotesLog, 
UserName As String)
This subroutine was included as a sample if someone wanted to delete the Locked Out 
records.  Just add this routine to the main 
Initialize of this agent and pass in the appropriate parameters	
	Dim db As NotesDatabase     'dabase object for the Internet Locked Out database
	Dim view As NotesView     'view object to loop through the document in the 
	Locked Out database
	Dim doc As NotesDocument     'document object for each document while looping 
	through the document of the view
	Dim tmpdoc As NotesDocument     'temporary document set if there is a match so
	it can be deleted after the next document has been retrieved
	Dim item As NotesItem     'object for the ILUserName field on the document 
	which holds the users' name
	Dim notesname As NotesName     'object to change the name to abbreviated
	Dim abbrevName As String     'string that represents the appreviated user 
	name on the Locked Out document
	Dim deleteDoc As Boolean     'boolean true or false to flag a document to 
	be deleted
	Dim viewName As String     'variable that references the view name in the 
	Locked Out database
	Dim dbFileName As String     'variable that references the file name of the 
	Locked Out database
	Dim fieldName As String     'variable that references the field name 
	in the locked out document
	Dim errStr As String     'used in error handling
	On Error Goto ErrorHandler
	'set the variables
	dbFileName = "inetlockout.nsf"	
	viewName = "Locked Out Users"
	fieldName = "ILUserName"
	'set up the objects to be used in the subroutine
	Set db = session.GetDatabase("", dbFileName)
	agentLog.LogAction("opened the Locked Out database")
	Set view = db.GetView(viewName)
	agentLog.LogAction("opened the view " + viewName)
	Set doc = view.GetFirstDocument
	If doc Is Nothing Then
		agentLog.LogAction("There are no Locked Out documents to be processed")
		agentLog.LogAction("opened the first document")
	End If
	deleteDoc = False
	'loop through the view and delete any documents with the user name passed in
	While Not( doc Is Nothing )
		'get the user name on the Locked Out document
		Set item = doc.GetFirstItem( fieldName )
		'change it to an abbreviated form
		Set notesname = session.CreateName(item.Text)
		abbrevName = notesname.Abbreviated
		agentLog.LogAction("processing for: " + abbrevName)
	'check to see if there is a match and if true then save the document and flag 
	that this needs to be deleted
	If Ucase(UserName) = Ucase(abbrevName) Then
		agentLog.LogAction(Ucase(UserName) + " = " + Ucase(abbrevName))
		Set tmpdoc = doc
		deleteDoc = True
		agentLog.LogAction("deteleDoc = " + Str(deleteDoc))
	End If
		'get the next document in the view
		Set doc = view.GetNextDocument( doc )
		'delete the document from the Locked Out database
		If deleteDoc Then
			Call tmpdoc.Remove(True)
			Set tmpdoc = Nothing
			deleteDoc = False
		End If
	Exit Sub
	errStr =  "Error in deleteLockedOutRecord: " & Err() & ": " & Error()
	Call agentLog.LogAction(errStr)
End Sub


In this article, we discussed the Internet password lockout feature of Lotus Domino 8. We reviewed the capabilities of this feature and discussed how to configure it for your Lotus Domino 8 servers. We also discussed creating a custom login form and provided a sample password reset tool. We provided a starting point to secure and customize the Web interface. In the previous articles, listed in the Resources section, we discussed Lotus Domino Web security and provided a case study of a sample Lotus Domino Web server implementation. This article adds another method of providing Internet security that does not require a custom DSAPI filter, as was required in previous releases.

Downloadable resources

Related topics

Zone=Collaboration, Security
ArticleTitle=Securing an IBM Lotus Domino Web server: Using the new Internet lockout feature