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:
- Open Lotus Domino Directory with the Lotus Notes client.
- Click Configuration - Servers - Configuration.
- Edit the default server configuration document or an individual server configuration document.
- 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.
If users hve a different value for the setting in the user policy, that value overrides the one set in the server configuration document.
- 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.
- 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
- Save and close.
- 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:
- Open Lotus Domino Directory.
- Click Configuration - Policies - Settings.
- Open the security policy. If one does not exist, create a new security policy.
- 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
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
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
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:
- Open the domcfg.nsf database on the server.
- Click the Add Mapping button. In the Applies to field, enter All Web Sites/Entire Server.
- In the Target Database field, enter the name of the database containing the customized login form.
- 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
- Click the Save and Exit buttons.
- 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
Figure 7 shows the email that users receive after the password is reset.
Figure 7. 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 name||Type||Description|
|Custom password management||Application||This element is a custom NSF file that contains a Custom Logon form and the agent that runs the majority of the transaction.|
|CustomLogonForm||Form||This 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.|
|PwdQuery||Agent||This agent is written in LotusScriptÂ® and does the following:|
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:
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.
Here is the sample code that we wrote to support this article.
Password Reset button in CustomLogonForm
Form JS header code in CustomLogonForm
var uname = document.forms.Username.value;
window.location = '/PwdMgt.nsf/PwdQuery?OpenAgent&QueryString=' + uname;
PwdQuery: Agent Initialize code
Listing 1. Agent initialize code
Sub Initialize %REM 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 %END REM ' 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) Else 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) Else '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 Else '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 Else '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 ErrorHandler: 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 ErrorHandler: 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 ErrorHandler: 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) %REM 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 %END REM 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") Else 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 Wend Exit Sub ErrorHandler: 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.
- Get started with IBM Lotus Notes and Domino V8 technical content.
- Read the developerWorksÂ® article, "Securing an IBM Lotus Domino Web Server: A case study."
- Read the developerWorksÂ® article, "Securing a Lotus Domino Web server."
- Read the developerWorksÂ® article, "What's new in IBM Lotus Notes and Domino V8."
- Read the "Lotus Notes and Domino 8 Reviewer's Guide."
- Download a trial of IBM Lotus Domino.
- Download a trial of IBM Lotus Notes, Domino Designer, and Domino Administrator clients.