Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Messaging Server 6 2005Q1 Administration Guide 

Chapter 6
Enabling Single Sign-On (SSO)

Single sign-on is the ability for an end user to authenticate once (that is, log on with user ID and password) and have access to multiple applications. The Sun Java System Access Manager (note that this used to be called Identity Server) is the official gateway used for SSO for Sun Java System servers. That is, users must log into Access Manager to get access to other SSO configured servers.

For example, when properly configured, a user can sign in at the Sun Java System Access Manager login screen and have access to Messenger Express, in another window without having to sign in again. Similarly, if the Sun Java System Calendar Server is properly configured, a user can sign in at the Sun Java System Access Manager login screen, then have access to their Calendar in another window without having to sign in again.

It should be noted that Messaging Server provides two methods of deploying SSO. The first way is through the Sun Java System Access Manager, the second way is through communications servers trusted circle technology. Using a trusted circle is the legacy method of implementing SSO. Though this method provides some features not available with Access Manager SSO, we do not recommend using it since all future development will be with the Access Manager. Both methods, however, are described in the following sections:

Access Manager SSO for Sun Java System Servers

This section describes SSO using Access Manager. It consists of the following sections:

SSO Limitations and Notices

Configuring Messaging Server to Support SSO

Four configutil parameters support Messaging Server SSO. Of these four, only one, local.webmail.sso.amnamingurl is required to enable SSO with Messaging Server. To enable SSO, set this parameter to the URL where Access Manager runs the naming service. Typically this URL is http://server/amserver/namingservice. Example:

configutil -o local.webmail.sso.amnamingurl -v http://sca-walnut:88/amserver/namingservice


Access Manager SSO does not look at local.webmail.sso.enable which enables the older SSO mechanism. local.webmail.sso.enable should be left to off or unset otherwise warning messages will be logged about missing configuration parameters which are needed for the old SSO mechanism.

You can modify the SSO configuration parameters shown in Table 6-3, by using the configutil command.

Table 6-1  Access Manager Single Sign-On Parameters




The URL where Access Manager runs the naming service. Mandatory variable for single sign-on through Access Manager. Typically this URL is http://server/amserver/namingservice.

Default: Not set.


Access Manager cookie name. If Access Manager is configured to use another cookie name, then that name needs to be configured in Messaging Server as local.webmail.sso.amcookiename so that Messaging Server knows what to look for when doing single-sign on. Default value is iPlanetDirectoryPro and must not be changed if Access Manager has the default configuration.

Default: iPlanetDirectoryPro


AMSDK logging level. The SSO library used by Messaging Server has its own logging mechanism separate from Messaging Server. Its messages are logged in a file called http_sso under msg_svr_base/log. By default only messages with info or higher are logged, but it is possible to increase the logging level by setting the logging level to a value from 1 to 5 (1 = errors, 2 = warnings, 3 = info, 4 = debug, 5 = maxdebug). Be aware that the library doesn’t have the same notion of message importances as Messaging Server and that setting the level to debug can result in a lot of meaningless data. Also the http_sso log file is not managed by common Messaging Server logging code and is never cleaned up or rolled over. It is the responsibility of the system administrator to clean it up when setting the log level higher than the default.

Default: 3


Single sign-off from Messaging Server to Access Manager. Access Manager is the central authentication authority, and single sign-off is always enabled from Access Manager to Messaging Server. This option allows a site to configure whether the logout button in webmail should also log the user out of Access Manager (saving some customization work). By default this is enabled. If this is disabled, a user logging out of the default webmail client is automatically logged back in since logout refers to the root document and the root document refers to the inbox display as long as the Access Manager cookie exists and is valid. Therefore, a site choosing to disable this option needs to customize what happens at webmail logout.

Default: yes

Troubleshooting SSO

If there is a problem with SSO, the first thing to do is check the webmail log file msg_svr_base/log/http for errors. Increasing the logging level may be helpful (configutil -o logfile.http.loglevel -v debug). If this does not help, then check the amsdk messages in msg_svr_base/log/http_sso, then increase the amsdk logging level (configutil -o local.webmail.sso.amloglevel -v 5). Note that new logging levels only take effect after server restart.

If SSO is still having problems, make sure you are using fully qualified host names of both Access Manager and Messaging Server during log in. Cookies are only shared between servers of the same domain, and browsers do not know what the domain is for local server names, so one must use the fully qualified names in the browser for SSO to work.

Trusted Circle SSO (Legacy)

This section describes trusted circle SSO. We do not recommend using this method of SSO since all future development will be with the Access Manager. However, there is some functionality available with trusted circle SSO that is not available with Access Manager SSO at this time.This section consists of the following sections:

Trusted Circle SSO Overview and Definitions

Before deploying SSO it is important to understand the following terminology.

Trusted Circle SSO Applications

