Domino Web Server Settings
Domino servers sometimes require special agent parameters. These parameters are used only for Domino servers unless otherwise indicated. Use the topics in the following categories to protect your Domino resources:
- For basic configuration information, see the following topics:
- For information about authentication, see the following topics:
- CoordinateCA Single Sign-Onand Domino authentication.
- For information about usingCA Single Sign-Onforms credential collectors (FCCs), see the following topics:
- For information about subjects not covered in the previous lists, see the following topics:
Domino Agents Overview
The Domino Application Server is a messaging and Web application platform that offers secure access for Lotus Notes clients. The Domino Web Agent protects only the HTTP interface of the Domino Application Server, controlling access to HTML, JAVA, CGI, and other Web resources, such as Notes served over the web. It does not protect the Notes server.
Domino stores data in groups of Notes databases. Resources in a Notes database can be a variety of objects, such as documents, views, forms, and navigators. These objects can include text, video, graphics, and audio content.
Notes objects are opened using a URL. To make Notes objects available for the Web, Domino dynamically creates Web pages from the objects in the Notes database. In the case of database views, Domino also creates URL links to the documents in a view. The dynamic creation of pages from the Notes database provides users with the most current information.
Domino URL Syntax
Access to resources on a Domino server is based on the URL. Domino servers use a specific URL syntax.
Domino servers can interpret standard URLs, such as one shown in the following example:
Domino URL commands can use the following syntax:
- HostIndicates the DNS entry or IP address of the server.
- DatabaseSpecifies the database file name with the path relative to the notes \data directory or the database Replica ID.
- Domino_objectSpecifies the object in the database, for example, a view, document, form, or navigator.
- ActionIdentifies the operation that performed on the Notes object. For example: ?OpenDatabase, ?OpenView, ?OpenDocument, ?OpenForm, ?ReadForm, ?EditDocument. If no action is specified in the URL, the default is used.Default:?Open.
- ArgumentDefines how the Domino server delivers an object. For example, if the action and argument is?OpenView&Expand=5, this argument specifies the number of rows displayed in an expanded format.The following example shows a URL to access a view in a Notes database named financials.nsf:http://www.example.com/financials.nsf/reports?OpenView
One of the Notes database conventions is to create aliases for objects. For example, the alias might identify a resource by its Notes ID or Replica ID instead of the object name. Using aliases makes programming easier for developers because the names of the Notes resources can change without requiring code changes.
The following Domino URLs access the same resource though the resource is identified by its aliases:
Regardless of how a resource is identified, the Domino Web Agent converts all Domino naming conventions into a standard URL based on the name of the database resource. This simplifies data entry into the
CA Single Sign-Onpolicy store.
For example, the following Domino URLs are pointing to the people view in the names.nsf database. The database and view are referred to by Replica ID and Notes ID:
The Domino Web Agent converts these URLs to a standard URL, as follows:
The following illustration shows the conversion of aliases to a named object.
Configure the Domino Web Agent
The Domino Web Agent uses all the standard Web Agent settings to do the following:
- Configure the Web Agent to communicate with the Policy Server
- Add and remove Agent identities for virtual servers
- Modify Web Agent settings
- Configure single sign-on
- Configure error message logging
You can configure these centrally at the Policy Server or locally in the Agent configuration file.
In addition to the standard functions, there are Domino-specific parameters you can set.
Configure Domino-Specific Agent Functions
In addition to the standard Web Agent settings, there are specific Domino configuration parameters that you can set only for the Domino Web Agent. These settings determine how Domino authenticates and authorizes a user with
CA Single Sign-On. You can configure these settings centrally in the Agent Configuration Object on the Policy Server or locally in the Agent configuration file on the web server.
The Domino Web Agent does not support the auditing feature used to track user activity.
Specify User Directories for Domino
The Domino Directory is integrated with every Domino server. You can enable LDAP service for the Domino server so that Policy Server can use the Domino Directory to authenticate and authorize users. If you enable Domino’s LDAP service, you do not need to configure a separate user directory for authentication.
To enable LDAP service, see your Domino Server documentation.
Guidelines for Creating Policies on Domino Servers
Use the following guidelines when creating policies for the Domino server:
- A user can open a form with a parent document to view default values for the form. The parent document is the original form that is used to create the document. To prevent unauthorized users from viewing default values for forms on which they do not have access, set the SkipDominoAuth parameter to no.
- If you replicate databases on the same computer, create a duplicate set of rules to protect each database.
- If the Domino Agent cannot associate an alias for a Notes document with a form, then each document requires its own rule for protection.
- The Domino server uses special identifiers in URL commands for certain database documents, for example, $DefaultView, $DefaultForm, $DefaultNav, and $SearchForm. The Domino agent converts these identifiers to a standard URL to access the document.For $defaultNav, the Domino Agent performs an action of ?OpenDatabase. You do not need to create additional rules for these types of identifiers.
- Aliases in the Notes database protect their associated resources. If no alias exists, the resource name or comment protects the associated resource.
- The Lotus Notes software allows multiple objects of different types to have the same name and alias. If you create a rule that uses a wildcard with the ?Open action, such as, ?Open*, be aware that this rule protects different types of resources that share an alias or name.
- Forms protect the documents that they create. The action that is used with the form is ?ReadForm.
- The Domino Agent protects files with the .nsf extension. Do not add this extension to the IgnoreExt parameter.
Configure Policies for Domino
The Domino server can represent the same Notes object in different ways. An object can be identified using the name, ReplicaID, UniversalID, and alias.
For the Domino Web Agent to communicate effectively with the Domino server, the Domino Agent processes access requests to Notes resources using only the object name. This enables the policy store to understand the entry.
Expressed as a URL, the access method to any resource would be:
Create Rules for Domino Server Resources
Actions for the Notes database resources should be considered when you create rules. Any resource not specified with an action will default to the action ?Open. The rules that are included in a policy must account for the default action, ?Open, and equivalent actions for ?Open, such as ?OpenDatabase, ?OpenView, ?OpenDocument, ?OpenFrameset.
The Domino Web Agent enables a policy administrator to create one rule for many aliases that point to the same resource. You only need one rule because the Domino Agent converts Domino’s multiple representations of a resource into one URL. This function of the Domino Agent is important to consider when creating rules for policies.
You create realms and rules using the Administrative UI.
For more information, see the Policy Server documentation.
Consider a sample URL that is a link to a Domino server with a Notes database called db1.nsf. The database contains two files:
- Page 1 with aliases p1 and 85255e01
- Page 2 with aliases p2 and 76444d03
Example 1: Protecting one document and all its aliases.
For access to page1 and all its aliases, you create only one rule for the realm db1.nsf. The Domino Agent is able to interpret all the different naming conventions and convert them to a one standard URL format.
For your realms and rules, do the following:
- When creating a realm you would specify a resource filter for the database where page1 resides. For example, to protect all files in the database you would configure the following:Resource filter: /db1.nsf/To protect not only page1 but all its aliases, you would configure the following:Resource filter: /db1.nsf/page1
- To create a rule that protects any action on page1, enter an asterisk (*) in the Resource field of the Rule Properties dialog box. For example:Resource: *This * wildcard indicates that any action, such as ?Open, ?EditDocument can be performed on page1 by the users that are bound to the policy.
Example 2: Protecting different documents in the same database.
To protect page2 in the db1.nsf database in addition to page1, you need to create a second rule.
Resource Filter: /db1.nsf/page2
Example 3: Protecting different actions on a single resource
To protect individual actions on a resource, for example, if you wanted only some users to perform the action ?EditDocument and all users to perform the action ?ReadForm, each action would require its own rule for each resource, as follows:
- Rule 1Resource Filter: /db1.nsf/page1Resource: ?OpenView
- Rule 2Resource Filter: /db1.nsf/page1Resource: ?EditDocument
You could also use one rule as follows:
Resource Filter: /db1.nsf/page
Note:In the Resource field, there is no forward slash (/) before ?Open.
Even if there are aliases for this resource, the one rule would protect the original page and all its aliases.
Instead of creating several rules for different actions, you could specify a single rule and use wildcards to cover all actions, for example:
Resource filter: /db1.nsf/page
With the rule, you are then protecting the resource:
If you want a rule to be literal, write a regular expression.
Redirect Users to the Correct Port Using the HTTP HOST Request
Some applications perform load balancing by redirecting traffic to specific web servers
withoutmodifying the actual HTTP headers. To redirect users back to the proper external port and not the port used by the load balancer, enable the
GetPortFromHeadersparameter. This parameter is required for non-framework Agents for Domino web servers.
GetPortFromHeadersdirects the Web Agent to obtain the port number from the HTTP HOST request header instead of obtaining it from the web server service.
Authenticate Users with the Domino Server
The Domino server must authenticate and authorize users even if
CA Single Sign-Onhas already gone through this process.
CA Single Sign-Onworks with Domino’s authentication process by providing the Domino server with a user identity that is also configured in the Domino Directory, which is the list of users and their privileges. The Domino server uses this identity to authenticate and authorize the user for access to database resources.
A user name must be resolved unambiguously, or else the Domino Agent denies the authentication request. This may require some adjustments in your user directory.
The Domino Web Agent identifies the user to the Domino server as one of the following:
- Super user
- Actual user
- Default user
To determine which identity the Domino Web Agent uses when communicating with the Domino server, you configure the following parameters:
Determines which name to pass to the domino server for server authentication.
- DominoSuperUserIdentifies a user who has access to all resources on the Domino server.
- DominoDefaultUserIdentifies a user with default access to the Notes database, which means this person has general access privileges.
You can configure the DominoSuperUser and DominoDefaultUser locally, in the Agent configuration file, or centrally, in the Agent Configuration Object. In the Agent configuration file, these settings have encrypted values. In the Agent Configuration Object, you have the choice of encrypting these values or leaving them in plain text.
Authenticate as the Domino Super User
A Domino Super User is a user who has access to all resources on the Domino server. If your Web site or portal is designed with
CA Single Sign-Onin mind, you are securing resources and applications by implementing
CA Single Sign-Onpolicies. As a result, the Domino server does not have to restrict user access based on its own security. In this case, users can be identified as the Super User for Domino’s authentication purposes.
To identify the user as the Super User, you enable the SkipDominoAuth parameter and specify a value for the DominoSuperUser parameter. This action makes sure that
CA Single Sign-Onand not Domino authenticates users. The user that you specify must also be in the Domino Directory.
Authenticate as the Actual User or the Default User
If a user is defined in the Domino Directory, Domino authenticates that user with their user name. However, if the user is not in the Domino Directory, and they have been authenticated by
CA Single Sign-Onagainst another user directory, then the Domino Web Agent identifies that user to the Domino server as the DominoDefaultUser.
The default user has default access to the Notes database, which means this person should have general access privileges such as Domino’s depositor, reader, or author level of access, configured in ACLs.
For the Domino Agent to use this value, set the SkipDominoAuth parameter to no.
There may be some Notes databases that do not require protection from
CA Single Sign-On. Resources that are not protected by
CA Single Sign-Onare not authenticated as the default Domino user. Instead, the Domino server prompts users for their credentials (if anonymous access is disabled).
Modify the Domino Default User and the Domino Super User
To modify the DominoDefaultUser and DominoSuperUser parameters, do one of the following:
- Change it in the Agent Configuration Object, if configuring centrallyYou can modify the DominoDefaultUser and DominoSuperUser settings in the Agent Configuration Object. You can choose whether the values are encrypted or in plain text.For more information, see the Policy Server documentation.
- Modify the parameters in the Agent configuration file using the encryptkey tool.In the Agent configuration file, the DominoDefaultUser and DominoSuperUser values must be encrypted. Consequently, you have to modify these values using the encryptkey tool.Do not edit these settings directly in the Agent configuration file.
Use Encryptkey to Set the Domino Default or Super User
To set or change the value of DominoSuperUser or DominoDefaultUser in the Agent configuration file
- Do one of the following:
- UNIX: Navigate to the Domino Agent's bin directory. For example:/$HOME/ca/SiteMinder/Web Agent/bin
- Windows: Open a command prompt window and navigate to the Domino Agent's Bin directory. For example:C:\Program Files\ca\SiteMInder Web Agent\Bin
- Run the encryptkey tool, using the following arguments:
For example:encryptkey -path "c:\program files\ca\SiteMinder\Web Agent\Bin\Lotus Domino5\webagent.conf"-dominoSuperUser adminThe path to the Agent configuration file must contain the file name, such as, webagent.conf. Also, if any value in the path contains spaces, the entire path must be surrounded by quotation marks.The encryptkey tool is not provided as a part of the Web Agent kit. However, the tool remains useful to Domino users who can manipulate it to generate encrypted DominoSuperUser settings for local configuration. You can contact Support to download a copy of this tool.
- For DominoSuperUser:encryptkey -pathpath_to_Agent_config_file-dominoSuperUsernew_value
- For DominoDefaultUser:encryptkey -pathpath_to_Agent_config_file-dominoDefaultUsernew_value
CA Single Sign-Onto Authenticate Users
CA Single Sign-On(and not Domino) authenticate users, set the SkipDominoAuth parameter to yes.
With SkipDominoAuth set to yes and a Super User defined,
CA Single Sign-Onfirst identifies and authorizes the user. The Domino Web Agent then identifies that user to the Domino Server as the Super User. As a Super User, the user has access to any resource on the Domino server, assuming the user has the appropriate ACLs.
You should also set SkipDominoAuth parameter to yes when users are not stored in the Domino Directory because Domino will not have an identity to use for authorization privileges.
If you set SkipDominoAuth to no, Domino authenticates users on its own using the actual user name or the default user name.
The following table shows how the setting of the SkipDominoAuth parameter affects how the user is identified.
Identified to the Domino Server As
Super User must be defined in the Domino Directory
User must be in the Domino Directory
User must be in the Domino Directory
The requested resource is automatically authorized, meaning that no authentication challenge will be presented to the user
CA Single Sign-OnHeader for Authentication
The DominoUseHeaderForLogin and DominoLookUpHeaderForLogin parameters can be used to identify a Domino user for authentication.
- DominoUseHeaderForLoginInstructs the Domino Web Agent to pass theCA Single Sign-Onheader value to the Domino Web Server. The Domino server uses the header data to identify a user in its user directory.Set this parameter to a header name. For example, if you specify DominoUseHeaderForLogin="HTTP_SM_USER", the Web Agent passes the user’s login name to the Domino server.
- DominoLookUpHeaderForLoginInstructs the Domino Web Agent to ask the Domino Web Server if the user requesting access to a resource is unique or ambiguous within the Domino user directory. This check is useful if a user named Jones tries accessing a resource and there are several users named Jones in the user directory. If this parameter is set to no, the Domino Web Agent does no checking with the Domino Web Server.Default:Yes
Disable Domino Session Authentication
CA Single Sign-Onprovides authentication and authorization functionality; therefore, the Domino session authentication feature is not needed. It should be disabled if the Web Agent is installed.
Under some conditions, having Domino session authentication enabled causes the user session to behave differently. This change in behavior does not affect security on a
CA Single Sign-On-enabled site. It reflects the intersection of
CA Single Sign-Onand Domino session management rules.
Use an Anonymous Authentication Scheme with Domino
To use an anonymous authentication scheme with a Domino agent, set the following parameter:
Specifies a value for anonymous users. This value is sent to the Domino server when users access Domino resources that are protected with an anonymous
CA Single Sign-Onauthentication scheme.
Default: No (anonymous authentication scheme
Example: Anonymous (use with anonymous authentication schemes)
The previous parameter applies only when using an anonymous authentication scheme with Domino. Do
notchange its value for other authentication schemes or server types.
Enable a Domino Agent to Collect Credentials for Authentication
A credential collector is an application within the Web Agent, which gathers user credentials for forms, SSL, and Windows authentication schemes, and for single sign-on across multiple cookie domains. The credentials gathered by the credential collector are based on the type of authentication scheme configured for a particular group of protected resources.
For a Domino Web Agent to act as a credential collector, you have to configure various MIME types, represented as file extensions in the Agent configuration file.
Credential collectors are generally auto-authorized, that is, when you add a file extension to these parameters, they are, by default, included in the IgnoreExt parameter. Domino Server cannot correctly process URLs that include files with these extensions, so the Domino Agent has to ignore these files.
For more information, see the Policy Server documentation.
Disable URL Normailization
The process of URL normalization modifies URLs from a Domino representation to a URL format used by a typical web browser. The Domino Web Agent relies on the Domino web server APIs to normalize a Domino URL.
During the normalization process, the Domino Server APIs periodically return a URL with a carriage return (0x0D in hex) and/or a line feed character (0x0A in hex) added to the normalized URL. The addition of these characters appears to be related to specific Notes database (.nsf) files and access patterns within these files.
The following example shows a normalized URL with an added carriage return:
- URL: http://server.ca.com:80/agentrunner.nsf/be68f4545348400461332?OpenView
- URL is mapped to: http://server.ca.com:80/agentrunner.nsf/AgentContext?OpenView
- URL is normalized to: http://xxxxx.ca.com:port/agentrunner.nsf/0x0d/AgentContext?OpenView
If necessary, you can ensure that URLs with Domino resource IDs are not normalized with the following parameter:
Specifies if the
CA Single Sign-OnWeb Agent converts Domino URLs to a URL-friendly name before redirecting them to a Forms Credential Collector.
The MapUrlsForRedirect parameter must also be set to yes for the Domino URLs to be converted.
If the DominoNormalizeUrls parameter is set to no, URLs will
notbe normalized, even if the MapUrlsForRedirect parameter is set to yes.
If you set the DominoNormalizeUrls parameter to no, you cannot protect individual documents within a Notes database; you can only protect the entire database or subdirectories of the Domino Web server.
To turn off normalization and ensure that URLs are not altered, set the DominoNormalizeUrls parameter to no.
Control Access to Lotus Notes Documents
The Web Agent offers a finer level of granularity for protecting Lotus Notes documents on Domino. The folloiwng parameter controls this protection:
Specifies how a Web Agent handles user requests for protected Lotus Notes documents in a Domino environment. Setting this parameter to yes grants users ReadForm permission only for the requested document.
Use the DominoLegacyDocumentSupport parameter to configure the Web Agent to process user-requested actions when accessing Notes documents. This offers a finer granularity of protection on Domino.
Notes documents do not have names. They are saved to the database with a reference to the form used to create them. When a user requests a Notes document, the Domino Web Agent finds the form for that document by converting the request into a URL. This URL includes the original Domino action. If no form is found, then nothing is used.
in the URL To ensure that the Web Agent performs the user-requested Domino action on the document that is specified in the URL, such as ?OpenDocument or ?EditDocument, set the DominoLegacyDocumentSupport parameter to no.
For example, if the URL request is:
The Domino Agent converts the preceding URL to:
where Person is the name of the form used to create the document identified by the NotesID in the original URL.
To force the Domino Web Agent revert back to its pre-4.6 operation for accessing Notes documents, which means that only the action ?ReadForm is permitted, set this parameter to yes. With the legacy document support enabled, the Domino Agent would convert the URL in the previous example to:
Convert Notes Document Names
Unlike views and forms, Notes documents do not have names; they are saved to the database with a reference to the form that was used to create the document. If a user is trying to access a document and the Domino Web Agent cannot convert it to a readable name, the Agent uses the name of the form that generated the document to create a URL. This applies only to documents. If there is no original form, the Agent uses the embedded form. If neither apply, the document is protected using the Domino identifier $defaultForm.
For example, if the incoming URL is:
The Agent uses:
In this example, Person is the name of the document.
Configure Full Logoff Support for Domino Agents
The full log-out feature uses a custom log-out page that you create with the following parameter:
- LogOffUriEnables the full log-out function by specifying the URI of a custom web page. This custom web page appears to users after they are successfully logged off. Configure this page so that it cannot be stored in a browser cache. Otherwise, a browser could possibly display a log-out page from its cache without logging the user off. If this situation happens, unauthorized users could possibly have an opportunity to assume control of a session.Default:(all agentsexceptthe CACA Single Sign-OnAgent for SharePoint r18.104.22.168) No defaultLimits:Multiple URI values permitted.Donotuse a fully qualified URL.Use arelativeURI.Example:(all agentsexceptthe CACA Single Sign-OnAgent for SharePoint r22.214.171.124) /Web pages/logoff.html
Follow these steps:
- Create a custom HTTP application that logs the user off. For example, add an Exit or Sign Off button that redirects the user to a URL you specify.
- Set up the log-out page so it cannot be cached in web browsers. This setting increases security because the page is always served from the web server, and not the cache of the browser. For example, for HTML pages, you can add the following meta tags to the page:< META HTTP-EQUIV="Pragma" CONTENT="no-cache">< META HTTP-EQUIV="Expires" CONTENT="-1">Important! Some web browsers do not support meta tags. Use a cache-control HTTP header instead.
- Configure the LogOffUri parameter with the following steps:
- Delete the pound sign (#), if necessary.
- Enter the URI of the custom HTTP file that will log the user off. Donotusea fully qualified URL.The full log-out feature is configured.
Use a Domino Agent with a WebSphere Application Server
A Domino web server acts as the front end to a WebSphere Application Server by providing a filter plug-in that intercepts requests before forwarding them to the WebSphere server.
Force Domino Server to Authenticate Unprotected Resources
Suppose you have resources on your Domino server that you not want to protect with
CA Single Sign-On. You can still protect those resources with your Domino server instead. To protect these resources, set the following parameter:
Specifies if the Domino server authenticates requests with a Domino user for resources that
onlythe Domino server (
CA Single Sign-On) protects.
If the value of this parameter is yes, the agent passes the Domino user to the Domino server. The Domino server authenticates the user. If the value of this parameter is no (or the parameter is disabled), the agent does
notpass the Domino user to the Domino server. The Domino server does not authenticate the user.
Follow these steps:
- Locate the previous parameter.
- Remove the # (comment) character in front of the parameter.
- Change the value of the parameter to yes.