This chapter explains several administrative tasks for Oracle Communications Convergence.
This section describes administrative tasks related to authentication.
See also Convergence Security Guide for information about certificate-based authentication.
To set up Convergence UI login for end users, evaluate if you want to use:
UID (default), or
Email Address Login (LDAP mail attribute)
The procedures for setting up email address login which uses the LDAP mail attribute are the following:
In order to create a filter for email address login, you need the uid and mail attributes.
The mail attribute identifies the primary email address for a user, calendar group, or calendar resource. This is the email address retrieved and displayed by lookup applications.
Table 3-1 lists the variables used in constructing the filter.
Table 3-1 Mail Attribute Filter Variables
| Variable | Description |
|---|---|
|
%U |
Name part of the login name (that is, everything before the login separator stored in the servers configuration). |
|
%V |
Domain part of the login string. |
|
%o |
Original login ID entered by the user. |
For more information on LDAP attributes, specifically, inetDomainSearchFilter, see the discussion about LDAP object classes and attributes in your Oracle Communications Messaging Server and Oracle Communications Calendar Server documentation.
To set up email address login, enable it on the Convergence Server:
iwcadmin -o ugldap.ugfilter -v "(|(uid=%U)(mail=%o))"
See "Convergence Properties Reference" for information on ugldap.ugfilter.
mailAlternateAddress is the alternate RFC 822 email address of this recipient. A filter similar to mail can be performed on mailalternateaddress:
iwcadmin -o ugldap.ugfilter -v "(|(uid=%U)(mail=%o)(mailalternateaddress=%o))"
LDAP authentication is enabled by default when you configure Convergence. You can use separate LDAP servers to store authentication information and user preferences. By default, Convergence uses UG LDAP as the authentication LDAP server. You can enable LDAP authentication by using the following command line option:
iwcadmin -o auth.ldap.enable -v true
You can configure Convergence to use a separate directory server for user authentication and another for user/group information.
When LDAP authentication module is configured for authentication, the LDAP authentication module, by default, uses the UG LDAP for authentication. If you use separate LDAP servers for storing the authentication information and user preferences, the schema type and user trees should match in both the LDAP stores.
To enable your site to use a separate LDAP server for authentication, you must set the following configuration parameters.
auth.ldap.enable - Set this parameter to true.
auth.ldap.schemaversion - Set this parameter to the schema version that you are using for the UG LDAP. The schema versions for the UG LDAP and authentication LDAP must be the same.
auth.ldap.dcroot - DC (Domain Component) or user tree root node in the LDAP. This should be the same value as in the UG LDAP.
auth.ldap.host - Host name of the authentication LDAP server.
auth.ldap.enablessl - Set this parameter to true or false to enable or disable SSL.
auth.ldap.port - Port number that the LDAP server listens to. If the LDAP server is configured in SSL mode, you must provide the SSL port.
auth.ldap.minpool - Minimum number of connections that you want to have when the LDAP pool is initialized.
auth.ldap.maxpool - Maximum number of connections that you want to have when the LDAP pool is initialized.
auth.ldap.timeout - Set this to the maximum number seconds that the LDAP server should wait for returning search results before aborting the search.
auth.ldap.binddn - The Bind DN of the user. The LDAP server privilege user ID. For example, cn=DirectoryManager.
auth.ldap.bindpwd - The bind DN user password.
You can set the parameters in batch mode. See "Running the Administration Utility in Batch Mode".
The following configuration parameter can be set when the administrator needs to customize default values.
iwcadmin -o auth.ldap.ugfilter -v user_group_filter
This should result in unique user entry under given domain/organization. For example,(|(uid=%U)(mail=%o)) otherwise it will cause unexpected results. If not set (uid=%U) will be used as default value.
If you use the same LDAP server, both for authentication and storing user preferences, you must set the ugldap.enablessl and ugldap.port configuration parameters by using the iwcadmin command.
iwcadmin -o ugldap.enablessl -v true
iwcadmin -o ugldap.port -v user_group_ldap_port
If your deployment uses an LDAP server other than the User/Group LDAP for authentication, you must set the following parameters by using the iwcadmin command:
iwcadmin -o auth.ldap.enablessl -v true
iwcadmin -o auth.ldap.port -v ldapport
Convergence creates log files that records events, status of various software components, system errors, and other aspects of the server such as session, IP addresses and so on. By examining the log files, you can monitor the server's operation.
The following are the components of Convergence for which you can set logging information.
Address Book (ADDRESS_BOOK)
Administration (ADMIN)
Authentication (AUTH)
Configuration (CONFIG)
Default (DEFAULT)
Event Notification System (ENS)
Notify (NOTIFY)
Protocol (PROTOCOL)
Calendar Proxy (PROXY_CAL)
Indexing and Search Service Proxy (PROXY_ISS)
Mail Proxy (PROXY_MAIL)
Network Address Book Proxy (PROXY_NAB)
Outside In Proxy (PROXY_OIN)
SIEVE filters (SIEVE)
For each component, you can set a log level. The existing log levels are described in "About Log Levels". To see the list of components for which logging can be enabled, use the following command:
iwcadmin -l | grep log.*.level log.ADDRESS_BOOK.level = DEBUG log.ADMIN.level = DEBUG log.AUTH.level = DEBUG log.CONFIG.level = DEBUG log.DEFAULT.level = DEBUG log.ENS.level = DEBUG log.NOTIFY.level = DEBUG log.PROTOCOL.level = DEBUG log.PROXY_CAL.level = DEBUG log.PROXY_ISS.level = DEBUG log.PROXY_MAIL.level = DEBUG log.PROXY_NAB.level = DEBUG log.PROXY_OIN.level = DEBUG log.SIEVE.level = DEBUG
Communication Center uses a set of loggers for various components of the server. You can enable and set log levels for each of the components by using the iwcadmin command.
For example, the following command sets the Address Book logging to the level INFO.
iwcadmin -o log.ADDRESS_BOOK.level -v INFO
Convergence uses Apache Log4j as its underlying logging framework. All the log levels that Log4j offers are available in Convergence. The following log levels are available:
OFF
ERROR
WARN
INFO
DEBUG
You can specify the following log locations:
Application log location: All log information generated by the server are sent to the application log. This log file contains information about the behavior of the application.
Administration log location: All log information that is generated by the iwcadmin command are sent to the administration log location.
To set log information for the application logger, type the following command:
iwcadmin -o log.location -v /data/logs/file.log
where file is the name you choose for the log file.
To set the logging information for the administration logger, use the following command:
iwcadmin -o log.adminloglocation -v /data/logs/file.log
Log rotation is an approach to manage log files by renaming the existing log file and creating a new log file. All the log messages generated after creating the new file is written in this new log file.
Convergence supports log rotation based on size or time. Size-based log rotation is triggered when the log file reaches a specified size in kb (kilobytes). Time based log rotation is triggered based on the date pattern specified by the administrator.
This example shows how to set size based log rotation:
iwcadmin -o log.sizetriggerval -v 102400
This example shows how to set time based log rotation policy:
iwcadmin -o log.timetriggerval -v "'.'yyyy-MM"
For more information about frequency patterns for time based log rotation, see the apache web site:
http://logging.apache.org/log4j/1.2/apidocs/org/apache/log4j/DailyRollingFileAppender.html
To log IP address and session tracking information, you must modify the log pattern to include the IP address and session ID of a user so that these get added into the log file. Type the following command:
iwcadmin -o log.pattern -v '%c: %p from %C Thread %t ipaddress=%X{ipaddress} sessionid=%X{sessionid} at %d - %m %n'
iwcadmin -o log.enableusertrace -v true
Modify the log-pattern to include the user IP address (%X{ipaddress}) and session id (%X{sessionid}) in the log messages.
Note:
If the GlassFish Server hosting Convergence resides behind a front-end reverse proxy or load balancer (web server), this front-end's IP address is captured, not the browser's IP address. To overcome this situation, use the following command to set the auth-pass-through-enabled parameter to true on the GlassFish Server.asadmin set server-config.network-config.protocols.protocol.http-listener-1.http.auth-pass-through-enabled=true
In case you are using a reverse proxy in front of Convergence, you have to configure that reverse proxy to put the original client IP address into an HTTP Header that must be called proxy-ip.
If you have set auth-pass-through-enabled to true, then your load balancer or reverse proxy must be passing the IP address to the client. If you do not configure the load balancer or reverse proxy in this manner, or if you bypass the load balancer, you will not be able to log into Convergence.
GlassFish Load Balancer plug-in automatically adds client original IP address to HTTP Header proxy-ip.
See your Oracle GlassFish Server documentation for more information.
The following example shows a typical logging session:
PROTOCOL: DEBUG from com.sun.comms.client.web.IwcCookieManager Thread httpSSLWorkerThread-80-23 ipaddress=198.51.100.0 sessionid= at 23:08:31,920- cleaning client cookies: webmailcookiename is webmailsid PROTOCOL: DEBUG from com.sun.comms.client.web.IwcCookieManager Thread httpSSLWorkerThread-80-23 ipaddress=198.51.100.0 sessionid= at 23:08:31,920- cleaning client cookies: webmailcookiepath is / PROTOCOL: DEBUG from com.sun.comms.client.web.IwcCookieManager Thread httpSSLWorkerThread-80-23 ipaddress=198.51.100.0 sessionid= at 23:08:31,920- Cookie sent by client : JSESSIONID value=687380a1199c738c5165692c4587 path=null comment=null domain=null version=0 isSecure? false maxAge=-1 PROTOCOL: DEBUG from com.sun.comms.client.web.IwcCookieManager Thread httpSSLWorkerThread-80-23 ipaddress=198.51.100.0 sessionid= at 23:08:31,921- Removing iwc client cookie JSESSIONID
These messages indicate that the user session has been invalidated by the server. There are a few reasons why a user session is invalidated:
a logout is issued from the browser.
a new login is initiated, but there is already active session in progress.
the GlassFish server is shutdown. All sessions are then invalidated.
This section explains how to configure Convergence with SSL.
Secure connections between applications connected over the Web can be obtained by using protocols such as Secure Sockets Layer (SSL) or Transport Layer Security (TLS). SSL is often used to refer to either of these protocols or a combination of the two (SSL/TLS). Due to a security problem with SSLv3, Convergence recommends the use of only TLS. See Convergence Security Guide for information about disabling SSLv3. However, throughout this guide, secure communications may be referred to by the generic term SSL.
SSL provides a secure means of communication between the web-browser client and the server. You can enable SSL in Convergence in two ways:
At the time of configuring Convergence, or
By setting the SSL configuration parameters after configuration.
To enable Convergence to use SSL, you must enable SSL at the GlassFish Server level and also set the base.sslport configuration parameters using the iwcadmin command.
For base.sslport properties, refer to "Convergence Properties Reference".
iwcadmin -o base.sslport -v ssl_port
Authentication-Only SSL is a mechanism in which users are authenticated by using the HTTPS protocol which prevents user authentication details from being sent unencrypted. All other requests from the client are performed using the HTTP protocol. To configure Convergence to use Authentication only SSL, you must set both the base.sslport to the GlassFish Server SSL port value, and the base.enableauthonlyssl value using the iwcadmin command. For example:
iwcadmin -o base.sslport -v ssl_port
iwcadmin -o base.enableauthonlyssl -v true
Use the iwcadmin command to enable SSL between Convergence and back-end servers.
To enable SSL for mail server, set the mail.enable and mail.port configuration parameters.
iwcadmin -o mail.enablessl -v true
iwcadmin -o mail.port -v mail_port
Where mail_port is the SSL port open on the Messaging server.
To enable SSL for Calendar Server 6.3, set the cal.enablessl and cal.port configuration properties.
iwcadmin -o cal.enablessl -v true
iwcadmin -o cal.port -v cal_port
Where cal_port is the SSL port open on the Calendar Server.
To enable SSL for Calendar Server 7, set the caldav.enablessl and caldav.port configuration properties.
iwcadmin -o caldav.enablessl -v true
iwcadmin -o caldav.port -v caldav_port
Where caldav_port is the SSL port open on the Calendar Server.
The address book service provide by Convergence is a part of Convergence. To enable SSL for the address book service, enable SSL for Convergence.
To enable SSL between Convergence and Instant Messaging Server, you must enable TLS/SSL in Instant Messaging Server. No configuration changes are required for Convergence. See Instant Messaging Server System Administrator's Guide for more information.
To enable SSL for Contacts Server, set the nab.enablessl and nab.port configuration properties.
iwcadmin -o nab.enablessl -v true
iwcadmin -o nab.port -v nab_port
Where nab_port is the SSL port open on the Contacts Server.
Oracle recommends setting up automatic HTTPS redirection on the Convergence web container. See the container documentation for the preferred approach for setting up HTTPS redirection.
You can enable HTTP strict transport security (HSTS) to protect the Convergence server from dynamic content accessed in Convergence (for example, in an email). HSTS requires at least one successful HTTPS request, otherwise the HSTS header is ignored.
By default, HSTS is not enforced.
Use the iwcadmin command to set base.hstsmaxage:
iwcadmin -0 base.hstsmaxage -v duration
where duration represents the number of seconds that a host is remembered as a known HSTS host. A value of 0 disables HSTS. Any value greater than 0 enforces HSTS.
You can configure the Convergence Display Name to map to LDAP displayName.
Table 3-2 lists the configuration parameters for mapping the LDAP display name to the Convergence display name.
Table 3-2 Configuration Parameters for Mapping the LDAP displayName
| Parameter | Description |
|---|---|
|
general.screenname |
Defines the LDAP attribute used for the screen name, also referred to as displayname. Located in the useroption-mappings.properties file. |
|
ScreenNameEditable |
Determines if the display name in the Options page is editable or not. Default is false. |
With these configuration parameters, you are able to modify the Convergence display name in the following ways:
If the LDAP displayName parameter does not contain a value, use the cn attribute as a fall back. If the user modifies the Convergence display name, then the LDAP displayName attribute is populated.
The ability to edit the Convergence display name is disabled by default. To enable it, set the following iwcadmin command:
iwcadmin -o client.screennameeditable -v true
To configure the corporate address book for search, modify the following parameters by editing the config/templates/ab/corp-dir/xlate-inetorgperson.xml file:
Search displayName and cn where displayName has a different LDAP attribute from cn. Modify:
<entry>
...
<displayname>db:your_ldap_displayname_attribute</displayname>
<cn>db:your_ldap_cn_attribute</cn>
...
</entry>
Search displayName only where displayName has a different LDAP attribute from cn. In this scenario, no modification is required.
Search displayName only where displayName has the same LDAP attribute cn. In this scenario, no modification is required.
You can enhance Convergence security with single sign-on (SSO).
Oracle recommends that you deliver SSO functionality using Oracle Access Manager. See your Oracle Access Manager documentation for more information.
You can also configure Convergence for Trusted Circle SSO or write a custom SSO module.
To configure Convergence to use Trusted Circle SSO, you must enable the sso.ms.enable configuration parameter.
iwcadmin -o sso.ms.enable -v true
Enabling SSO, by default enables single sign-off.
To manually enable single sign off, enter the following command:
iwcadmin -o sso.enablesignoff -v true
To enhance security in Convergence, you can write your own custom modules for authentication or single sign-on. See the discussion about security considerations for developers in Convergence Security Guide for more information
This section explains the different LDAP services for Convergence.
To configure Convergence for LDAP failover, type the following command:
iwcadmin -o ugldap.host -v ldap1:port1,ldap2:port2
ldap1:port1 and ldap2:port2 are the LDAP servers that are a part of the failover.
If your LDAP hosts are configured for SSL, all the failover LDAP servers in the failover mechanism are also in SSL mode. Each host does not have a separate SSL flag. All the LDAP servers should have the same privileged userid and password. All the LDAP servers should run in Master-Master replication mode.
This section explains the administrative tasks pertaining to configuration management.
To configure Convergence for SSL, you must first configure the Convergence server to accept SSL requests. Additionally, you must also configure the client utility: the iwcadmin command to communicate to the Convergence server in SSL mode.
To configure Convergence server administration for SSL:
Enable SSL by using the iwcadmin command.
iwcadmin -o admin.enablessl -v true
Generate keystore and truststore using keytool.
Set the keystore password.
iwcadmin -o admin.keystorepwd -v password
Copy keystore to the configuration and data files directory. The default location of this directory is /var/opt/sun/comms/iwc/.
Restart the GlassFish server.
The following log message appears indicates that the SSL configuration is a successful:
RMI connector server in SSL mode started successfully.
Set up the client to securely connect to Convergence. To do this, modify the following parameters in the iwcadmin.properties file. This file is available in the configuration and data files directory. The default path is: /var/opt/sun/comms/iwc.
Set the parameter secure to true. Optionally, you can use the -s option in the iwcadmin command.
Set the truststorepath parameter to the directory where you stored the trust store.
Set a password for truststorepasswd.
To change the Convergence administrator password, type the following command.
iwcadmin -o admin.adminpwd -v new_password
Convergence enables you to configure multiple domains in a deployment. Users can login to a domain by typing the URL and suffix the domain name to the user name. For example, user1@siroe.com. On successful authentication, the domain information is extracted from the login name and the user is logged into the specific domain.
Convergence provides an alternative way for users to log in to a specific domain. For example, you can configure Convergence to display a customized login page based on the domain information. The Convergence server displays the login page by extracting the domain name from the URL and determining if it contains a known domain and presents the domain specific login screen for the domain. The user can then type the user name and password and login to the domain. In this case the user will not have to suffix the domain name to the user name.
Consider an example where siroe.com is a configured domain for a Convergence deployment. When users access Convergence, the server presents a customized login page for the domain siroe.com. Convergence server determines this based on the value of the client.{domain-name}.loginpage property. To set a customized login page for a domain, set the client.{domain-name}.loginpage configuration property by typing the following command.
iwcadmin -o client.{siroe.com}.loginpage -v "/iwc_static/layout/loginpage_siroe.html"
Convergence enables you to set a time in minutes to automatically log out of the application in case of user inactivity in client and also when the user closes the application without logging out. By default, the time is set to zero and is disabled. To set a time and enable the automatic logout option, set the client.autologouttime configuration property by typing the following command.
iwcadmin -o client.autologouttime -v logout_time
Convergence allows you to verify the administration passwords. Convergence stores all passwords in encrypted format during configuration. You can verify if the password you have set while configuring Convergence is correct by using the EncryptPwd utility. The utility takes the password that you want to verify, as the input, and provides an encrypted string. To verify the password, you must compare this encrypted string with the encrypted password string stored in the Convergence configuration file.
To verify a password:
Enter the following command:
java -cp /var/opt/sun/comms/iwc/WEB-INF/lib/iwc-shared-util.jar com.sun.comms.shared.util.EncryptPwd
You will be prompted to provide the encryption key.
Note:
Where /var/opt/sun/comms/iwc/WEB-INF refers to the default deploy directory to which Convergence is deployed.Type the encryption key. By default the encryption key is available in the file: /var/opt/sun/comms/iwc/config/.ngc_enc.
Enter the encryption key ( To generate a new key press Enter ):
You will be prompted to enter a string to encrypt.
Type the password that you guess is the right password. For example.
Enter string to encrypt: admin123
The password you guess is encrypted and displayed at the prompt.
admin123 ---> rE9ZIq6H0r49RgsQrKHXsw==
Compare the encrypted password (rE9ZIq6H0r49RgsQrKHXsw==) with the encrypted password available in the configuration file to verify if the password you provided is correct. If the encrypted password strings match, the password you guessed is correct.
If the encrypted password strings do not match you can provide another string, or type quit to exit.
Enter string to encrypt: quit Bye...
A user must have a minimum set of LDAP privileges to manage the LDAP tasks for a Convergence deployment. Instead of using cn=Directory Manager, create an administrator user with a set of privileges that can enable him to manage a Convergence installation. The following privileges must be available for the user:
Read
Write
Search
Add
Delete
Update
The following LDIF file contains the ACIs assignments for Schema 1 for a user named convergenceAdminUser.
# Sample for Schema 1 # Adding ACIs to DC Tree dn: o=internet changetype: modify add: aci aci: (targetattr="*") (version 3.0; acl "foo"; allow (read,search) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";) # Adding ACIs to Organization Tree dn: dc=siroe,dc=sun,dc=com changetype: modify add: aci aci: (targetattr="*") (version 3.0; acl "foo"; allow (all) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";) # Adding ACIs to Address Book BaseDN dn: o=PiServerDb changetype: modify add: aci aci: (targetattr="*") (version 3.0; acl "foo"; allow (all) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";)
The following LDIF file contains the ACIs assignments for Schema 2 for a user named convergenceAdminUser:
# Sample for Schema 2 # Adding ACIs to Organization Tree dn: dc=siroe,dc=sun,dc=com changetype: modify add: aci aci: (targetattr="*") (version 3.0; acl "foo"; allow (all) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";) # Adding ACIs to Address Book BaseDN dn: o=PiServerDb changetype: modify add: aci aci: (targetattr="*") (version 3.0; acl "foo"; allow (all) userdn="ldap:///uid=convergenceAdminUser, ou=people, o=siroe.sun.com,dc=siroe,dc=sun,dc=com";)
Using the LDAP modify command, create the user:
ldapmodify -h hostname -p port -D "cn=Directory Manager" -w pwd -f add_acis.ldif modifying entry o=internet modifying entry o=usergroup modifying entry o=PiServerDb
Additionally, you must also set the ugldap.binddn and ugldap.bindpwd parameters in Convergence to reflect the user credentials:
iwcadmin -o ugldap.binddn -v uid=convergenceAdminUser, ou=people, o=siroe.com,o=usergroup
iwcadmin -o ugldap.bindpwd -v ug_ldap_bindpassword
Directory Server provides a mechanism to create indexes. These indexes improve the turnaround time at the time of searching for entries in the directory server instance. You must set the following parameters to enable VLV indexes in Directory Server.
search_base
vlv_search_filter
vlv_sort_attribute
vlv_scope
Note:
If you have multiple back-end Directory Servers that store user group information, you must create the indexes on all the instances.Before setting the VLV Browsing indexes, you must have information about the directory server settings. The directory server settings are available in the dse.ldif file under the directory_server_root/config directory. Specifically, you would need the value of the cn attribute. The following example shows the dse.ldif file:
dn: cn=isp,cn=ldbm database,cn=plugins,cn=config objectClass: top objectClass: extensibleObject objectClass: nsBackendInstance cn: isp creatorsName: cn=directory manager modifiersName: cn=directory manager entrydn: cn=isp,cn=ldbm database,cn=plugins,cn=config numSubordinates: 4 nsslapd-suffix: o=isp nsslapd-cachesize: -1 nsslapd-cachememsize: 10485760 nsslapd-readonly: off nsslapd-require-index: off nsslapd-directory: /var/opt/SUNWdsee/dsins1/db/isp
Use the ldapmodify command to specify the Directory Server browsing search indexes. For example:
ldapmodify -h directory.aus.sun.com -p 389 -D "cn=Directory Manager" dn: cn=Browsing isp,cn=isp,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvSearch cn: Browsing isp vlvbase: o=aus.sun.com,o=isp vlvscope: 2 vlvfilter: (&(mail=*)(cn=*)) aci: (targetattr="*")(version 3.0; acl "VLV for Anonymous"; allow (read,search,compare) userdn="ldap:///anyone";) dn: cn=Sort by cn,cn=Browsing isp,cn=isp,cn=ldbm database,cn=plugins,cn=config changetype: add objectClass: top objectClass: vlvIndex cn: Sort by cn vlvSort: cn
In the previous section, we provided the information about the search indexes that we want to create for your search base. For the settings to take effect, the indexes must be generated. It is recommended that these steps should be performed during a scheduled change window. This is because the Directory Server needs to be restarted.
The following commands describes the steps to create the indexes:
Change directory to the directory server installation. For example:
cd /opt/SUNWdsee/ds6/bin
Stop the directory server instance:
dsadm stop /var/opt/SUNWdsee/dsins1/
Populate the index entries using the dsadm reindex command. The reindex option requires you to provide the vlv_sort_attribute, the path to the directory server instance, and the value of the user group base.
dsadm reindex -l -t "Sort by cn" /var/opt/SUNWdsee/dsins1/ "o=isp"
Start the directory server instance.
dsadm start /var/opt/SUNWdsee/dsins1/
The Convergence client sends AJAX requests to communicate with the server. If these requests are redirected for any reason, you must take special care with the redirects. With AJAX requests, redirects are automatically handled by the browser. The contents of the redirected page are handed over as the AJAX response. But, when you look at the response headers, you cannot determine if the request was successful or if the request was redirected. If the request is redirected, then the application may not understand the response. As a result, you must configure Convergence to understand the contents of a redirected page.
When there is a security agent in between the Convergence client and server, problems occur when the agent intercepts every request while looking for a valid session. If the session is invalid, the request is redirected to a login page configured in security agent. Because Convergence does not understand the contents of the login page, it displays a response parsing error, such as a syntax error. To get around this problem, the security agent should redirect to a page that Convergence is able to understand, instead of redirecting to a custom login page.
Convergence expects session time out error messages to be in specific format. When the agent encounters session time out, it needs to redirect the request to a page that generates this error message instead of its login page. Sample error messages are provided in Table 3-3 and can be copied to the policy agents deployment location.
Convergence uses different protocols for each service. For Mail: the wmap protocol, for Calendar: the wcap protocol, for Address book: wabp protocol, and for Options: the iwcp protocol.
The agent should be configured to differentiate between the kinds of requests it receives and correspondingly send the error response specific to that service.
For example, if the agent receives /iwc/svc/wmap/* request, the error response should be as mentioned in Convergence_Domain/jsp/samplefiles/MailServiceErrorJSON.jsp.
Table 3-3 lists the requests that are redirected, the URL patterns, and appropriate error responses.
Table 3-3 Requests that are Redirected, URL Patterns, and Error Responses
| Service Request | URL Pattern | Redirect to File |
|---|---|---|
|
|
/iwc/svc/wmap/* |
MailServiceErrorJSON.jsp |
|
Calendar |
/iwc/svc/wcap/* |
CalServiceErrorJSON.jsp |
|
Address Book |
/iwc/svc/wabp/* |
If the expected response type is JSON: AddressBookErrorJSON.jsp; If the expected response type is XML: AddressBookErrorXML.jsp |
|
Options |
/iwc/svc/iwcp/ |
IwcProtocolErrorJSON.jsp |