Before implementing SSO, you must first consider which applications will be in this trusted circle. The applications which can be in this trusted circle are Messenger Express (with or without Messenger Express Multiplexor), Calendar Express, and the old iPlanet Delegated Administrator for Messaging (not recommended because it only supports Sun LDAP Schema 1).

Table 6-2 shows which applications can be accessed from each other via SSO. From a user’s point of view, logging into one of the applications on the first column, SSO works if the user is able to access application across the top row without having to re-enter user id and passwords.

Table 6-2  SSO Interoperability




Calendar Express

Messenger Express

Messenger Express Multiplexor

Delegated Administrator

Calendar Express





Messenger Express





Messenger Express Multiplexor





Delegated Administrator





Trusted Circle SSO Limitations

Example Trusted Circle SSO Deployment Scenarios

The simplest SSO deployment scenario consists of only Messenger Express and iPlanet Delegated Administrator for Messaging. A more complicated scenario can be created by adding Calendar Express—on the same machine or a different machine—using the same SSO prefix so they are in the same trusted circle. This is shown in Figure 6-1.

Figure 6-1  Simple SSO Deployment

Graphic shows a simple SSO deployment with three applications under a single SSO prefix.

An even more complex deployment would include Messenger Express Multiplexors and load balancers.

Figure 6-2  Complex SSO Deployment

Graphic shows a complex SSO deployment with seven server applications.

Setting Up Trusted Circle SSO

