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:

• 6.1 Access Manager SSO for Sun Java System Servers

• 6.2 Trusted Circle SSO (Legacy)

6.1 Access Manager SSO for Sun Java System Servers

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

• 6.1.1 SSO Limitations and Notices

• 6.1.2 Configuring Messaging Server to Support SSO

• 6.1.3 Troubleshooting SSO

6.1.1 SSO Limitations and Notices

• The Messenger Express session is only valid for as long as the Access Manager session is valid. If the user logs out of Access Manager the webmail session is automatically closed (single sign-off).

• SSO Applications working together must be in the same DNS domain. (Also known as cookie domain).

• SSO Applications must have access to Access Manager verification URL (naming service).

• Browsers must have cookies.

6.1.2 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.

6.1.3 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.

6.2 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:

• 6.2.1 Trusted Circle SSO Overview and Definitions

• 6.2.2 Trusted Circle SSO Applications

• 6.2.3 Trusted Circle SSO Limitations

• 6.2.4 Example Trusted Circle SSO Deployment Scenarios

• 6.2.5 Setting Up Trusted Circle SSO

• 6.2.6 Messenger Express Trusted SSO Configuration Parameters

6.2.1 Trusted Circle SSO Overview and Definitions

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

• SSO: Single Sign-On. The ability to sign on to one application and be able access the other applications. The user identification is the same throughout all applications.

• Trusted applications. Applications sharing the SSO scheme (SSO Prefix) and trusting each other’s cookies and verifications. Also known as Peer SSO applications.

• Trusted circle. The circle of trusted applications. They share the same SSO Prefix.

• SSO Prefix. A string defined by the person deploying SSO and made known to applications so they can use it to find cookies generated by other applications in the same trusted circle. Applications with different prefixes are not in the same circle and the user needs to re-authenticate when moving between these applications. The prefix sometimes, but not always, explicitly contains the trailing - (“-”) in the configuration setting.

• Application ID. (appid). A unique string defined by the person deploying SSO for each application in the SSO circle.

• SSO Cookie. A token that the browser uses to remember that the user has authenticated to some application. The name of the cookie is of the form SSO_prefix-application ID. The value of the cookie is the SSO key, usually a session ID generated by the application.

• Cookie Domain. A domain within which the application is restricted to send cookies. This is a domain in the DNS sense.

• Verification URL. A URL used by one application to verify the cookie it found to another application.

6.2.2 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, 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.

6.2.3 Trusted Circle SSO Limitations

• SSO Applications working together must be in the same domain.

• SSO Applications must have access to each other’s SSO verification URL.

• Browsers must support cookies.

• For security purposes, SSO should not be used on machines where the browser is run.

• To switch to a different identity, the browser needs to be restarted.

• Assuming single sign-off is enabled in both Messenger Express and for Sun Java System Calendar Server, if you log out of Sun Java System Calendar Server, then you are supposed to have to login again to Messenger Express. If you log out of Messenger Express, then you would have to login again into Sun Java System Calendar Server. However, it currently does not work this way. You may stay logged into one after logging out of another.

6.2.4 Example Trusted Circle SSO Deployment Scenarios

The simplest SSO deployment scenario consists of only Messenger Express and Delegated Administrator. 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

An even more complex deployment would include Webmail Servers and load balancers.

Figure 6–2 Complex SSO Deployment

6.2.5 Setting Up Trusted Circle SSO

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

To Set Up SSO for Messenger Express, Delegated Administrator, and Calendar Manager

1. Configure Messenger Express for SSO.

   1. Set the appropriate SSO configutil parameters.

      To enable single sign-on for Messenger Express with Delegated Administrator, set the configuration parameters as follows (assumes your default domain is siroe.com). 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 Delegated Administrator, although you can choose a different prefix, using the default would save a little typing when configuring Delegated Administrator and Calendar Server.

      configutil -o local.webmail.sso.id -v ims5

      ims5 is a name you pick to identify Messenger Express (ME) to other applications.

      configutil -o local.webmail.sso.cookiedomain -v “.siroe.com”

      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 xyz.com, 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 \ "http://ApplicationHost:port/VerifySSO?"

      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 application. Example:

      configutil -o local.sso.ida.verifyurl -v \ "http://siroe.com:8080/VerifySSO?"

   2. Restart Messenger Express http server after changing the configuration.

      cd instance_root./stop-msg http ./start-msg http

