Sun Java System Messaging Server 6 2004Q2 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 Identity Server is the official gateway used for SSO for Sun Java System 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 Java System Identity Server 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 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 Java System 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 Java System ServersThis section describes SSO using Identity Server. It consists of the following sections:
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
You can modify the SSO configuration parameters shown in Table 6-3, by using the configutil command.
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
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.
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.
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.
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
An even more complex deployment would include Messenger Express Multiplexors and load balancers.
Figure 6-2 Complex SSO Deployment
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 6-3. You must be root user. cd to instance_root
- 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: proxypasswordldapadd -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=DelAdminIDFor 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.
- 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 httpMessenger 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
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.
cookiedomainThe 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.
singlesignoffThe 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