This section describes setting up SSO for Messenger Express, iPlanet Delegated Administrator for Messaging, and Calendar Manager.

  1. Configure Messenger Express for SSO.
    1. Set the appropriate SSO configutil parameters.
    2. To enable single sign-on for Messenger Express with Delegated Administrator, set the configuration parameters as follows (assumes your default domain is These parameters are described in Table 6-3. You must be root user. cd to instance_root

      configutil -o local.webmail.sso.enable -v 1
      configutil -o local.webmail.sso.prefix -v ssogrp1
            ssogrp1 is the default SSO Prefix used by iDA, although you can choose a different prefix,
            using the default would save a little typing when configuring iDA and iCS.
      configutil -o -v ims5
            ims5 is a name you pick to identify Messenger Express (ME) to other applications.
      configutil -o local.webmail.sso.cookiedomain -v “”
            The above domain must match the domain used by the ME/browser client to connect to
            the servers. Thus, although the hosted domain on this server may be called, we
            must use a real domain in the DNS. This value must start with a period.
      configutil -o local.webmail.sso.singlesignoff -v 1
      configutil -o local.sso.
      ApplicationID.verifyurl -v \
            ApplicationID is a name we give to the SSO application (example: ida for Delegated
            Administrator, ics50 for Calendar Server). ApplicationHost:port is the host and port number of the
            application. You will have one of these lines for each non-Messaging Server applcation. Example:
            configutil -o local.sso.ida.verifyurl -v \

    3. Restart Messenger Express http server after changing the configuration.
    4. cd instance_root
      ./stop-msg http
      ./start-msg http

  2. Configure Directory Server for SSO.
    1. Create a proxy user account in the directory.
    2. The proxy user account allows the Delegated Administrator to bind to the Directory Server for proxy authentication. Using the following LDIF code (proxy.ldif) you could create a proxy user account entry using ldapadd.

      ldapadd -h -D "cn=Directory Manager" -w password -v -f proxy.ldif

      dn: uid=proxy, ou=people,, o=isp
      objectclass: top
      objectclass: person
      objectclass: organizationalperson
      objectclass: inetorgperson
      uid: proxy
      givenname: Proxy
      sn: Auth
      cn: Proxy Auth
      userpassword: proxypassword

    3. Create the appropriate ACIs for proxy user account authentication.
    4. Using the ldapmodify utility, create an ACI for each of the suffixes you created at the time you installed the Delegated Administrator.

      osiroot - The suffix you entered to store the user data (the default is o=isp). osiroot is the root of the Organization Tree.

      dcroot - The suffix you entered to store the domain information. (The default is o=internet.)

      osiroot - The suffix you entered to store the configuration information, it should have been the same value you entered to store the user data.

      The following is an example of an ACI entry (aci1.ldif) for the osiroot for the proxy user created earlier:

      dn: o=isp
      changetype: modify
      add: aci
      aci: (target="ldap:///o=isp")(targetattr="*")(version 3.0; acl
      "proxy";allow (proxy) userdn="ldap:///uid=proxy, ou=people,, o=isp";)

      ldapmodify -h -D "cn=Directory Manager" -w password -v -f aci1.ldif

      Create a similar ACI entry (aci2.ldif)for the dcroot:

      dn: o=internet
      changetype: modify
      add: aci
      aci: (target="ldap:///o=internet")(targetattr="*")(version 3.0; acl "proxy";allow (proxy) userdn="ldap:///uid=proxy, ou=people,, o=isp";)

      ldapmodify -h -D "cn=Directory Manager" -w password -v -f aci2.ldif

  3. Configure the Delegated Administrator
    1. Add the proxy user credentials and cookie name for context to the Delegated Administrator file.
    2. Uncomment and modify the following entries in the Delegated Administrator iDA_server_root/nda/classes/netscape/nda/servlet/ file:


      For example:

         uid=proxy, ou=people,, o=isp

    3. Add the participating server’s verification URL.
    4. To verify a single sign-on cookie it receives, Delegated Administrator must know who to contact. You must provide a verification URL for all known participating servers.

      Following the example, assume Messenger Express is installed and its application ID is msg5. Edit the Delegated Administrator iDA_server_root/nda/classes/netscape/nda/servlet/ file and add an entry such as:


  4. Add Delegated Administrator single sign-on cookie information and enable UTF8 Parameter Encoding.
    1. Define a context identifier for Delegated Administrator.
    2. Edit Web_Server_Root/https-instancename/config/ and uncomment all lines containing the text servlet.*.context=ims50. Where * is any string.

    3. Specify a cookie name for the context in the Enterprise Server configuration.
    4. Edit the Enterprise Server file Web_Server_Root/https-instancename/config/ and add the following line to the bottom of the file before the #IDACONF-Start line:


    5. Enable UTF8 parameter encoding for ims5 contexts.
    6. To Enable UTF8 Parameter Encoding for ims5 Contexts in the Enterprise Server configuration add the following entry to the Enterprise Server WebServer_Root/https-instancename/config/ file:


  5. Restart Messenger Express.
  6. After you’ve made the configuration changes described in steps 1a through 2c, you must restart Messenger Express for the changes to take effect:


  7. If you are deploying Calendar in this SSO group, configure Calendar Server.
  8. Edit ics.conf and add the following:

    sso.appid = "ics50"
    sso.appprefix = "ssogrp1"
    sso.cookiedomain = ""
    sso.enable = "1"
    sso.singlesignoff = "true"
    sso.userdomain = ""

  9. Restart Calendar Server
  10. start-cal

  11. Restart the Messenger Express http server:
  12. msg_svr_base/sbin/stop-msg http
    msg_svr_base/sbin/start-msg http

Messenger Express Trusted SSO Configuration Parameters

You can modify the single sign-on configuration parameters for Messenger Express, shown in Table 6-3, by using the configutil command. For more information about configutil, see the Messaging Server Reference Manual.

Table 6-3  Trusted Circle Single Sign-On Parameters




Sets the verify URL values for peer SSO applications. appid is the application ID of a peer SSO application whose SSO cookies are to be honored. For example, the default appid for Delegated Administrator is nda45.Its actual value is specified by the Delegated Administrator file entry NDAAuth-applicationID.

There should be one parameter defined for each trusted peer SSO application. The standard form of the verify URL is:


If you are using a load balancer in front of multiple Messenger Express Multiplexors and Message Store servers (running Messenger Express) or Calendar front ends, be sure to assign a different appid for each physical system with the real host names in the verifyurl. This will ensure that the correct system will be used to verify the cookie


The string value of this parameter is used to set the cookie domain value of all SSO cookies set by the Messenger Express HTTP server. The default value is null.

This domain must match the DNS domain used by the Messenger Express browser to access the server. It is not the hosted domain name.


Enables or disables all single sign-on functionality, including accepting and verifying SSO cookies presented by the client when the login page is fetched, returning an SSO cookie to the client on successful login and responding to requests from other SSO partners to verify its own cookies.

If set to any non-zero value, the server performs all SSO functions.

If set to zero, the server does not perform any of these SSO functions.

The default value is zero.

The string value of this parameter is used as the application ID value when formatting SSO cookies set by the Messenger Express HTTP server. The default value is null.

This is an arbitrary string. Its value must match what you specify for the Delegated Administrator in its file. The corresponding entry in would be:


Where XXX is the local.webmail.sso.prefix value set above, and YYY is the value of set here.


The string value of this parameter is used as the prefix value when formatting SSO cookies set by the Messenger Express HTTP server. Only SSO cookies with this prefix will be recognized by the server; all other SSO cookies will be ignored.

A null value for this parameter effectively disables all SSO functionality on the server.

The default value is null.

This string must match what’s used by the iPlanet Delegated Administrator for Messaging in its file without the trailing -. For example, if:


Then this value should be set here to ssogrp1.


The integer value of this parameter, if set to any non-zero value, clears all SSO cookies on the client with prefix values matching the value configured in local.webmail.sso.prefix when the client logs out.

If set to zero, Messenger Express will clear its own SSO cookie when the client logs out.

The default value is zero.

Previous      Contents      Index      Next     

Copyright 2005 Sun Microsystems, Inc. All rights reserved.