Creating a Web SSO configuration document

The Web SSO configuration document is a domain-wide configuration document stored in the HCL Domino® Directory. This document, which should be replicated to all Domino® servers participating in the single sign-on domain, is encrypted for participating servers and administrators, and contains a shared secret key used by servers for verifying user credentials.

To create a Web SSO configuration document if you are using Internet Sites

Before you begin

Make sure you have created a Web Site document, and enabled the use of Internet Site documents in the Server document.

Also make sure that your client location document has the home/mail server set to a server in the same domain as the servers participating in SSO. This ensures that all public keys for participating server can be found when the SSO document is encrypted.

Procedure

  1. In the Domino® Administrator, click Files, and open the server's Domino® Directory (usually NAMES.NSF).
  2. Select the Internet Sites view.
  3. Click Create Web SSO Configuration.
  4. In the document, click Keys.
  5. Initialize the Web SSO Configuration with the shared secret key in one of two ways:
    • Choose Domino only (no IBM® WebSphere® servers participating in single sign-on), and then select Create Domino SSO Key. If you choose this option, do not complete Step 6, instead go to Step 7.
    • Choose Domino and WebSphere (single sign-on with WebSphere®), and then continue to Step 6.
  6. Complete the rest of the document as follows:
    Table 1. Domino® and WebSphere® SSO configuration fields

    Field

    Action

    Configuration Name

    Enter the name of the SSO configuration keeping the following points in mind:

    • If you create multiple Web SSO Configuration documents, be sure to give each document a unique name. Web SSO documents are located by name and if multiple documents have the same name, the SSO configurations do not work well. However, creating multiple SSO documents can only work under limited circumstances. Multiple SSO documents are not recognized by all protocols. In particular, SSO involving Java™ agents and other components using the local Java™ back-end classes will not function if a name other than the default LtpaToken is used.
    • If the single sign-on configuration is a mixed-release configuration that includes Release 5.0x servers, the Configuration Name must be LtpaToken, as Release 5.0x servers only work with this configuration name.

    Organization Name

    (Required) Enter the name of the organization. This must match the organization name for the corresponding Web site. The SSO document will then appear in the Internet sites view, along with the Web Sites documents.

    DNS Domain

    (Required) Enter the DNS domain (for example -- .renovations.com) for which the tokens will be generated. The servers enabled for single sign-on must all belong to the DNS domain you specify.

    When you enter the DNS domain, be sure you type the initial period. For example, do not enter renovations.com; instead you should enter .renovations.com.

    If the SSO domain includes WebSphere® servers, WebSphere® treats the DNS domain as case-sensitive, so ensure that the DNS domain value is specified with appropriate case.

    Map names in LTPA token

    Enable this option to map the user name that appears in a Domino-created LTPA token to the user's name that is expected by WebSphere® SSO servers. You should enable this setting if you have a mixed Domino® and Websphere environment, and if it is the case that Domino® and WebSphere® do not share the same directory.

    Do not enable this option if you want Domino-created LTPA tokens to continue to contain the user's Domino® distinguished name.

    Domino® Server Names

    Enter the names of the Domino® servers that will be participating in single sign-on (for example -- server1/renovations, server2/renovations). This document will be encrypted for the creator of the document, the members of the Owners and Administrators fields, and the servers specified in the Domino Server Names field.

    Groups, wildcards, and the names of WebSphere® servers are not allowed in this field. Only Domino® servers can be listed as participating servers in the Server Names field.

    Note: There is a 64K-size limit on this field. An error message appears when the limit is reached, such as when the names of several hundreds of servers are entered. It is recommended that you create more than one Web SSO Document if this limit is reached.

    Windows™ single sign-on integration

    Enable this option to allow Domino® servers to use Windows™ single sign-on for Web clients.

    LtpaToken Custom Cookie name

    If you are not using the default name LtpaToken as the browser cookie name, enter a custom name for Domino to use with the browser cookie.

    Note: If you selected a Token Format that did not include LtpaToken, this option does not appear.
    Tip: This custom name is useful for compatibility with HCL Digital Experience.

    The cookie name cannot begin with a dollar-sign character, and cannot contain underscore, comma, semicolon or white space characters. Some browsers cannot process non-ASCII characters and might also have designated special characters that cannot be used. Domino limits the cookie name to 128 characters.

    LtpaToken2 Custom Cookie name

    If you are not using the default name LtpaToken2 as the browser cookie name, enter a custom name for Domino to use with the browser cookie.

    Note: If you selected a Token Format that did not include LtpaToken2, this option does not appear.
    Tip: This custom name is useful for compatibility with HCL Digital Experience.

    The cookie name cannot begin with a dollar-sign character, and cannot contain underscore, comma, semicolon or white space characters. Some browsers cannot process non-ASCII characters and might also have designated special characters that cannot be used. Domino limits the cookie name to 128 characters.

    LDAP realm

    		 The value of this field is read from the WebSphere key file. Edit this field only if directed to do so by support.

    Expiration (minutes)

    Specify the time period, in minutes, for which the token will be valid. This time period begins at the time the token is issued. The token is valid for only the number of minutes specified. Default is 30 minutes.

    Note: If an Idle Session Timeout is configured, the session may timeout (based on inactivity) at a time earlier than that specified by the expiration.

    Idle Session Timeout

    (Domino-only SSO configuration) Enable this option to end a user's SSO session if there is no activity for a specified amount of time, and then provide a Minimum Timeout value.

    Note: If you chose to import Websphere LTPA keys, this option will not appear on the Web SSO Configuration document.

    Minimum Timeout (minutes)

    If you enabled Idle Session Timeout, this option appears. Specify the length of time, in minutes, that a user's session must show no activity before timing out.

    If you imported Websphere LTPA keys, complete these fields:

    Table 2. Websphere LTPA key fields

    Field

    Action

    Token format

    Choose one of the following:

    • LtpaToken (compatible with Domino® 7 and prior releases)
    • LtpaToken2 (incompatible with Domino® 7 and prior releases, but provides SSO security improvements)
    • LtpaToken and LtpaToken2 (compatible with all releases of Domino®)
    Note: The LtpaToken2 format was introduced in IBM® WebSphere® Server release 5.1.1. Support for this token improves security for SSO deployments.

    LDAP realm

    Specify the LDAP realm in this format: 

    fully-qualified-host-name:port

    This realm must be the same for all participating servers for the LTPA token mechanism to work.

    LTPA Version

    The value of this field is read from the WebSphere® key file.

  7. Save the Web SSO Configuration document. A message on the status bar indicates the number of servers/people for whom the document was encrypted. The document(s) will appear in the Internet Sites view.

