This chapter describes 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 (directory server mail attribute)
The procedures for setting up email address login which uses the directory server 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 directory server attributes, specifically inetDomainSearchFilter, see the discussion about directory server 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))"
You can use the iwcadmin command to set up email address login into back-end servers.
To set up email address login for mail server, set the mail.uidreplayformat parameter.
iwcadmin -o mail.uidreplayformat -v "%o"
To set up email address login for calendar server, set the caldav.uidreplayformat parameter.
iwcadmin -o caldav.uidreplayformat -v "%o"
To set up email address login for contacts server address book, set the nab.uidreplayformat parameter.
iwcadmin -o nab.uidreplayformat -v "%o"
To set up email address login for Indexing and Search Service, set the ISS.uidreplayformat parameter.
iwcadmin -o ISS.uidreplayformat -v "%o"
See "Convergence Properties Reference" for information on mail.uidreplayformat, caldav.uidreplayformat, nab.uidreplayformat, and ISS.uidreplayformat.
Directory server authentication is enabled by default when you configure Convergence. You can use separate directory servers to store authentication information and user preferences. By default, Convergence uses UG LDAP as the authentication directory server. You can enable directory server authentication with 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 directory server authentication module is configured for authentication, the directory server authentication module uses the UG LDAP for authentication. If you use separate director servers for storing the authentication information and user preferences, the schema type and user trees should match in both the directory server stores.
To enable your site to use a separate directory 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 UG LDAP and directory server authentication must be the same.
auth.ldap.dcroot - DC (Domain Component) or user tree root node in the directory server. This should be the same value as in the UG LDAP.
auth.ldap.host - Host name of the authentication directory server.
auth.ldap.enablessl - Set this parameter to true or false to enable or disable SSL.
auth.ldap.port - Port number on which the directory server listens. If the directory 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 directory server pool is initialized.
auth.ldap.maxpool - Maximum number of connections that you want to have when the directory server pool is initialized.
auth.ldap.timeout - Set this to the maximum number seconds that the directory server should wait for returning search results before ending a search.
auth.ldap.binddn - The Bind DN of the user. The directory 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 directory 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 a directory 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)
IM Gateway (HTTPBIND)
Network logs for HTTPBIND (HTTPBIND_XREF)
Avatar logs for HTTPBIND (HTTPBIND_AVATAR)
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.HTTPBIND.level = DEBUG log.HTTPBIND_AVATAR.level = DEBUG log.HTTPBIND_XREF.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 set or unset the appender reference for the components of Convergence. Appender reference is used so that the logging properties can be set for an individual component. If the component does not require the logging properties at component level, you can unset the appender reference by setting its value to a blank.
To set the appender reference for the component, type the following command:
iwcadmin -o log.component_name.appendername -v appender_name
where component_name is the name of component of Convergence.
where appender_name is the name of the appender.
For example, the following command sets the appender reference ADDRESS_BOOK_APPENDER for the ADDRESS_BOOK.
iwcadmin -o log.ADDRESS_BOOK.appendername -v ADDRESS_BOOK_APPENDER
For example, the following command sets the appender reference GENERIC for the PROXY_CAL.
iwcadmin -o log.PROXY_CAL.appendername -v GENERIC
To unset the appender refernece for the component, type the following command:
iwcadmin -o log.component_name.appendername -v
where component_name is the name of component of Convergence.
For example, the following command unsets the appender reference for the ADDRESS_BOOK.
iwcadmin -o log.ADDRESS_BOOK.appendername -v
Note:
You can also set the same appender reference for more than one component of the Convergence.For example, the following command sets the appender reference GENERIC for the PROXY_CAL, PROXY_MAIL, and SIEVE components.
iwcadmin -o log.PROXY_CAL.appendername -v GENERIC iwcadmin -o log.PROXY_MAIL.appendername -v GENERIC iwcadmin -o log.SIEVE.appendername -v GENERIC
You can specify the following logging properties for an individual component after the appender reference is set for the component:
log.appender.appender_name.type
log.appender.appender_name.location
log.appender.appender_name.sizetriggerval
log.appender.appender_name.maxbackupindex
log.appender.appender_name.pattern
where appender_name is the name of appender.
This example shows how to set the logging properties for the ADDRESS_BOOK after the appender reference ADDRESS_BOOK_APPENDER is set for the component:
iwcadmin -o log.appender.[ADDRESS_BOOK_APPENDER].type -v FILE iwcadmin -o log.appender.[ADDRESS_BOOK_APPENDER].location -v /opt/sun/comms/iwc/logs/ADDRESS_BOOK_LOGS.log iwcadmin -o log.appender.[ADDRESS_BOOK_APPENDER].sizetriggerval -v 2048 iwcadmin -o log.appender.[ADDRESS_BOOK_APPENDER].maxbackupindex -v 5 iwcadmin -o log.appender.[ADDRESS_BOOK_APPENDER].pattern -v '%c: %p from %C Thread %t at %d%m %n'
Note:
When an appender refernce is not associated with the component, all logs for that component will default to global logging properties (specified by log.location, log.adminloglocation, log.pattern etc).Fore more information about the logging properties, see Table 11-5, "Logging Configuration Properties".
Note:
Logging properties for HTTPBIND, HTTPBIND_XEFR, and HTTP_AVATAR components should be set only by using iwcadmin command. The logging properties defined in the httpbind_log4j.conf file in Convergence configuration directory will no longer be used for HTTPBIND, HTTPBIND_XEFR, and HTTP_AVATAR components.This example shows how to set the logging properties for the HTTPBIND component after the appender reference is set for the component:
iwcadmin -o log.appender.[HTTPBIND_APPENDER].type -v FILE
iwcadmin -o log.appender.[HTTPBIND_APPENDER].location -v /var/opt/sun/comms/iwc/log/httpbind_new.log
iwcadmin -o log.appender.[HTTPBIND_APPENDER].sizetriggerval -v 5120
iwcadmin -o log.appender.[HTTPBIND_APPENDER].maxbackupindex -v 7
iwcadmin -o log.appender.[HTTPBIND_APPENDER].pattern -v '[%d{DATE}] %-5p %c [%t] %m%n'
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 a load balancer (web server), the IP address of the front-end reverse proxy is captured, not the IP address of the browser. 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
If you use a reverse proxy in front of Convergence, you should configure that reverse proxy to put the original client IP address into an HTTP Header that must be called proxy-ip.
If you 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 cannot log into Convergence.
GlassFish Load Balancer plug-in automatically adds client original IP address to HTTP Header proxy-ip.
See the GlassFish Server documentation for more information.
For Oracle WebLogic Server:
If the Oracle WebLogic Server hosting Convergence resides behind a front-end reverse proxy or a load balancer (web server), the IP address of the front-end is captured, not the IP address of the browser. To overcome this situation, ensure that the WebLogic Plugin Enabled option is selected in the Web Applications tab for the domain name where Convergence is deployed (DomainName > Configuration > Web Applications).
If you use a reverse proxy in front of Convergence, you should configure that reverse proxy to put the original client IP address into an HTTP Header that must be called proxy-ip.
If you have selected the WebLogic Plugin Enabled option, 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 cannot log into Convergence.
See the Oracle WebLogic 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 Oracle certified application 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 Oracle certified application 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 Oracle certified application 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 7 and Calendar Server 8, 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.
To enable SSL for Indexing and Search Service, set the iss.enablessl and iss.port configuration properties.
iwcadmin -o ISS.enablessl -v true
iwcadmin -o ISS.port -v iss_port
Where iss_port is the SSL port open on the Indexing and Search Service server.
To enable SSL between Convergence and the directory server, set the ugldap.enablessl and ugldap.port configuration properties.
iwcadmin -o ugldap.enablessl -v true
iwcadmin -o ugldap.port -v ldap_port
Where ldap_port is the SSL port open on the directory 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 -o 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 directory server displayName.
Table 3-2 lists the configuration parameters for mapping the directory server display name to the Convergence display name.
Table 3-2 Configuration Parameters for Mapping the Directory Server displayName
| Parameter | Description |
|---|---|
|
general.screenname |
Defines the screen name directory server attribute, 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 directory server 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 directory server 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 by directory server displayName, modify the following parameters in the config/templates/ab/corp-dir/xlate-inetorgperson.xml file:
Search displayName and cn where displayName has a different directory server 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 directory server attribute from cn. In this scenario, no modification is required.
Search displayName only where displayName has the same directory server attribute cn. In this scenario, no modification is required.
To configure Convergence to hide global time zone selection from options (Date & Time), you must set the client.hideglobaltimezoneselection configuration parameter to true.
To set the parameter to true, type the following command.
iwcadmin -o client.hideglobaltimezoneselection -v true
The default value is false.
Host header specifies the host name for an incoming HTTP client request. The web server uses this value of the host header to dispatch the request to the specified website or web application. Since, the HTTP host header is controlled by the user, the user may enter incorrect or malicious information causing a host header attack. To prevent the attack, web servers can configure a virtual host to which the redirection happens in case a host header attack.
Convergence uses different approaches to prevent host header attack in a single domain and multi-domain environment.
When the Convergence deployment is in a single domain, you can set the server name in the Oracle certified application server settings to prevent the Convergence server from host header attack. However, this approach is only possible when the Convergence deployment is in a single domain.
To set a Server Name in GlassFish Server:
Log in to the GlassFish Server Administration Console.
Select http-listener-1 from the Configurations menu (Configurations/ server-config/Network Config/ Protocols).
http-listener-1 is assumed to be in use for Convergence.
Enter server name in the Server Name box.
Click Save.
Restart GlassFish Server.
To set a Server Name in Oracle WebLogic Server:
Log in to the Oracle WebLogic Server Administration Console.
Select HTTP from the Protocols menu (Environment/Servers/ManagedServer/Protocols/HTTP).
HTTP is assumed to be in use for Convergence.
Enter server name in the Frontend Host box.
Enter server port in the Frontend HTTP Port box.
Click Save.
Restart Oracle WebLogic Server and the Managed Server.
For more information on mitigating host header attacks on Oracle WebLogic Server, see: https://support.oracle.com/epmos/faces/DocumentDisplay?_afrLoop=255242706168486&id=2356316.1&_afrWindowMode=0&_adf.ctrl-state=ht6sq8y55_4">>.
When multiple domains are configured in the Convergence deployment, you can configure default host and whitelisted hosts to prevent the Covergence server from host header attack. To configure default host and whitelisted hosts, you can set the base.defaulthost and the base. whitelistedhosts values using the iwcadmin command. For example:
iwcadmin -o base.defaulthost -v "abcd.abc.com" iwcadmin -o base.whitelistedhosts -v "*.abc.com,*.xyz.com"
When the base.defaulthost and the base. whitelistedhosts parameters are set, the following occurs:
If the domain is a part of whitelisted domains, the user gets redirected to the corresponding domain page.
If the domain is not a part of whitelisted domains, the user gets redirected to the value configured as base.defaulthost.
See "Convergence Properties Reference" for information on base.defaulthost and base. whitelistedhosts.
When there is a specific login page set for a domain, this domain should be included in the whitelisted hosts, for the redirection to happen as expected.
You can enhance Convergence security by configuring single sign-on (SSO).
Oracle recommends that you deliver SSO functionality using Oracle Access Manager.
You can also configure Convergence for Trusted Circle SSO or write a custom SSO module.
You can integrate Convergence with Oracle Access Manager to deliver SSO capabilities.
Install and configure Oracle Access Manager according to its documentation. Refer to Oracle Fusion Middleware Installation Guide for Oracle Identify Management for detailed installation and configuration information as you complete the following tasks:
Install Oracle Database. During the installation, specify the following:
For Installation Option, select Create and Configure a Database.
For System Class, select Desktop.
Ensure the database has write permissions to the Oracle Base folder.
For Character Set, select UNICODE.
Set the following environment variables:
export ORACLE_HOME=database_home
where database_home is the database instance directory.
export PATH=$ORACLE_HOME/bin:$PATH
export ORACLE_SID=database_SID
Tune the following database parameters:
SQL>alter system set processes=500 scope=spfile;
SQL>alter system set open_cursors=1500 scope=spfile;
SQL>alter system set session_cached_cursors=500 scope=spfile;
SQL>alter system set session_max_open_files=50 scope=spfile;
SQL>alter system set aq_tm_processes=1 scope=spfile;
SQL>alter system set job_queue_processes=10 scope=spfile;
Create the schemas for Oracle Access Manager on the database using the Oracle Repository Creation Utility.
Install and configure Oracle WebLogic Server.
Install Oracle Access Manager and deploy it to the WebLogic server.
Using the Oracle Access Manager console, configure an identity store for the Unified Communications Suite directory server. Specify the following values:
For Store Type, select Iplanet Oracle Directory Server Enterprise Edition.
For Location, enter your directory server location.
For Bind DN, enter cn=directory manager.
Specify the directory server user search base. For example, enter o=my_domain.com,o=isp.
For Group Na me Attribute, enter cn.
Specify the directory server group search base. For example, enter o=my_domain.com,o=isp.
Using the Oracle Access Manager console, configure an authentication module for the new identity store.
Using the Oracle Access Manager console, change the authentication scheme to use the new authentication module.
Install and configure Oracle Web Tier and Oracle HTTP Server. Ensure the following:
Modify mod_wl_ohs.conf. Add or replace the following lines:
<IfModule weblogic_module> WebLogicHost OAM_Host WLLogFile /tmp/weblogicdebug Debug ON DynamicServerList Off WebLogicPort OAM_ADMIN_SERVER_PORT </IfModule>
The mod_wl_ohs.conf file enables communication between Oracle Access Manager and Oracle HTTP Server.
Create an Oracle wallet with a signed certificate from a certificate authority and a user certificate.
Modify httpd.conf. Locate the section in the file similar to the example below. Modify the section to match the example below, replacing the sample values.
ProxyRequests Off SSLProxyEngine On SSLProxyWallet "Oracle_Wallet_Absolute_Path" RequestHeader set Front-End-Https "On" ProxyPass /iwc https://Host:Port/iwc ProxyPass /iwc_static https://Host:Port/iwc_static ProxyPassReverse /iwc https://Host:Port/iwc ProxyPassReverse /iwc_static https://Host:Port/iwc_static <Location "/iwc"> Order allow,deny Allow from all </Location> <Location "/iwc_static"> Order allow,deny Allow from all </Location>
Modify ssl.conf. Turn on SSLEngine and set SSLWallet to the user wallet location.
Configure the Convergence Oracle certified application server:
Enable SSL in Convergence. See "About SSL in Convergence" for more information.
Import the certificate authority certificate used in the Oracle wallet into the Convergence Oracle certified application server.
Install and configure a webgate for Oracle HTTP Server. Ensure the following:
Register the webgate on Oracle Access Manager using the administration console. Ensure the following:
For the base URL, enter http://HTTP_Host:port, where HTTP_Host is the Oracle HTTP Server host name and port is the Oracle HTTP Server port number.
For the logout redirect URL, enter the URL to the location of the custom logout redirect script you will create later.
Copy the generated files and artifacts to the Oracle HTTP Server webgate instance location.
In the policy configuration for Oracle Access Manager, configure authentication and authorization policies to pass user email attributes in email header variables. Set up the policies with the following values on the Responses tab:
For Name, specify the Oracle Access Manager mail ID.
For Type, select Header.
For Value, enter ${user.attr.mail}.
To configure Convergence for SSO with Oracle Access Manager:
Using the iwcadmin command, set the following properties:
Set sso.oam.enable to true
Set sso.misc.OAMAuthHeader to the Oracle Access Manager mail ID
Set sso.misc.OAMLogoutUrl to the URL of the custom logout redirect script
Ensure that the idle session time-out value in Convergence (client.autologouttime) is the same as in Oracle Access Manager. In Oracle Access Manager, the idle session time out is on the System Configuration page under Common Settings.
Create a custom HTML logout redirect script. Place the script inside the Oracle HTTP Server or the Convergence Oracle certified application server domain. Ensure the following:
The webgate for Oracle Access Manager logout redirect URL points to this script.
The Convergence sso.misc.OAMLogoutUrl parameter points to this script.
The logout script clears any cookies belonging to applications protected by Oracle Access Manager, including applications under other webgates.
See "Sample Custom Logout Redirect Script" for a sample custom logout redirect script.
This section provides a sample custom HTML logout redirect script. This sample script uses https://Convergence_Server:port/iwc/svc/iwcp/lougout_oam.iwc as the new logout URL. The logout script can be run from any tab in the same browser session and does not require a token parameter.
You can copy the following sample and use it as a starting point for your own custom HTML logout redirect script.
<!DOCTYPE html>
<html>
<head>
<title>logout_oam_custom_script.html</title>
<script type="text/javascript">
//Replace "<OAM_SERVER_HOST:PORT>" by OAM server and its port. Example:"example.my_oam_server.com:14100"
var timedout = false;
var timeoutDuration = 0; //should be set, if we want to make sure logout process is not stuck at this page for long time. Unit is seconds
var protectedAppClearCookieURL = [];
var logoutAttemptedAppCount = 0;
function logout(){
for (var i=0; i < protectedAppClearCookieURL.length ; ++i){
var img = document.createElement("img");
img.onload = imageLoadedHandler;
img.onerror = imageErrorHandler;
img.src = protectedAppClearCookieURL[i];
}
if(timeoutDuration){
setTimeout(function(){
timedout = true;
errorOccurred = true;
doRedirect();
},timeoutDuration);
}
}
function imageLoadedHandler() {
logoutAttemptedAppCount++;
if (logoutAttemptedAppCount >= protectedAppClearCookieURL.length) {
doRedirect();
}
}
function imageErrorHandler() {
logoutAttemptedAppCount++;
errorOccurred = true;
if (logoutAttemptedAppCount >= protectedAppClearCookieURL.length){
doRedirect();
}
}
function doRedirect() {
if(errorOccurred) {
//Cuurently ignoring error..@TODO handle this
//alert('LOGOUT_ERROR');
}
document.location.href = "http://OAM_SERVER_HOST:Port/oam/server/logout"; //default logout redirect URL handler
}
</script>
</head>
<body onload="logout()">
<CENTER>
<BR/>
<IMG src="http://OAM_SERVER_HOST:Port/oam/pages/images/wait.gif" border="0" ALT=""/>
<BR/>
</CENTER>
</body>
</html>
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 directory server services for Convergence.
To configure Convergence for directory server failover, enter:
iwcadmin -o ugldap.host -v ldap1:port1,ldap2:port2
ldap1:port1 and ldap2:port2 are the directory servers that are a part of the failover.
If your directory server hosts are configured for SSL, all the failover directory servers in the failover mechanism are also in SSL mode. Each host does not have a separate SSL flag. All the directory servers should have the same privileged userid and password. All the directory 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 Oracle certified application 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"
To configure Convergence to use a different page for changing user password, set the client.changepasswordpage configuration property by typing the following command.
iwcadmin -o client.changepasswordpage -v <URL to the password management page>
When client.changepasswordpage is set, the Change Password tab in Convergence Global Options displays a link to the configured password management page. The default Change Password Page provided by Convergence can be retained by resetting the value of this configuration parameter.
iwcadmin -o client.changepasswordpage -v ""
This will reset the default Change Password page provided by Convergence and will display the text boxes to enter Current Password and New password.
The following scenarios apply:
Convergence handles password policies applied to user in Directory Server.
When a user login with the password that is about to expire, the "Change Password" and "Remind me Later" buttons are displayed in the Convergence banner.
When client.changepasswordpage is not set, clicking "Change Password" button, redirects the user to the default Change Password Page provided by Convergence.
When client.changepasswordpage is set, clicking "Change Password" button, redirects the user to the configured password management page to change the password.
Convergence handles password policies applied to user in Directory Server.
When client.changepasswordpage is not set and a user logins with the expired password, a warning message is displayed in the Convergence Login page.The user has to contact system administrator to change the password for this user.
When client.changepasswordpage is set and a user logins with the expired password, a warning message is displayed in the Convergence Login page along with the "Change Password" button. The UserName, Password fields and "Sign In" buttons will be disabled on the Login page. Clicking "Change Password" button, redirects the user to the configured password management page to change the password.
Convergence handles password policies applied to user in Directory Server.
When client.changepasswordpage is not set and a user logins with the new password provided by administrator, user can login to Convergence. Depending on the password policy rules, user will be forced to change the password using the Change Password dialog box that appears.
When client.changepasswordpage is set and a user logins with the new password provided by administrator, a warning Message is displayed on the Convergence Login page along with the "Change Password" button. The UserName, Password fields and "Sign In" button will be disabled on the Login page. Clicking "Change Password" button, redirects user to the configured password management page to change the password.
In a Convergence deployment with multiple domains, users can login to a domain by typing the URL and suffix the domain name to the user name.For example, user1@siroe.com.
To set a different Change Password page for a domain, set the client.{domain-name}.changepasswordpage configuration property by typing the following command.
iwcadmin -o client.{domain_name}.changepasswordpage -v <URL to the password management page>
where, domain_name is the domain name.
When client.{domain-name}.changepasswordpage is set, the Change Password tab in Convergence Global Options displays a link to the configured password management page for the users of the specified domain.
The following scenarios apply:
Convergence handles password policies applied to user from each domain in Directory Server.
When a user login with the password that is about to expire, the "Change Password" and "Remind me Later" buttons are displayed in the Convergence banner.
When the client.changepasswordpage and the client.{domain-name}.changepasswordpage are not set, clicking "Change Password" button redirects the users from all the domains to the default Change Password Page provided by Convergence.
When the client.changepasswordpage is set and the client.{domain-name}.changepasswordpage is not set, clicking "Change Password" button, redirects the users from all the domains to the configured password management page to change the password.
When the client.changepasswordpage is set and the client.{domain-name}.changepasswordpage is set for domain_name1, clicking "Change Password" button:
Redirects the users from domain_name1 to the password management page configured for the domain_name1.
Redirects the users from other domains to the configured password management page defined by the client.changepasswordpage.
When the client.changepasswordpage is not set and the client.{domain-name}.changepasswordpage is set for domain_name1, clicking "Change Password" button:
Redirects the users from domain_name1 to the password management page configured for the domain_name1.
Redirects the users from other domains to the default Change Password page provided by Convergence.
Convergence handles password policies applied to user from each domain in Directory Server.
When the client.changepasswordpage, the client.{domain-name}.changepasswordpage are not set and user logins with the expired password, a warning message is displayed in the Convergence Login page.The user has to contact system administrator to change the password for this user.
When the client.changepasswordpage is set, the client.{domain-name}.changepasswordpage is not set, and a user logins with the expired password, a warning message is displayed in the Convergence Login page along with the "Change Password" button. The UserName, Password fields and "Sign In" button will be disabled on the Login page. Clicking "Change Password" button, redirects the users from all the domains to the configured password management page to change the password.
When the client.changepasswordpage is set, the client.{domain-name}.changepasswordpage is set for domain_name1, and a user logins with the expired password, a warning message is displayed in the Convergence Login page along with the "Change Password" button. Clicking "Change Password" button:
Redirects the users from domain_name1 to the password management page configured for the domain_name1.
Redirects the users from other domains to the configured password management page defined by the client.changepasswordpage.
When the client.changepasswordpage is not set and the client.{domain-name}.changepasswordpage is set for domain_name1, and a user logins with the expired password, a warning message is displayed in the Convergence Login page along with the "Change Password" button.
For the users from domain_name1, clicking "Change Password" button, redirects the user to the password management page configured for the domain_name1.
For the users from other domains, the "Change Password" button is not displayed and they have to contact system administrator to change the password.
Convergence handles password policies applied to users from each domain in Directory Server.
When the client.changepasswordpage, the client.{domain-name}.changepasswordpage are not set and a user logins with the new password provided by administrator, the user can login to Convergence. Depending on the password policy rules, user from all the domains will be forced to change the password using the Change Password dialog box that appears.
When client.changepasswordpage is set, client.{domain-name}.changepasswordpage is not set, and a user logins with the new password provided by administrator, a warning message is displayed on the Convergence Login page along with the "Change Password" button. The UserName, Password fields and "Sign In" button will be disabled on the Login page. Clicking "Change Password" button, redirects user to the configured password management page to change the password.
When client.{domain-name}.changepasswordpage is set for domain_name1, client.changepasswordpage is set, and a user logins with the new password provided by administrator, a warning message is displayed in the Convergence Login page along with the "Change Password" button. The UserName, Password fields and "Sign In" button will be disabled on the Login page. Clicking "Change Password" button:
Redirects the users from domain_name1, to the password management page configured for the domain_name1.
Redirects the users from other domains to the configured password management page defined by client.changepasswordpage.
When the client.changepasswordpage is not set, the client.{domain-name}.changepasswordpage is set for domain_name1, and a user logins with the new password provided by administrator.
For the users from domain_name1, a warning message is displayed in the Convergence Login page along with the "Change Password" button. The UserName, Password fields and "Sign In" button will be disabled on the Login page. Clicking "Change Password" button, redirects the user to the password management page configured for the domain_name1.
Users from other domains can login to Convergence. Depending on the password policy rules, the user will be forced to change the password using the Change Password dialog box that appears.
You can configure Convergence to automatically log users out of the session after a specified number of minutes. By default, auto logout is set to 15 minutes. To configure auto logout, set the client.autologouttime property, as shown in the following example:
iwcadmin -o client.autologouttime -v logout_time
Where logout_time is an integer equal to or greater than zero. Set client.autologouttime to zero to disable auto logout, preventing Convergence from logging out users for inactivity.
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 privileges to manage directory server 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 ldapmodify 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 |