Chapter 4
Implementing Single Sign-On
Single Sign-On allows an end user to authenticate once and use multiple applications without re-authenticating. For example, you can login to Communications Express and use the mail applications without authenticating again, provided single sign-on is enabled in the mail application. Single Sign-On can be performed with or without Identity Server.
|
Note
|
Messenger Express or Messenger Express Multiplexor (MEM) and Communications Express should be deployed on the same host to enable inter- operability between calendar and mail, and address book and mail user interfaces. If the applications are deployed on different hosts, the browser will not permit you to inter-operate between applications for security reasons.
|
|
This chapter contains the following sections:
Setting up Single Sign-On With Identity Server
The following sections explain how to set up and use Communications Express with single sign-on of the Identity Server.
Enabling Single Sign-On in Communications Express With Identity Server
When Communications Express is deployed with Identity Server, it uses the Identity Sever’s single sign-on mechanism for authentication. All parameters mentioned in Table 4-1 are set when the configuration wizard is invoked. Follow the guidelines provided in Table 4-1 while setting the parameters.
|
Note
|
- The uwcauth.identity.binddn and uwcauth.identity.bindcred values should correspond to the values entered when installing Identity Server.
For example, uwcauth.identity.binddn=uid=amAdmin, ou=People, o=siroe.example.com, o=example.com and uwcauth.identity.bindcred=password.
- Do not leave uwcauth.identity.binddn and uwcauth.identity.bindcred values unassigned.
- You need to move the Identity Server related jar files (am_sdk.jar and am_services.jar, from <UWC-deployed-path>/ WEB-INF/lib) to the temporary directory till the fix for bug number 4920222 is resolved.
|
|
You can modify Communications Express specific parameters, listed in Table 4-1, in uwcauth.properties file to enable you to work with Identity Server SSO.
Table 4-1 Configure UWC Specific Parameters to Access Messenger Express using the Identity Server Session
Parameter
|
Default Value
|
Purpose
|
uwcauth.identity.enabled
|
true
|
Specifies whether identity server is enabled.
The attribute is set to “true” to enable Identity Server.
|
uwcauth.identity.login.url
|
|
Specifies the configuration variable that enables SSO from Identity Server. The parameter should point to the URL where the Identity Server runs the naming service.
For example, uwcauth.identity.login.url=http://siroe.example.com:85/amserver/UI/login
|
uwcauth.identity.cookiename
|
iPlanetDirectoryPro
|
Specifies the cookie name used by Identity Server.
The value of uwcauth.identity.cookiename should correspond to the value configured for Identity Server.
|
uwcauth.identity.binddn
|
amAdmin BindDN
|
Specifies the complete DN of the amadmin.
For example,
uid=amAdmin, ou=People, o=siroe.example.com, o=example.com
|
uwcauth.identity.bindcred
|
amAdminBindCred
|
Specifies the password of the amadmin
|
uwcauth.http.port
|
80
|
Specifies the port number that Communications Express listens to when Communications Express is configured on a non SSL port.
|
uwcauth.https.port
|
443
|
Specifies the https port number that Communications Express listens to when Communications Express is configured on Web Server.
|
Enabling SSO in Messaging Express With Identity Server
As an Administrator, you can configure the parameters listed in Table 4-2 using msg-svr_install_root/sbin/configutil tool. Note that these parameters need to be set explicitly after install as the installer does set these parameters.
For more information on using the configutil tool, refer to Chapter 3, Configuring General Messaging Capabilities, of the Sun Java System Messaging Server Administration Guide at http://docs.sun.com/doc/817-6266-10
You can modify the Messenger Express specific parameters listed in Sun Java System Messaging Sever configuration, to enable UWC users access Messenger Express using the Identity Server session.
Table 4-2 Configure Messenger Express Specific Parameters in Messaging Sever configuration, to enable UWC users access Messenger Express using the Identity Server session
Parameters
|
Example
|
Purpose
|
local.webmail.sso.amnamingurl
|
|
This configuration enables SSO from Identity Server.
The variable should point to the URL Identity Server runs the naming service.
For example,
configutil -o local. webmail.sso.amnamingurl -v http://siroe.example.com:85/amserver/namingservice
|
local.webmail.sso.uwcenabled
|
1
|
Enables UWC users access Messenger Express.
|
local.webmail.sso.uwclogouturl
|
http://siroe.example.com:85/base/UWCmain?op=logout
When Communications Express is deployed in non-root URI, such as /uwc, the value of this parameter is:
http://siroe.example.com:85/uwc/base/UWCmain?op=logout
|
Specifies the URL Messenger Express uses to invalidate the UWC session.
|
local.webmail.sso.uwcport
|
85
|
Specifies the UWC HTTP port.
|
local.webmail.sso.uwccontexturi
|
uwc
|
Specifies the path in which UWC is deployed.
Specify this parameter only when UWC is deployed in non root URI. For example if UWC is deployed in /uwc, local.webmail.sso.uwccontexturi=uwc
|
local.webmail.sso.amcookiename
|
iPlanetDirectoryPro
|
Specifies the Identity Sever session cookie.
Ensure that in the uwcauth.properties file the value of uwcauth.appprefix is set to the value of local.webmail.sso.amcookiename.
|
local.webmail.sso.uwchome
|
|
Specifies the url required to access the home link in the Mast head.
|
How UWC Works With Identity Server SSO
- If Identity Server is enabled the authentication is performed by the Identity Server and the cookie is set with a name as specified in uwcauth.identity.cookiename in uwcauth.properties file.
- Communications Express verifies the validity of the cookie by sending a request to the Identity Server naming URL using Identity Server SDK. The Identity Server naming URL is picked up from the key whose value is in the format:
<protocol>://<host>:<port>/<content URI>
For example, http://siroe.example.com:/amserver
For example, http://siroe.com:80/amserver
- UWC receives the user ID and the organization DN from SSO SDK after the credentials are successfully verified.
- UWC verifies the services enabled for that particular user and creates a local session.
- UWC session is invalidated and redirected to the UWC login page when either the Identity session times out or is destroyed when the user logs out.
Setting up Single Sign-On With Messaging SSO
This section explains how to set up and use the Communications Express with Messaging Server single sign-on. The configuration wizard does not set any of the mandatory SSO related parameters. You need to manually set the required parameters as explained in the first and second sections listed below.
Enabling Communications Express Using Messaging SSO
You can modify mail specific parameters, listed in Table 4-3, in uwcauth.properties file to enable communications Express users access Messenger Express using Messaging SSO.
Table 4-3 Configure Mail Specific Parameters in uwcauth.properties File
Parameters
|
Default Value
|
Purpose
|
uwcauth.sessioncookie
|
JSESSIONID
|
Specifies the name of the cookie used by the servlet container to track the sessions.
|
uwcauth.appprefix
|
|
Specifies the prefix for the host application.
The prefix is used to find cookies generated by other trusted applications during single sign-on.
If the deployment uses Messaging SSO, this attribute should be assigned the value of local.webmail.sso.prefix set during messaging configuration.
|
uwcauth.appid
|
uwc
|
Specifies the cookie name containing the unique application ID for the host application.
|
uwcauth.cookiedomain
|
|
Specifies the domain name saved as part of the single sign-on cookie.
The value must begin with a period (.), for example, “.example.com” where the fully qualified host name is siroe.example.com.
|
uwcauth.messagingsso.enable
|
true
|
Enables or disables all single sign-on functionality with messaging.
Set this parameter to “true” to enable single sign-on and “false” to disable single sign-on.
|
uwcauth.messagingsso.cookiepath
|
/
|
Specifies the domain or path saved as part of the single sign-on cookie.
|
uwcauth.messagingsso.singlesignoff
|
true
|
If set to “true” both UWC and Messenger Express sessions are invalidated and the user is redirected to the login page. Otherwise, only the Messenger Express session is invalidated.
|
messagingsso.xxx.url
|
http://servername/ VerifySSO?
|
Specifies the URL used to verify the SSO cookie.
The value of xxx should be replaced by the application ID of the server.
For example, if you want to enable SSO with Messaging Server whose application ID is “msg60”, you need to add the following configuration parameter:
mesagingsso.msg60.url=http://servername/VerifySSO?
The value of xxx mentioned here should be identical to the value assigned in Messenger Express to local.webmail.sso.id.
|
messagingsso.uwc.url
|
http://servername:85/VerifySSO?
When Communications Express is deployed in non-root URI, such as /uwc, the default value of the parameter is:
http://servername:85/uwc/VerifySSO?
|
Specifies the verify URL of UWC server.
If you have edited the value of uwcauth.appid for this server, replace uwc in messagingsso.uwc.url with the new uwcauth.appid.
|
messagingsso.appid
|
ims
|
UWC uses this cookie to determine whether to issue the logout request to Messenger Express.
The value of messagingsso.appid should be same as the local.webmail.sso.id set during messaging configuration.
|
Enabling Messaging Server Using Messaging SSO
You can modify mail specific parameters, listed in Table 4-4,using configutil utility (msg-svr_install_root/sbin/configutil) to enable UWC users access Messenger Express using Messaging SSO.
Table 4-4 Configure Messenger Express parameters in Messaging Server configuration to Enable UWC Users Access Messenger Express Using Messaging SSO
Parameter
|
Example
|
Purpose
|
local.sso.<uwc-appid>.verifyurl
|
http://siroe.example.com:85/VerifySSO?
When Communications Express is deployed in non-root URI, such as /uwc, the default value of the parameter is:
http://siroe.example.com:85/uwc/VerifySSO?
|
Specifies the URL used by Messenger Express to verify the cookie with UWC.
The value of <uwc-appid> should correspond to the value of appid provided in uwcauth.properties file.
|
local.webmail.sso.cookiedomain
|
.example.com
|
The string value of this parameter is used to set the cookie domain value of all SSO cookies by the Messenger Express HTTP server.
The value must begin with a period (.), for example, “.example.com” when the fully qualified hostname is siroe.example.com.
Ensure that the value specified for this parameter is the same as that entered for uwcauth.cookiedomain
|
local.webmail.sso.enable
|
1
|
Enables or disables single sign-on functionality with Messaging SSO.
|
local.webmail.sso.ims.verifyurl
|
http://siroe.example.com/VerifySSO?
Here it is assumed that webmail is deployed in port 80.
|
Specifies the URL used to verify the SSO cookie.
|
local.webmail.sso.prefix
|
|
Specifies the prefix of the host application used to find cookies generated by other trusted applications for SSO.
Ensure this value corresponds to the value entered for uwcauth.appprefix.
|
local.webmail.sso.singlesignoff
|
1
|
If set to true, the server removes all single sign-on cookies for the user matching the value of sso.apprefix, when the user logs out.
If set to false, the server removes only its single sign-on user cookie.
|
local.webmail.sso.uwcenabled
|
1
|
Enables or disables UWC users access Messenger Express.
|
local.webmail.sso.uwclogouturl
|
http://siroe.example.com:85/base/UWCMain?op=logout
When Communications Express is deployed in non-root URI, such as /uwc, the default value of the parameter is:
http://siroe.example.com:85/uwc/base/UWCMain?op=logout
|
Specifies the URL used by Messenger Express to invalidate the UWC session.
|
local.webmail.sso.uwcport
|
85
|
Specifies the UWC HTTP port.
|
local.webmail.sso.uwccontexturi
|
uwc
|
Specifies the path in which UWC is deployed.
Specify this parameter only when UWC is deployed in non-root URI. For example, if UWC is deployed in “/uwc”, local.webmail.sso.uwccontexturi=uwc
|
local.webmail.sso.uwchome
|
http://www.sun.com
|
Specifies the url required to access the home link in the Mast head.
|
How Communications Express works with Messaging SSO
Figure 4-1 Setting up Single Sign-on with Messaging SSO
When a user logs into Communications Express, the unified web client authenticates the user and maintains the session’s cookie in the browser. The cookie name of this session is in the format:
uwcauth.appprefix + "-" + uwcauth.appid.
When Messenger Express is accessed from UWC with SSO enabled in Messenger Express:
- Messenger Express receives all the cookies that have names starting with the value configured in local.webmail.sso.prefix. The cookie which contains the UWC appid is selected to be verified.
- Messenger Express creates an appropriate UWC URL using the parameters local.webmail.sso.uwccontexturi and local.webmail.sso.uwcport.
The uwcport is the port where Communications Express is deployed.
For example, if UWC and Messenger Express are deployed on siroe.varrius.com, Messenger Express creates the URL string in the following format:
http(s)://siroe.varrius.com:local.webmail.sso.uwcport/local.webmail.sso.uwccontexturi
- Messenger Express verifies the cookie value with UWC by sending the verify request to local.sso.uwc.verifyurl.
- Messenger Express receives the User ID and domain information after UWC authenticates the user credentials.
- Messenger Express then creates a local session and displays the mail box of the user.
- When the user clicks on logout, the logout request goes to Messenger Express to invalidate the Messenger Express Session. After invalidating the Messenger express session it redirects the user to the logout url of Communications Express. Communications Express invalidates its session and redirects users to the login page.
Setting up Common Parameters for both Identity Server SSO and Messaging SSO
|
Note
|
Both Communications Express and Messenger Express should be deployed in the same protocol (either http or https).
|
|
Table 4-5 lists the common UWC specific parameters in uwcconfig.properties file. The parameters are set when Communications Express is configured.
Table 4-5 Common UWC Specific Parameters set when Communications Express is configured
Parameter
|
Example
|
Description
|
mail.deployed
|
true
|
Enables or disables mail access in UWC.
The attribute is set to “true” if Messenger Express is deployed.
|
webmail.host
|
siroe.example.com
|
Specifies the host name of Messenger Express (or MEM). Messenger Express’s host name should correspond to the host name of UWC.
|
webmail.port
|
80
|
Specifies the port number where Messenger Express is running.
|
Accessing Messenger Express in Communications Express
The Communications Express decides whether to show the 'Mail' tab to a user based on the values of the LDAP attributes in the following order:
mailDeployed (appl level) -> inetDomainStatus(domain level) -> mailDomainStatus(domain level) -> inetUserStatus(user level) -> mailUserStatus(user level)
For more details on these LDAP attributes refer to the Sun Java System Communications Services 6 Schema Reference Guide.