2. Configure Directory Server for SSO.

   1. Create a proxy user account in the directory.

      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 mysystem.siroe.com -D "cn=Directory Manager" -w password -v -f proxy.ldif

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

   2. Create the appropriate ACIs for proxy user account authentication.

      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=siroe.com, o=isp";)

      ldapmodify -h siroe.com -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=siroe.com, o=isp";)

      ldapmodify -h siroe.com -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 resource.properties file.

      Uncomment and modify the following entries in the Delegated Administrator resource.properties file:

      LDAPDatabaseInterface-ldapauthdn=Proxy_Auth_DN LDAPDatabaseInterface-ldapauthpw=Proxy_Auth_Password NDAAuth-singleSignOnId=SSO_Prefix- NDAAuth-applicationId=DelAdminID

      For example:

      LDAPDatabaseInterface-ldapauthdn= uid=proxy,ou=people,o=cesta.com,o=isp LDAPDatabaseInterface-ldapauthpw=proxypassword NDAAuth-singleSignOnId=ssogrp1- NDAAuth-applicationId=ida

      The resource.properties file is stored in the following location:

      iDA_svr_base/nda/classes/netscape/nda/servlet/

   2. Add the participating server’s verification URL.

      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 resource.properties file and add an entry such as:

      verificationurl-ssogrp1-msg5=http://webmail_hostname:port/VerifySSO? verificationurl-ssogrp1-ida=http://iDA_hostname:port/VerifySSO? verificationurl-ssogrp1-ics50=http://iCS_hostname:port/VerifySSO?

      The resource.properties file is located in the following directory:

      iDA_svr_base/nda/classes/netscape/nda/servlet/

4. Add Delegated Administrator single sign-on cookie information and enable UTF8 Parameter Encoding.

   1. Define a context identifier for Delegated Administrator.

      Edit the servlets.properties file and uncomment all lines containing the text servlet.*.context=ims50. Where * is any string.

      The servlets.properties file is located at:

      Web_Svr_Base/https-instancename/config/

   2. Specify a cookie name for the context in the Enterprise Server configuration.

      Edit the Enterprise Server contexts.properties file and add the following line to the bottom of the file before the #IDACONF-Start line:

      context.ims50.sessionCookie=ssogrp1-ida

      The contexts.properties file is located at:

      Web_Svr_Base/https-instancename/config/

   3. Enable UTF8 parameter encoding for ims5 contexts.

      To Enable UTF8 Parameter Encoding for ims5 Contexts in the Enterprise Server configuration add the following entry to the Enterprise Server contexts.properties file:

      context.ims50.parameterEncoding=utf8

5. Restart Messenger Express.

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

   Web_Svr_Base/https-instance_name/stop Web_Svr_Base/https-instancename/start

6. If you are deploying Calendar in this SSO group, configure Calendar Server.

   Edit ics.conf and add the following:

   sso.appid = "ics50" sso.appprefix = "ssogrp1" sso.cookiedomain = ".red.iplanet.com" sso.enable = "1" sso.singlesignoff = "true" sso.userdomain = "mysystem.red.iplanet.com" sso.ims5.url="http://mysystem.red.iplanet.com:80/VerifySSO?" sso.ida.url=http://mysystem.red.iplanet.com:8080/VerifySSO?

7. Restart Calendar Server

   start-cal

8. Restart the Messenger Express http server:

   msg-svr-base/sbin/stop-msg http msg-svr-base/sbin/start-msg http

6.2.6 Messenger Express Trusted SSO Configuration Parameters

You can modify the single sign-on configuration parameters for Messenger Express, shown in 6.2.6 Messenger Express Trusted SSO Configuration Parameters, by using the configutil command. For more information about configutil, see the Sun Java System Messaging Server 6.3 Administration Reference

local.webmail.sso.
cookiedomain

Verifycationurl-XXX-YYY=http://webmailhost:
webmailport/VerifySSO?

local.webmail.sso.
singlesignoff