Customizing the HTML log-in form

HCL Domino® provides a default HTML log-in form to allow a user to enter a name and password, and then use that name and password for the entire user session. The Web browser sends the user's name and password to the server using the server's character set. Therefore, a user can enter a name and password in a character set other than ASCII or Latin-1.

About this task

The terms log-in and sign-in are used interchangeably.

The available set of characters to use for user name are different for basic authentication and session-based authentication.

Table 1. Available characters for name authentication

Authentication type

User name

Password

Basic authentication

Any printable characters in ISO-8859-1

Any printable characters in US-ASCII

HTTP session authentication

Any printable characters in Unicode

Any printable characters in US-ASCII

This form is created and configured in the Domino® Web Server Configuration database (DOMCFG.NSF). You can customize the form to contain additional information. To do this, the Domino® Web server must be set running.

To create and use a custom sign-in form, you must complete these procedures:

  • Create the Domino® Web Server Configuration database. If you do not create the database, Domino® uses a generic log-in form.
  • Create a custom form.
  • Specify the custom form as the sign-in form. If the Domino® Web Server Configuration database exists on the Web server but you have not created and specified a custom sign-in form, Domino® uses the form $$LoginUserForm.

Creating the Domino® Web Server Configuration database (DOMCFG.NSF)

Procedure

  1. From the Domino® Administrator choose File > Application > New.
  2. Enter the name of the Web server in the Server field.
  3. Select Show Advanced Templates.
  4. Select the Domino® Web Server Configuration template (DOMCFG5.NTF).
  5. Enter a title for the database.
  6. In the File name field, enter DOMCFG.NSF.
    Important: The name of the database is not optional, because the Web server has this name incorporated into its code. The name of the database must be DOMCFG.NSF.
  7. Click OK.
  8. Add an entry named Anonymous to the database ACL, and give the entry Reader access.

Creating a custom form

About this task

The simplest way to create a custom log-in form is to modify a copy of $$LoginUserForm, the example log-in form provided in the Domino® Configuration database. You can also create a new log-in form.

Procedure

  1. In the Domino® Designer client, open the Domino® Configuration database (DOMCFG.NSF).
  2. Choose View > Design.
  3. Do one of the following:
    • To create a custom form using $$LoginUserForm, make a copy of $$LoginUserForm, then double-click the copy to open it. (You can rename the copy if necessary -- for example, CustomLoginForm.)
    • Click New Form to create a new form.
  4. When you finish designing the custom form, save and close it.

Specifying the custom form as the log-in form

Procedure

  1. In the Notes® client, open the Domino® Configuration database (DOMCFG.NSF) and open the Sign In Form Mappings view.
  2. Click Add Mapping.
  3. Under Site Information, choose one:
    • All Web Sites/Entire Server -- to use the custom log-in form for all Web Sites on the server, or for the entire Web server.
    • Specific Web Sites/Virtual Servers -- to map the custom log-in form to specific Web Site documents or Virtual Servers. If you choose this option, a new field appears, in which you specify the IP addresses of the Web Site documents or Virtual Servers
  4. Optional: Enter a comment.
  5. Enter the file name of the database that contains the custom form. This should be DOMCFG.NSF unless you store the custom form in a different database.
  6. Enter the name of the custom log-in form.
  7. Save and close the document.

Configuring error messages

About this task

You can enable session-based Web authentication to return error messages for log-in failures and session time-outs. This is accomplished by configuring two fields on your custom login form -- the reasontext and reasontype fields. DOMCFG5.NTF includes these two fields in the default form provided, $$LoginUserForm. (To obtain the changes, you must refresh or replace the design of DOMCFG.NSF with the most current DOMCFG5.NTF).

The five cases that cause the Login form to appear are encoded in the field reasontype and include:

  • Prompt for the user to log in, at which no error message will display.
  • User Name, you are not authorized to access application.nsf. Please sign in with a name which has sufficient access rights. The user is authenticated with correct credentials for the server but is not authorized to the database or file, for example.
  • You provided an Invalid username or password. Please sign in again. The user has given an incorrect name or password.
  • Your connection has expired. Please sign in again. This occurs when the browser has not sent a request to the server in the given amount of time as configured in the server document (default=30 minutes). If the session times out, they will lose what hasn't been saved. Administrators should lengthen the server's session timeout, if this occurs frequently, to the length of a workday.
  • User Name, your login has been invalidated due to a timing issue with the login server. (The servers may need to have their clocks synchronized to resolve this.) Please sign in again. This occurs when multi-server session authentication is configured and an idle session timeout is enabled. This message indicates that the SSO servers do not agree on the current time, which may invalidate the user's SSO session.