To create a Web SSO configuration document if you are using the Web Server Configurations view

About this task

Use this procedure to create a Web SSO configuration document if your server is a Release 5.0x server, or if you are using Domino® 6 or higher but you do not use Web Site documents to manage your Web sites.

Procedure

  1. In the Domino® Administrator, click Files, and open the server's Domino® Directory (usually NAMES.NSF).
  2. Select the Servers view.
  3. Click Create Web SSO Configuration.
  4. In the Web SSO Configuration document, click Keys.
  5. Initialize the Web SSO Configuration with the shared secret key in one of two ways:
    • Choose Domino only (no WebSphere® servers participating in single sign-on), and then select Create Domino SSO Key. If you choose this option, do not complete Step 6, instead go to Step 7.
    • Choose Domino and WebSphere (single sign-on with WebSphere®), and then continue to Step 6.
  6. Complete the rest of the document as follows:
    Table 3. Domino® and WebSphere® SSO configuration fields

    Field

    Action

    Configuration Name

    Enter the name of the SSO configuration keeping the following points in mind:

    • If you create multiple Web SSO Configuration documents, be sure to give each document a unique name. Web SSO documents are located by name and if multiple documents have the same name, the SSO configurations won't work well. However, creating multiple SSO documents can only work under limited circumstances. Multiple SSO documents are not recognized by all protocols. In particular, SSO involving Java™ agents and other components using the local Java™ back-end classes will not function if a name other than the default LtpaToken is used.
    • If the single sign-on configuration is a mixed-release configuration that includes Release 5.0x servers, the Configuration Name must be LtpaToken, as Release 5.0x servers only work with this configuration name.

    Organization Name

    Leave this field blank, and this document will appear in the Web Configurations view.

    DNS Domain

    (Required) Enter the DNS domain (for example, .renovations.com) for which the tokens will be generated. The servers enabled for single sign-on must all belong to the same DNS domain.

    When you enter the DNS domain, be sure you type the initial period. For example, do not enter renovations.com; instead you should enter .renovations.com.

    If the SSO domain includes WebSphere® servers, WebSphere® treats the DNS domain as case-sensitive, so ensure that the DNS domain value is specified with appropriate case.

    Map names in LTPA token

    Enable this option to map the user name that appears in a Domino-created LTPA token to the user's name that is expected by WebSphere® SSO servers. You should enable this setting if you have a mixed Domino® and Websphere environment, and if it is the case that Domino® and WebSphere® do not share the same directory.

    Do not enable this option if you want Domino-created LTPA tokens to continue to contain the user's Domino® distinguished name.

    Domino® Server Names

    Enter the names of the Domino® servers that will be participating in single sign-on (for example -- server1/renovations, server2/renovations). This document will be encrypted for the creator of the document, the members of the Owners and Administrators fields, and the servers specified in the Domino® Server Names field.

    Note: Groups, wildcards, and the names of WebSphere® servers are not allowed in this field. Only Domino® Servers can be listed as participating servers in the Server Names field.

    Windows™ single sign-on integration

    Enable this option to allow Domino® servers to use Windows™ single sign-on for Web clients.

    LtpaToken Custom Cookie name

    If you are not using the default name LtpaToken as the browser cookie name, enter a custom name for Domino to use with the browser cookie.

    Note: If you selected a Token Format that did not include LtpaToken, this option does not appear.
    Tip: This custom name is useful for compatibility with HCL Digital Experience.

    The cookie name cannot begin with a dollar-sign character, and cannot contain underscore, comma, semicolon or white space characters. Some browsers cannot process non-ASCII characters and might also have designated special characters that cannot be used. Domino limits the cookie name to 128 characters.

    LtpaToken2 Custom Cookie name

    If you are not using the default name LtpaToken2 as the browser cookie name, enter a custom name for Domino to use with the browser cookie.

    Note: If you selected a Token Format that did not include LtpaToken2, this option does not appear.
    Tip: This custom name is useful for compatibility with HCL Digital Experience.

    The cookie name cannot begin with a dollar-sign character, and cannot contain underscore, comma, semicolon or white space characters. Some browsers cannot process non-ASCII characters and might also have designated special characters that cannot be used. Domino limits the cookie name to 128 characters.

    Expiration (minutes)

    Specify the time period, in minutes, for which the token will be valid. This time period begins at the time the token is issued. The token is valid for only the number of minutes specified. Default is 30 minutes.

    Note: If an Idle Session Timeout is configured, the session may timeout (based on inactivity) at a time earlier than that specified by the expiration.

    Idle Session Timeout

    Enable this option to end a user's SSO session if there is no activity for a specified amount of time, and then provide a Minimum Timeout value.

    Note: If you chose to import Websphere LTPA keys, this option will not appear on the Web SSO Configuration document.

    Minimum Timeout (minutes)

    If you enabled Idle Session Timeout, this option appears. Specify the length of time, in minutes, that a user's session must show no activity before timing out.

    If you imported Websphere LTPA keys, complete these fields:

    Table 4. Websphere LTPA key fields

    Field

    Action

    Token format

    Choose one of the following:

    • LtpaToken (compatible with Domino® 7 and prior releases)
    • LtpaToken2 (incompatible with Domino® 7 and prior releases, but provides SSO security improvements)
    • LtpaToken and LtpaToken2 (compatible with all releases of Domino®)
    Note: The LtpaToken2 format was introduced in IBM® WebSphere® Server release 5.1.1. Support for this token improves security for SSO deployments.

    LDAP realm

    Specify the LDAP realm in this format: 

    <fully-qualified-host-name>:<port>

    This realm must be the same for all participating servers for the LTPA token mechanism to work.

    LTPA Version

    The value of this field is read from the WebSphere® key file.
  7. Save the Web SSO Configuration document. A message on the status bar indicates the number of servers/people for whom the document was encrypted. The document(s) will appear in the Web Server Configurations view.
    Note: If you receive messages on the client indicating that a particular key was not found for encrypting the document, you may have to change your client's location document to point to a different mail/directory server that will have all the public keys included in server and person documents.