Chapter 4 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 One Identity Server is the official gateway used for SSO for Sun ONE servers. That is, users must log into Identity Server to get access to other SSO configured servers.

For example, when properly configured, a user can sign in at the Sun One Identity Server login screen and have access to Messenger Express, in another window without having to sign in again. Similarly, if the Sun ONE Calendar Server is properly configured, a user can sign in at the Sun One Identity Server 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 One Identity Server, 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 Identity Server SSO, we do not recommend using it since all future development will be with the Identity Server. Both methods, however, are described in the following sections:

"Identity Server SSO for Sun ONE Servers"

"Trusted Circle SSO (Legacy)"

Identity Server SSO for Sun ONE Servers

This section describes SSO using Identity Server. It consists of the following sections:

"SSO Limitations and Notices"

"Configuring Messaging Server to Support SSO"

"Troubleshooting SSO"

SSO Limitations and Notices

The Messenger Express session is only valid for as long as the Identity Server session is valid. If the user logs out of Identity Server 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 Identity Server verification URL (naming service).

Browsers must have cookies.

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 Identity Server 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


Note	Identity Server 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 4-3, by using the configutil command.

Table 4-1 Identity Server Single Sign-On Parameters
Parameter	Description
local.webmail.sso.amnamingurl	The URL where Identity Server runs the naming service. Mandatory variable for single sign-on through Identity Server. Typically this URL is http://<server>/amserver/namingservice. Default: Not set.
local.webmail.sso.amcookiename	Identity Server cookie name. If Identity Server 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 Identity Server has the default configuration. Default: iPlanetDirectoryPro
local.webmail.sso.amloglevel	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
local.webmail.sso.singlesignoff	Single sign-off from Messaging Server to Identity Server. Identity Server is the central authentication authority, and single sign-off is always enabled from Identity Server to Messaging Server. This option allows a site to configure whether the logout button in webmail should also log the user out of Identity Server (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 Identity Server 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 Identity Server 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 Identity Server. However, there is some functionality available with trusted circle SSO that is not available with Identity Server SSO at this time.This section consists of the following sections:

"Trusted Circle SSO Overview and Definitions"

"Trusted Circle SSO Applications"

"Trusted Circle SSO Limitations"

"Example Trusted Circle SSO Deployment Scenarios"

"Setting Up Trusted Circle SSO"

"Messenger Express Trusted SSO Configuration Parameters"

Trusted Circle SSO Overview and Definitions

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.

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 ONE LDAP Schema, v.1).

Table 4-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.

Trusted Circle SSO Limitations

Table 4-2 SSO Interoperability
To: From:	Calendar Express	Messenger Express	Messenger Express Multiplexor	Delegated Administrator
Calendar Express	SSO	SSO	SSO	SSO
Messenger Express	SSO	N/A	N/A	SSO
Messenger Express Multiplexor	SSO	N/A	N/A	SSO
Delegated Administrator	SSO	SSO	SSO	N/A

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 ONE Calendar Server, if you log out of Sun ONE 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 ONE Calendar Server. However, it currently does not work this way.You may stay logged into one after logging out of another.

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 4-1.

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

Setting Up Trusted Circle SSO

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

Configure Messenger Express for SSO.

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 4-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 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 applcation. Example:
      configutil -o local.sso.ida.verifyurl -v \
         “http://siroe.com:8080/verifySSO?”

Restart Messenger Express http server after changing the configuration.

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

Configure Directory Server for SSO.

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.

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

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

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

Configure the Delegated Administrator

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 iDA_server_root/nda/classes/netscape/nda/servlet/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=siroe.com, o=isp
LDAPDatabaseInterface-ldapauthpw=proxypassword
NDAAuth-singleSignOnId=ssogrp1-
NDAAuth-applicationId=ida

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 iDA_server_root/nda/classes/netscape/nda/servlet/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?

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

Define a context identifier for Delegated Administrator.

Edit Web_Server_Root/https-instancename/config/servlets.properties and uncomment all lines containing the text servlet.*.context=ims50. Where * is any string.

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

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

context.ims50.sessionCookie=ssogrp1-ida

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 WebServer_Root/https-instancename/config/contexts.properties file:

context.ims50.parameterEncoding=utf8

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:

WebServer_Root/https-iinstance_name/stop
WebServer_Root/https-instancename/start

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?

Restart Calendar Server

start-cal

Restart the Messenger Express http server:

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 4-3, by using the configutil command. For more information about configutil, see the Messaging Server Reference Manual.

Table 4-3 Trusted Circle Single Sign-On Parameters
Parameter	Description
local.webmail.sso.enable	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.
local.webmail.sso.prefix	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 resource.properties file without the trailing -. For example, if: NDAAuth-singleSignOnID=ssogrp1- Then this value should be set here to ssogrp1.
local.webmail.sso.id	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 resource.properties file. The corresponding entry in resource.properties would be: Verifycationurl-XXX-YYY=http://webmailhost:webmailport/VerifySSO? Where XXX is the local.webmail.sso.prefix value set above, and YYY is the value of local.webmail.sso.id set here.
local.webmail.sso. cookiedomain	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.
local.webmail.sso. singlesignoff	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.
local.sso.appid.verifyurl	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 resource.properties file entry NDAAuth-applicationID. There should be one parameter defined for each trusted peer SSO application. The standard form of the verify URL is: http://nda-host:port/VerifySSO? 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