Chapter 17 Configuring the Communication Channels

This chapter provides information on the communication channels for Sun™ Java System Portal Server, starting with general descriptive information, moving to an explanation of the state of the communication channels after installation but before configuration, and finally leading into a description of various steps for configuring the communication channels according to a site’s needs.

The information provided on configuration makes up the bulk of this chapter and includes administrator and end user configuration. End users have the ability to edit the configuration of each channel directly from the Portal Desktop by clicking the edit button accessible in each channel. This gives end users access to an edit page (or edit pages) that allows editing of specific server configuration information and that allows editing of specific features visible to the end user in the channel, such as the number of address book entries visible in the Address Book channel.

Furthermore, if a site has more than one instance of a particular application available—for example, two or more instances of a mail application—administrators can allow end users to configure a second Mail channel on their Portal Desktops; For more information, see Enabling End-Users to Set Up Multiple Instances of a Communication Channel Type.

Overview of the Communication Channels

Supported Software for the Communication Channels

The Installer and the Communication Channels

Configuration Tasks for the Communication Channels

Overview of the Communication Channels

The Sun Java System Portal Server product offers four communication channels that are accessible by end users directly in Portal Desktop. These channels allow end users access to corresponding applications—such as a mail application— which enable end users to organize, schedule, and communicate more effectively and efficiently.

The Address Book channel displays address book entries for end users to view. To access the address book in order to create and edit address book entries, first click Launch Address Book.

Calendar Channel The Calendar channel displays calendar events and tasks for end users to view. To access the calendar application in order to create new tasks and events, first click Launch Calendar.

The Instant Messaging Channel displays the presence status of other users with access to Sun™ Java System Instant Messenger. These contacts are from a list end users have created within the Instant Messenger application. Initiate a chat from the channel by clicking a presence status icon, which is one method of invoking Instant Messenger. To get presence updates directly from the channel, reload Portal Desktop. To receive presence updates as they occur, view contacts’ presence status from Instant Messenger by invoking the application; therefore, click Instant Messenger.

Mail Channel The Mail channel displays mail messages sent to end users for them to view. To access the mail application in order to read and compose messages, click Launch Mail.

Supported Software for the Communication Channels

The Sun Java System Portal Server software supports the following resource server platforms for the Communication Channels:

Sun™ Java System Messaging Server 5.2, 6.0, 6 2004Q2

Sun™ Java System Calendar Server 5.1.1, 6.0, 6 2004Q2

Sun™ Java System Instant Messaging Server 6.1, 6 2004Q2

IBM Lotus Notes 5.0.6

Microsoft Exchange Server 2000

The Installer and the Communication Channels

The Sun Java System Portal Server installer performs several tasks involving the communication channels. General communication channel configuration tasks are also handled by the installer. More detailed configuration is then required by administrators and end users depending up the needs of the site and of the individuals.

Sun Java System Portal Server Installer Tasks

installs the following packages, SUNWpsso, SUNWpsap, SUNWpsmp, SUNWpscp, and SUNWiimps which are deployed to the default Sun Java System Portal Server instance. Therefore, the installer does not install the communication channels on all of the Sun Java System Portal Server instances. For information on multi-server deployments, see Multiple Instance Deployments.

creates the channels, Address Book, Calendar, Instant Messaging, and Mail. The installer places channels for Sun Java System servers into the My Front Page Tab panel container for the sample organization. Therefore, the communication channels are installed only when the sample portal is installed. Microsoft Exchange Server and IBM Lotus Notes server are not automatically placed in a container. An administrator would need to add these channels to a container, if desired.

creates and configures the single sign-on (SSO) Adapter service which enables single sign-on with the Sun Java System Calendar Server and Sun Java System Messaging Server.

Multiple Instance Deployments

If you have a multi Sun Java System Portal Server deployment, manually deploy the communication channels to each additional instance of Sun Java System Portal Server and restart each instance. To deploy, type:

PortalServer-base/SUNWps/bin/deploy redeploy -instance instancename -deploy_admin_password deployadminpassword

Where instancename is the name for that particular non-default instance and deployadminpassword is the administrator password for the web container (web server or application server). The web container administrator password is only needed when the web container is Sun™ Java System Application Server or BEA WebLogic Server™. It is not problematic if you include the password when using one of the other acceptable web containers: Sun™ Java System Web Server or IBM WebSphere® Application Server; however, in those cases the password will be ignored.

Code Example 17-1 lists the commands for manually deploying communication channels to two non-default Sun Java System Portal Server instances and for restarting those instances, where myinstance1 and myinstance2 are non-default Sun Java System Portal Server instance names and Admin is the web container administrator password.

Configuration Tasks for the Communication Channels

The following are the high-level tasks involved in setting up the communication channels. Not all tasks are applicable to all sites. You need to determine if a task is applicable to your site according to your site’s business requirements.

If you already have Sun Java System Messaging Server and Sun Java System Calendar Server installed either on the same server or on different servers, specify the respective URL when you create a channel.

Enabling Access to Mail and Calendar Applications

Messaging Server and Calendar Server both verify the Internet Protocol (IP) address of the host where the browser requests a login session ID. If the IP address differs from the host IP address where the session ID is issued, Messaging Server and Calendar Server reject the session with a session time out message.

You must change the value of the parameter that enables and disables an IP security check to allow the user to access mail through Portal Server. The parameter that specifies whether to restrict session access to the login IP address, is:

To Disable ipsecurity for Messaging Server

To disable ipsecurity for Messaging Server, perform the following steps in the command line on the machine running the mail server.

Type the following command:

MessagingServer-base/sbin/server5/msg-messaging-server-hostname/configutil -o service.http.ipsecurity -v no

Change to root using the su command.

Stop Messaging Server using this command

MessagingServer-base/sbin/server5/msg-messaging-server-hostname/stop-msg

Start Messaging Server using this command:

MessagingServer-base/sbin/server5/msg-messaging-server-hostname/start-msg

To Disable ipsecurity for Calendar Server

To disable ipsecurity for Calendar Server, perform the following steps in the command line on the machine running the Calendar Server:

Assuming calendar server is installed in /opt/SUNWics5, type the following:

cd /opt/SUNWics5/cal/config/

Edit the ics.conf file and set ipsecurity to no. For example:

service.http.ipsecurity = "no"

Assuming calendar server is installed in /opt/SUNWics5, restart Calendar Server by typing:

/opt/SUNWics5/cal/sbin/stop-cal

/opt/SUNWics5/cal/sbin/start-cal

Refresh or re-authenticate to the Portal Desktop; the “Launch Calendar” link should work.

Configuring the Services for the Default Organization

After the communication channels have been installed, the Instant Messaging and Address Book channels require more detailed configuration as explained subsequently. However, the Calendar and Mail channels have sample or default settings that can work without further configuration by an administrator. Site-specific issues can exist for any of the communication channels—including the Calendar and Mail channels—that deserve attention and might require configuration by an administrator before the channels will work according to the needs of the site.

The following sections provide important information relating to the configuration of the communication channels.

Communication Channel Configuration Information

Regarding All the Communication Channels

End-User Configuration

Unless you configure the communication channels with proxy authentication—see Administrator Proxy Authentication: Eliminating End-User Credential Configuration for more information—end users will still need to go to each channel’s edit page by clicking the edit button in the respective communication channel to further configure the channel.

CAUTION—Undetected Error: Missing Launch Link

If a client port number is entered incorrectly for any of the communication channels, end users will not receive an error message. The error manifests itself by not displaying the launch link for the respective channel, which does not aid end users in identifying the root cause of the problem. Both administrators and end users can enter an incorrect client port number, but since end users can only edit the client port number for the Calendar and Mail channels, those are the only channels where they can create this problem.

Various situations can cause end users not to see a communication channel and not to see an error message explaining the problem. The cause might be a misconfigured template or configuration name, which doesn’t allow the template or configuration to be found. A communication channel does not display when any of the following conditions is true:

The SSOAdapter template is not found.

The SSO Adapter configuration is not found.

The display.template file is not found.

Regarding the Mail Channel

HTTPS Enabled Messaging Server

If the Mail channel is connected to—a more secure—HTTPS enabled messaging server instead of the basic HTTP enabled messaging server, then you will need to make some security-related adjustments for the Mail channel to work as intended. For more information, see Configuring the Mail Provider to Work with an HTTPS Enabled Messaging Server.

Configuring the Instant Messaging Channel

Sun Java System Instant Messaging Server is installed during the installation of Sun Java System Portal Server if the Enable IM in Portal Server option is selected during the Sun Java System Instant Messaging Server installation.

The Instant Messaging channel is based on a Portal Server content provider called IMProvider. The IMProvider is an extension of the JSPProvider in the Portal Server. As an extension of the JSPProvider, IMProvider uses the JSP files to generate the content page and the edit page for the Instant Messaging channel. The JSP files are also used to generate the pages used to launch the Instant Messenger. The IMProvider also defines an instant messaging-specific tag library and this tag library is used by the JSP files. The JSP files and the tag library use the channel properties that are defined by the IMProvider.

For more information on Sun Java System Instant Messaging Server, see Instant Messaging Administrator’s Guide. For information specific to the Sun Java System Portal Server Instant Messaging Channel tag library and the customization of Instant Messaging Channel through the editing of JSP files, see Sun Java System Portal Server 6 2005Q1 Desktop Customization Guide. Furthermore, administrators and end users can access information about Sun Java System Instant Messaging Server by visiting the URL used in the codebase property for the Instant Messaging Channel configuration.

To Configure the Instant Messaging Channel

From an Internet browser, log into the Sun™ Java System Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Identity Management tab to display the View drop down list in the navigation pane (the lower left frame).

Select Services in the View drop down list to display the list of configurable services.

Under the Portal Server Configuration heading, click the arrow next to Portal Desktop to bring up the Portal Desktop page in the data pane (the lower right frame).

Click the Manage Channels and Containers.

Scroll down to the Channels heading and click Edit Properties next to IMChannel to display the Instant Messaging service panel, which includes Basic Properties.

The following is a partial list of the properties displayed in the Edit IMChannel page with example values provided for each property.


Property	Example Value
authMethod	idsvr
authUsernameAttr	uid
clientRunMode	plugin
codebase	imapplet.example.com
contactGroup	My Contacts
mux	imserver.example.com
muxport	49909
netletRule	IM
password	(not applicable when idsvr is used for authmethod)
port	49999
server	imserver.example.com
username	(not applicable when idsvr is used for authmethod)

In the text field next to each property you want to input, enter the desired value. Table 17-1 describes the properties and the type of information to enter as a value.

Table 17-1 Property and Value Description for Edit IMChannel Page
Property	Value
authMenthod	It is usually preferable to enter idsvr as the value, which indicates that the authentication method to be used is the Sun Java System Access Manager authentication method. Two values are possible, idsvr or ldap. The idsvr value enables Single Sign-On to work. It also removes the username and password fields from the Instant Messaging channel edit page.
authUsernameAttr	Enter the name of the attribute to use for the user name when authenticating using the idsvr authentication method.
clientRunMode	Enter the method for running the Instant Messaging client: plugin or jnlp (which is used for Java Web Start).
codebase	Enter the URL prefix from which the Instant messaging client is downloaded.
contactGroup	Enter the name of the contact group that is displayed in the Instant Messaging channel.
mux	Enter the hostname of the Sun Java System Instant Messaging Multiplexor to be used when the Instant Messaging client is launched by the channel.
muxport	Enter the port number associated with the Sun Java System Instant Messaging Multiplexor. The default port number is 49909.
netletRule	Enter the name of the netlet rule that is used with the Instant Messaging client when in secure mode via the Secure Remote Access (SRA) gateway.
password	Enter the password to use when authenticating using the LDAP method. When stored in the display profile, this property is obfuscated using the AMPasswordUtil class.
port	Enter the port number associated with the Sun Java System Instant Messaging Server to be used by the channel. The default port number is 49999.
server	Enter the hostname of the Sun Java System Instant Messaging Server to be used by the channel.
username	Enter the username to use when authenticating using the LDAP method.

Scroll as needed and click Save.

Additional Configuration for the Instant Messaging Channel

Steps Might be Required to Allow Multiple Organizations

When a Portal Server instance serves multiple organizations but uses a single Instant Messaging server additional steps must be taken.

Access Manager and Portal Server allow administrators to set up users with the same User ID (uid) across an organization. For example, an organization could have two suborganizations that each have an end user named enduser22. This creates a conflict when these two end users attempt to access their respective accounts through the Instant Messaging channel.

To avoid this potential conflict, one set of JSP launch pages per organization must be created to contain a pass-in-the-parameter domain set to the value of the organization’s attribute sunPreferredDomain. The default launch pages are:

Inserting Instant Messenger Links in an Organization

By default the Instant Messenger links are added to the Application channel—which provides the links to launch various applications—in the default organization. The Instant Messenger links allow the Instant Messenger to be launched from the Application channel. You need to add Instant Messenger links manually, if:

you want to add these links for another organization.

you do not have the sample portal installed.

you are using the AppProvider for another channel.

The contents for the Instant Messenger links are in the file PortalServer-base/SUNWps/samples/InstantMessaging/dp-IMChannel.xml. The dp-IMChannel.xml file also contains the sample IMChannel.

Edit a copy of the file dp-IMChannel.xml to add the Instant Messenger links information to the display profile for another organization and install the file using the dpadmin command as follows:

Change to the following directory:

Create a copy of the dp-IMChannel.xml file as follows:.

To modify the Application channel, type the following dpadmin command:

dpadmin modify -u ADMIN_DN -w PASSPHRASE -d ORG_DN -m newfile.xml

Enabling Secure Mode for Sun Java System Instant Messenger in Sun Java Server Portal Server

Netlet facilitates secure communication between the Instant Messenger and the server.


Note	The Instant Messaging channel automatically uses the secured mode when accessed through the Secure Remote Access gateway. The Instant Messaging channel does not use the secured mode when it is not accessed through the gateway.

From an Internet browser, log into the Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Identity Management tab to display the View drop down list in the navigation pane.

Select Services in the View drop down list to display the list of configurable services.

Scroll down to SRA Configuration and select Netlet.

Click the arrow icon beside Netlet. The Netlet Rules are displayed in the right panel.

Click Add under Netlet Rules.

Type IM in the Rule Name field.



Note	The Netlet rule name can be different. You can configure the Instant Messaging channel to use a different Netlet rule.

Remove the default value in the URL field and leave the field blank.

Select the Download Applet check box and enter the following string:

$IM_DOWNLOAD_PORT:$IM_HOST:$IM_PORT

For example:

49916:company22.example.com:80

where,

IM_DOWNLOAD_PORT. The port on which Instant Messaging resources are downloaded using Netlet.

IM_HOST. The host name of the web container serving Instant Messenger. For example: company22.example.com

IM_PORT. The port number of the web container serving the Instant Messenger. For example, 80.

Select the default value in the Port-Host-Port List and click Remove.

Enter the local host port on which Netlet will run in the Client Port field. For example: 49916.

Enter the Instant Messaging Multiplexor host name in the Target Host(s) field.

Enter the Instant Messaging Multiplexor port in the Target Port(s) field.



Note	The values for Netlet Port, Instant Messaging Host, and Instant Messaging Port should be the same as the Instant Messaging service attributes mentioned in the Instant Messaging service panel as discussed in the final steps of To Configure the Instant Messaging Channel.

Click Add to List.

Click Save to save the Netlet Rule.

Disallowing Users from Launching Instant Messenger

You can remove the ability for users to use the Instant Messaging channel by removing the channel from the user's display profile. For example, to remove the sample IMChannel that is automatically installed, do the following:

From an Internet browser, log into the Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Identity Management tab to display the View drop down list in the navigation pane.

Select Services in the View drop down list to display the list of configurable services.

Click the arrow icon next to the Portal Desktop service.

Click the Manage Channels and Containers Link.

Select the check box to the left of the IMChannel channel.

Scroll as needed and click Delete to delete the channel.

Configuring the Address Book Channel

For the Address Book channel to work, you need to configure the defaults for the Address Book service. Because the AddressBookProvider is not pre-configured, any channel the user creates based on the AddressBookProvider will not appear on the user’s Desktop or on the Content link unless the AddressBookProvider has been configured.

Configuring the Address Book Service Defaults

This section provides information about single sign-on (SSO) Adapter templates. These templates globally affect the display of the communication channels on users’ portal Desktops. To alter the display profile of users for the communication channels, you will need to edit or create SSO Adapter templates and configurations.


Note	Creating channels based on the other communications channels in the pre- populated, user-defined channels set may result in the created channel displaying the message: “Please specify a valid configuration.” Although the other Communication Channels are defined to a sufficient extent to appear on the user’s Desktop, they require additional administrative tasks in order to ascertain which backend service to use. Additionally, the communication channels require the desktop user to specify backend credentials (such as username and password) after the administrative tasks are completed. The desktop user can specify these values in the channel by using the channel’s Edit button.


Note	The userDefinedChannels set might need to be administered on a per install basis because this set includes references to backend services which might not apply to your particular setup. For example, all Lotus Providers in this set refer to interaction with Lotus backend services for the communication channels which do not apply if none in the Portal user base will be using Lotus backend services.

This chapter only discusses templates for Address Book. Even for Address Book, the discussion here is very specific. For a broader explanation of SSO Adapters, SSO Adapter templates, and SSO Adapter configurations, see Appendix A, "SSO Adapter Templates and Configurations".

To Configure the Address Book Service Defaults

From an Internet browser, log into the Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Service Configuration tab to display the list of configurable services in the navigation pane.

Scroll down the navigation pane to the Single Sign-on Adapter Configuration heading and click the arrow next to the item SSO Adapter, which brings up the SSO Adapter page in the data pane.

Click New under SSO Adapter Configuration to add an SSO adapter configuration.

The New Configuration page appears.

Type a configuration name and select SUN-ONE-ADDRESS-BOOK from the menu.

Click Next.

The Configuration Properties page appears.

Modify the properties as needed.

Scroll down the SSO Adapter page and click Save.

When done, click Save.

For more information about the attributes in an SSO Adapter template string, see Appendix A, "SSO Adapter Templates and Configurations".

Configuring End-User Channel Settings

Log into the Desktop as the new user:

From an Internet browser, go to:

http://hostname.domain:port/portal/dt, for example http://psserver.company22.example.com:80/portal/dt

Enter the user ID and password.

Click Login.

Click the Edit button of each channel to configure the server settings.

To configure the Mail channel settings:

Server Name. Enter the host name of the mail server. For example, mailserver.example.com.

IMAP Server Port. Enter the mail server port number.

SMTP Server Name. Enter the name of the Domain Name Server (DNS) of the outgoing mail—Simple Mail Transfer Protocol (SMTP)— server.

Client Port. Enter the port number configured for HTTP service.

User Name. Enter the mail server user name.

User Password. Enter the mail server user password.

When sending a message place a copy in Sent Folder. Check this box to store copies of your outgoing messages in the Sent folder.

Finished. Click this button to save the mail configuration.

Cancel. Click this button to close the window without saving the configuration details.

To configure Address Book channel settings:

The IMAP user ID and Password are the same as the User Name and User Password entered when configuring the mail channel settings. For details, refer to the previous bulleted item,To configure the Mail channel settings:

User Name. Enter your User Name.

Password. Enter you Password.

Finished. Click this button to save the server information.

Cancel. Click this button to close the window without saving the details.

To configure the Calendar channel settings:

Server Name. Enter the calendar server host name. For example, Calserver.example.com.

Server Port. Enter the calendar server port number.

User Name. Enter the calendar server user name.

User Password. Enter the calendar server user password.

Finished. Click this button to save the calendar configuration.

Cancel. Click this button to close the window without saving the details.

To configure the Instant Messaging channel settings:

Contact List. Select the desired contact list whose contacts will be displayed in the Instant Messaging Channel.

Launch Method. Select the desired launch method:
Java Plugin or Java Web Start.

Server. Enter the Sun Java System Instant Messaging Server name. For example:
IMserver.example.com

Server Port. Enter the Sun Java System Instant Messaging Server port number. For example:
49999

Multiplexor. Enter the Multiplexor name, which must be the same machine as the Sun Java System Instant Messaging server. For example:
IMserver.example.com

Multiplexor Port. Enter the Multiplexor port number. For example:
49909

User Name. (This field only appears when the authentication method is set to the Sun Java System Access Manager authentication method, idsvr) Enter the Sun Java System Instant Messaging user name.

User Password. (This field only appears when the authentication method is set to the Sun Java System Access Manager authentication method, idsvr) Enter the Sun Java System Instant Messaging user password.

Finished. Click this button to save the Sun Java System Instant Messaging Server configuration.

Cancel. Click this button to close the window without saving the details.



Note	The Address Book, Calendar, and Mail channels each have display options that can be set by the user and by default cannot be overwritten by an administrator. After logging into the Portal Desktop, the user can change the display options for a channel by clicking the edit button in the panel for that channel. The display options are clearly marked and easily changed. In Address Book, a display option that users can change is the Number of Entries option; in Calendar, a display option that users can change is the Display Day View option; in Mail, a display option that users can change is the Number of Headers option. Changes made by users to the default communication channels display options take precedence. Any future changes made by administrators will not automatically take effect and a new channel added by administrators will not automatically be accessible by users.

Application Preference Editing: Configuring Communication Channel Edit Pages

You can configure the edit pages that end users will see after they click the edit button in a communication channel’s toolbar for the Address Book, Calendar, and Mail channels. The Instant Messaging channel does not use application preference editing. For information about configuring the Instant Messaging Channel’s edit page, see Sun Java System Portal Server 6 2005Q1 Desktop Customization Guide.

For the three communication channels that allow application preference editing, you can change which options are available for end users to edit, the names and wording that accompany those options, and the way the options are formatted. Configuration of the communication channels edit pages can be performed in the display profile, various HTML templates, and an SSO Adapter template. You might also need to access an SSO Adapter configuration. These items together are involved in the configuration of the edit pages.

This section gives only a brief explanation of application preference editing. Other chapters in this guide and the Sun Java System Portal Server 6 2005Q1 Desktop Customization Guide provide a more complete explanation of the template files and the display profile, including how they interact with each other and how you can access and edit them.

Display Profile Attributes for the Edit Pages

The communication channels have two collections in their display profile that drive the creation of the edit pages, ssoEditAttributes and dpEditAttributes.

You can edit these collections by accessing the Sun Java System Access Manager admin console. Either download the display profile—to edit the XML code before uploading it back to the directory server—or edit specific properties in these collections using only the admin console.

The ssoEditAttributes collection controls the editing of the attributes contained by the SSO Adapter service—such as user name and user password—while dpEditAttributes controls the editing for the display profile attributes—such as sort order and sort by, which are options that by default are editable by end users.

Therefore, these collections list the attributes that can be edited and also contain information on the type of input and the header for the input string to use. For example:

The name in the collection must match the name of the corresponding display profile SSO Adapter attribute. The value portion of the item contains two pieces of information separated by the “|” character. The first part of the value string specifies what the display type is for the attribute. The second part of the attribute’s value string specifies the text that will be displayed next to the item. The list below specifies how the type relates to a corresponding HTML GUI item:

string - Creates a text field where alphanumeric characters can be entered

password - Creates a password field where the input is replaced with “*”

check - Creates a checkbox

select - Creates a select box. Every select item must have a corresponding collection with a list of values and display text

For every select display type you must have a corresponding collection that lists the value to be returned and the display value for the option. The collection name must be made up of the name value for the attribute and the text SelectOptions. For example, for the sortOrder attribute in the MailProvider, the collection name is sortOrderSelectOptions:

HTML Templates for the Edit Pages

There are nine HTML templates used to create the edit pages for the communication channel providers. The templates were created to be very generic in order to correspond to specific browser GUI types. They mostly relate to specific HTML inputs in the edit pages. The edit-start.template and the edit-end.template are exceptions in that they contain most of the HTML that is used for page layout. Table 17-2 contains a description of each template name and how it relates to the GUI types. Some of the templates are used to start, end and separate the attributes. These templates are available for each of the communication channels at:

For example, the templates for the Calendar channel edit pages can be accessed at:

A Display Profile Example

This example demonstrates how certain SSO Adapter attributes work together with their corresponding display profile attributes to give end users the ability to change the entries for specific features in a communication channel’s edit page, thereby changing how the communication channels are configured and displayed on their Portal Desktops.

Table 17-2 Templates for the Communication Channel Edit Pages
Template	Description
edit-start.template	Provides the starting HTML table for the edit page.
edit-checkbox.template	Provides a generic template for checkbox items.
edit-separate.template	Separates the display profile attributes from the SSO attributes.
edit-end.template	Ends the HTML table for the edit page.
edit-password.template	Provides a generic template for password items.
edit-string.template	Provides a generic template for text items.
edit-select.template	Provides a generic template for a select item.
edit-selectoption.template	Provides a generic template for a select option. This way the option can also be generated dynamically from the display profile.
edit-link.template	Provides a template to generate the link so the user can edit their client’s display attributes.

The SSO Adapter template in Code Example 17-2 is for a sample mail channel. The SSO Adapter template contains two merged attributes:

uid - User ID

password - User password

A merged attribute is an attribute that end users can specify. Administrators decide which attributes are merged, therefore, which attributes they want end users to be able to edit.

Code Example 17-3 contains the channel’s display profile XML fragment for the channel’s ssoEditAttributes.

After administrators have set an attribute to merge in an SSO Adapter template, they can then edit that attribute in the display profile in order to reconfigure how the attribute is displayed to end users in an edit page and how end users can edit it. Administrators can decide how end users are queried for the necessary information by editing the proper display profile collection. For example, in this example, administrators could replace User Name with the question, What is your user name? The use of the string attribute display type before the “|” symbol is the most likely choice. However, it’s possible for an administrator to change this to the password type or to another type.

For this example, in the Mail channel edit page, end users will see text fields titled:

User Name:

User Password:

Enabling End-Users to Set Up Multiple Instances of a Communication Channel Type

Multiple types of communication channels can be created by end users or administrators. For end users to create multiple types of communication channels, they will need to utilize the Create a new channel link found on the Content page.

Administrators can create multiple channels for an organization, role, or group. After administrators have made multiple instances of a particular component available—for example, a second instance of the address book component—they can allow end users to configure a second Address Book channel on their Portal Desktops.

Administrators can create an SSO Adapter template for each new communication channel type or they can use one SSO Adapter template and create multiple SSO Adapter configurations for each channel. For more information, see the SSO Adapter documentation in Appendix A, "SSO Adapter Templates and Configurations".

Depending on the amount of configuration done by the administrator, the end users may not need to enter as many configuration settings. Administrators can configure these settings by utilizing the application preference editing feature (see Application Preference Editing: Configuring Communication Channel Edit Pages).

To create two Address Book channels, you make each refer to a different SSO adapter template. You can then add both Address Book channels to the visible page you just came from. Likewise, you can create one SSO Adapter template and two SSO Adapter configurations (dynamic). The SSO Adapter template would define the server settings as user definable values (merge) and the SSO Adapter configuration would then specify those server settings.

To configure the address book for different servers where end users can configure the servers as needed:

Specify the server information as user definable, merge, in the SSO Adapter template. For more information, see Appendix A, "SSO Adapter Templates and Configurations".

Specify which attributes are editable in the channel’s display profile ssoEditAttributes collection. For more information, see Application Preference Editing: Configuring Communication Channel Edit Pages and for specific information about the display profile, see the Sun Java System Portal Server 6 2005Q1 Desktop Customization Guide.

Administrator Proxy Authentication: Eliminating End-User Credential Configuration

You can enable administrator proxy authentication for the Address Book, Calendar, and Mail channels. Extending support for proxy authentication between the Sun Java System Portal Server and Sun Java System Messaging Services (Messaging Server and Calendar Server) eliminates the need for end users to visit a channel’s edit page in order to enter their credentials: user name and user password. An administrator’s credentials are used instead of end-users’ credentials and they are stored in the SSO Adapter template. Within the template, the administrator’s User ID is stored as a value for the proxyAdminUid attribute while the administrator’s password is stored as a value for the proxyAdminPassword attribute. Every time a user launches a channel, these values are used to make a connection between a channel and its respective back-end server. A naming attribute for the user is also sent to the back-end server. For more information on the use of naming attributes for administrator proxy authentication, see the userAttribute property in Table 17-3.

Proxy authentication cannot be configured for Sun Java System Instant Messaging Server, Microsoft Exchange Server, or IBM Lotus Notes server.

CAUTION—Potential for Multiple End Users to be Directed to One Mail Account

Access Manager and Portal Server allow administrators to set up users with the same User ID across an organization. For example, the organization could have two suborganizations that each have an end user named enduser22. If administrator proxy authentication is enabled for a Sun Java System communication channel and the end user naming attribute is set to the default, uid, then both users could potentially access the same back-end user account. Administrator proxy authentication enables administrators to change the user naming attribute in the SSO Adapter template. For example, you can change the attribute to an attribute that is unique for each employee, such as employee number, to ensure that portal end users access the correct back-end server account.

Overview of How to Configure Proxy Authentication

In order to enable administrator proxy authentication for the Address Book, Calendar, and Mail channels, you need to access the SSO Adapter templates through the Sun Java System Access Manager admin console and you need to access the Sun Java System communication servers. More specifically, you need to:

Edit SSO Adapter Templates.

access Sun Java System Messaging Server to enable proxy authentication for the Address Book and Mail channels

access Sun Java System Calendar Server to enable proxy authentication for the Calendar channel.

Proxy Authentication and Single Sign-On (SSO) Adapter Templates

To Edit SSO Adapter Templates For Enabling Administrator Proxy Authentication

From an Internet browser, log into the Sun Java System Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Service Configuration tab to display the list of configurable services in the navigation pane.

Select SSO Adapter to display the page for configuring the SSO Adapter in the data pane.

Click the string for the channel that you want to enable with administrator proxy authentication.

Click in the configuration description field.

Delete and key in the necessary information for administrator proxy authentication:

Table 17-3 describes the properties that need to be edited in the SSO Adapter Template to enable support for administrator proxy authentication.

Table 17-3 SSO Adapter Template Properties for Administrator Proxy Authentication
Property	Value	Description
enableProxyAuth	true \| false	The value associated with this attribute is a flag to indicate if proxy authentication is enabled or not. If true the SSO Adapter and Application Adapter will perform proxy authentication. For example, &enableProxyAuth=true
proxyAdminUid	(configurable)	The value associated with this attribute is the administrator’s user name. For example, &proxyAdminUid=ServiceAdmin
proxyAdminPassword	(configurable)	The value associated with this attribute is the administrator’s user password. For example, &proxyAdminPassword=mailpwd
userAttribute	(configurable)	The value associated with this attribute is the user’s naming attribute. This value is mapped to an attribute on the user’s record (the user’s entry in the directory). A typical record has several attributes, including the User ID (uid) and employee number. By default, the naming attribute is set to uid. For example, &userAttribute=uid By editing the SSO Adapter template, you can map the naming attribute to another attribute, such as employee number.
The preceding four properties appear in the SSO Adapter template string again, as shown subsequently. The configuration of the properties can be set to either default or merge. In the following examples, they are all set to default.
Property	Value	Example
enableProxyAuth	default	&default=enableProxyAuth
proxyAdminUid	default	&default=proxyAdminUid
proxyAdminPassword	default	&default=proxyAdminPassword
userAttribute	default	&default=userAttribute

Proxy Authentication and Communication Servers

Setting Up Sun Java System Messaging Server for Administrator Proxy Authentication

Type the following code:

MessagingServer-base/msg-instance-name/configutil -o service.http.allowadminproxy -v yes

Restart the Messaging Server.

See the Sun Java System Messaging Server Administrator’s Guide for detailed instructions on running configutil and restarting the server.

Setting Up Calendar Server for Administrator Proxy Authentication

Open the following file with the editor of your choice:

CalendarServer-base/cal/bin/config/ics.conf

Set the following attribute as shown:

service.http.allowadminproxy = "yes"

Restart the calendar server.

See the Calendar Server Administrator’s Guide for detailed instructions on restarting the server.

Configuring a Read-Only Communication Channel for the Authentication-Less Portal Desktop

The authentication-less (authless anonymous) Portal Desktop supports read-only communication channels.

Read-Only Communication Channels Facts and Considerations

You can configure read-only access to Address Book, Calendar, and Mail channels for the authless anonymous Portal Desktop. End users can access the information in a read-only communication channel by simply accessing the Portal Desktop; therefore, by entering the following URL in an Internet browser:

http://hostname.domain:port/portal/dt, for example http://psserver.company22.example.com:80/portal/dt

Without logging in, end users have access to any read-only communication channels that administrators have configured. However, end users are usually prevented from editing these channels. For more information about the authentication-less Portal Desktop, including enabling anonymous log in, see the Sun Java System Portal Server 6 2005Q1 Desktop Customization Guide.

The calendar channel is the channel most commonly shared by multiple users; therefore, the following steps are for configuring a read-only calendar channel. In this example, the calendar being shared belongs to user library. The public read-only calendar is titled Library Schedule. The following calendar set up demonstrates one possible approach. For more information about setting up users for the Sun Java System Calendar Server, see the create userid option of the csuser command in the Sun Java System Calendar Server Administrator’s Guide

To Set Up a Calendar User

Create a calendar user by issuing a command such as the following:

csuser -g Library -s Admin -y libadmin -l en -m libadmin@library.com -c librarySchedule create libadmin

Where user libadmin has a given name of Library, surname of Admin, password of libadmin, preferred language of en (English), email address of libadmin@library.com, and calendar ID of librarySchedule.

Set the access permissions to world readable for:

libadmin:librarySchedule

You can set the access permissions using the cscal utility or the end user can do this using Calendar Express.

To Configure a Read-Only Communication Channel

Configure the settings for the end user—which in this case is authless anonymous—and create a calendar SSO adapter configuration.

From an Internet browser, log on to the Sun Java System Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Identity Management tab to display the View drop down list in the navigation pane.

Click Users in the View drop down list.

Scroll down as needed to the authless anonymous user and click the accompanying arrow to bring up the authlessanonymous page in the data pane.

Now you can add the SSO Adapter service to the authless anonymous user.

Click Services in the View drop down list within the authlessanonymous page to display the available services.

Click Add.

Click the checkbox for SSO Adapter

Click Save.

Create a calendar SSO Adapter configuration for the authless anonymous user.

If not already logged in, log into the Sun Java System Access Manager admin console.

Click the Identity Management tab to display the View drop down list in the navigation pane.

Select Services in the View drop down list to display the list of configurable services.

Click the arrow next to SSO Adapter to bring up the SSO Adapter page in the data pane.

In the blank configuration description field, type in a group-oriented SSO Adapter configuration string (with a User ID and password). A typical configuration has been provided subsequently for your reference. The attributes available in this string can vary depending upon how you configured the Sun Java System Portal Server SSO Adapter template. By default the SSO Adapter template expects the user to specify the following information:

host

port

client port

uid

password

If the configuration description field is not blank when you get to it, select all the text in the field and delete it before entering a string in the following format:

default|undef://?uid:password@host:port/?
configName=configuration-name
&configDesc=configuration-description

For example:

default|undef://?libadmin:libadmin@example.com:3080/?
configName=sunOneCalendar_librarySchedule
&configDesc=SUN-ONE-CALENDAR

Click Add.

Click Save.

Create a new calendar channel for the authless anonymous user that is based on the newly created SSO Adapter configuration.

If not already logged in, log into the Sun Java System Access Manager admin console.

Click the Identity Management tab to display the View drop down list in the navigation pane.

Click Users in the View drop down list.

Scroll down as needed to the authless anonymous user and click the accompanying arrow to bring up the authlessanonymous page in the data pane.

Now you can create a new calendar channel for the authless anonymous user.

Click Portal Desktop in the View drop down list within the authlessanonymous page to display the Edit link.

Click the Edit link.

Click the Channel and Container Management link.

Scroll down to the Channels section and click New.

Enter a name in the Channel Name field. For example:

LibraryScheduleChannel

Choose the correct provider from the provider drop down list. For this example the correct provider is Calendar Provider.

Click OK, which returns you to the Channel and Container Management page.

Now you can edit the channel properties.

Scroll down to the Channels section and click Edit Properties next to your newly created channel. For example:

LibraryScheduleChannel

Edit fields as appropriate. For example:

title: Library Schedule

description: Library Schedule

ssoAdapter: sunOneCalendar_librarySchedule

loadSubscribedCalendars: false (no checkmark)

is editable: false (no checkmark)

Scroll as needed and click Save.

Now you can add the new calendar channel to Portal Desktop of the Authless Anonymous user.

Near the top of the page, click Top, which returns you to the Channel and Container Management page.

Scroll down the Container Channels section and click the link for the container that you want to add the new channel to. For example, MyFrontPageTabPanelContainer. Do not click the accompanying Edit Properties link.

Under the Channel Management heading, click the name of the channel you just created. For example, LibraryScheduleChannel, which is in the Ready For Use list.

Add the channel to the Available to End Users on the Content Page list or to the Visible on the Portal Desktop list.

Click the Add button above the list for which you want to add the channel.

Scroll back up the page to click Save under the Channel Management heading.

Restart the web container.

Configuring Microsoft Exchange Server or IBM Lotus Notes

Besides supporting Sun Java System Messaging Server and Sun Java System Calendar Server for the communication channels, Sun Java System Portal Server 6 also supports Microsoft Exchange Server and IBM Lotus Notes server.

You can configure Microsoft Exchange Server to work with Sun Java System Portal Server, giving end users access to the Microsoft Outlook Web Access solution. End users gain this access after clicking Launch Address Book, Launch Calendar, or Launch Mail in the respective channel on Portal Desktop.

Similarly, you can configure IBM Lotus Notes server to work with Sun Java System Portal Server, giving end users access to the IBM Lotus Domino Webmail solution through the Address Book, Calendar, and Mail channels.

To Configure Microsoft Exchange 5.5 Server for Address Book, Calendar, and Mail


Note	Microsoft Exchange Server and IBM Lotus Notes server do not support administrator proxy authentication or single sign on. Because of the single sign on limitation, when end users launch a channel connected to one of these servers, they will need to reenter their credentials before being connected.

Log into your Primary Domain Controller (PDC) as an administrator of the domain.

Select Start, Programs, Administrative Tools, User Manager for Domains and create an account with user name MAXHost.

Select Groups and add MAXHost to the groups, Administrators, and Domain Admins.

Ensure that MAXHost can log on locally to the MAIL_HOST, Domain Controllers, and MAX_HOST.

Set the password.

Go to Start, Programs, Microsoft Exchange, Microsoft Exchange Administrator.

For each end user, set permissions to the mailbox.

To enable the permissions tab, go to Tools, Options, Permissions, and enable Show Permissions Page for All Objects.

Double-click on the user name.

Select the permissions tab and select Add from the permissions page to add MAXHost and leave role as User.

Repeat steps 9 through 11 for each user who will be accessing the communication channels.

Unzip the ocxhost.zip file located in the following directory:

PortalServer-base/SUNWps/export.

When unzipping the file, you will see the following file format:


Archive: ocxhost.zip
creating: ocxhost
creating: ocxhost/international
inflating:ocxhost/international/ocxhostEnglishResourceDll.dll
inflating:ocxhost/ocxhost.exe

Locate the ocxhost.exe.

Select Start and Run.

Type the following in the Run window:

ocxhost.exe /multipleuse

To set the properties of ocxhost utility:

Configure the necessary DCOM settings for the ocxhost utility using the dcomcnfg utility. That is:

Select Start and Run.

Type dcomcnfg and select OK.

In the Distributed COM Configuration Properties dialog box:

Select Default Properties tab:

Check the Enable Distributed COM on the computer check box.

Set the default Authentication Level to Connect.

Set the default Impersonation Level to Identify.

Select the Applications tab.

Double-click the ocxhost utility in the Properties dialog.

The ocxhost properties window is displayed.

Check Run Application on this Computer under the Location tab.

Set Use custom access permissions, Use custom launch permissions, and Use custom configuration permissions under the Security tab.

Select Edit for the Access, Launch, and Configuration settings and ensure that the following users are included in the Access Control List (ACL):

Interactive

Everyone

System

Select a User under the Identity tab in the ocxhost properties window.

Select Browse and locate the MAXHost.

Enter the password and confirm the password.

Select OK.

The ocxhost DCOM component is now configured and ready to communicate with the Exchange Servers.

To Configure Microsoft Exchange 2000 Server for Address Book, Calendar, and Mail

If the Portal Server should be setup to access Calendar data from an Exchange Server 2000 environment in a complex Windows 2000 Domain configuration ocxhost.exe should be installed on a dedicated System (called MAX_HOST).

It allows easier troubleshooting if a user can not access his calendar from the portal.

It allows a more restrictive security setup if firewall exists between the Portal Server and the Windows Domain.

A “complex” Domain might be if the Exchange Server is a Cluster and/or front-end and a back-end Exchange Server is configured. Or if Windows User and Exchange Mailbox of the same end user are in different Domains.

is the name of the dedicated Windows 2000 System running Outlook 2000 and ocxhost.exe is installed.

When setting up the dedicated Windows 2000 System (MAX_HOST) note the following requirements and assumptions:

Windows 2000 Server SP3 or Windows 2000 Professional.

Microsoft Outlook 2000 with CDO enabled.

The Operating System and Outlook 2000 is installed. Assign an IP Address and bring the new Host in the same Domain as the Exchange Server.

Create a User MAXhost in the Domain.

Log into your Host (MAX_HOST) as an administrator of the domain.

Select Start, Programs, Administrative Tools, Active Directory Users and Computers and create an domain account with user name MAXHost.

Select User->Properties->Member of and add the group Administrators (local)

Ensure that MAXHost can log on locally to the MAIL_HOST and MAX_HOST.

Set the password.

Configure Outlook for MAXHost user.

Configure the Outlook Profile for the user MAXHost by starting Outlook (refer to Microsoft Documentation if required).

Close Outlook after completing the Outlook setup for MAXHost user.

Note: Outlook may not run concurrently with ocxhost.exe.

Configure Microsoft Exchange Server for Address Book, Calendar, and Mail.

If you are using an Exchange 2000 Front-End Server log in to your front-end Server as MAXHost.

Go to Start, Programs, Microsoft Exchange, Active Directory Users and Computers.

For each end user, set permissions to the mailbox.

Select View->Advanced Features

Double-click on the user name.

Select the Exchange Advanced tab and select Mailbox Rights.

Add MAXHost and give MAXHost full access.

Repeat steps Step d through Step g for each user who will be accessing the communication channels.

Install ocxhost.exe on the MAX_HOST.

Unzip the ocxhost.zip file located in the following directory:

PortalServer-base/SUNWps/export.

When unzipping the file, you will see the following file format:

Archive: ocxhost.zip

creating: ocxhost

creating: ocxhost/international

inflating:ocxhost/international/ocxhostEnglishResourceDll.dll

inflating:ocxhost/ocxhost.exe

Locate the ocxhost.exe file.

Select Start and Run.

Type ocxhost.exe /multipleuse and select OK.

Note: Perform this registration only once, because each time this command is executed the DCOM settings described in the next step are cleared and need to be reconfigured.

Configure the necessary DCOM settings for the ocxhost utility using the dcomcnfg utility.

Select Start and Run.

Type dcomcnfg and select OK.

In the Distributed COM Configuration Properties dialog box select Default Properties tab and use the following settings:

Check the Enable Distributed COM on the computer check box.

Set the default Authentication Level to Connect.

Set the default Impersonation Level to Identify.

Select the Applications tab.

Double-click the ocxhost utility in the Properties dialog.

The ocxhost properties window is displayed.

Check Run Application on this Computer under the Location tab.

Set Use custom access permissions, Use custom launch permissions and Use custom configuration permissions under the Security tab.

Select Edit for the Access, Launch, and Configuration settings and ensure that the following users are included in the Access Control List (ACL):

Interactive

Everyone

System

Select a User under the Identity tab in the ocxhost properties window.

Select Browse and locate the MAXHost.

Enter the password and confirm the password.

Select OK.

The ocxhost DCOM component is now configured and ready to communicate with the Exchange Servers. It will be launched by RPC call when the first access from the Portal Server occurs.

Change MAXHost users group.

For security reasons you may want to remove the domain user from the Administrators group:

Log out and login again as Administrator on MAX_HOST.

Remove the user MAXHost from local Administrators group, (and assign it to Domain User Group).



Note	A firewall should not be used between the Portal and the MAX_HOST. (RPC calls using dynamic ports are used for the communication from Portal Server to ocxhost.exe) A firewall should not be used between the MAX_HOST and the MAIL_HOST.

SSO Adapter for Calendar

Set up SSO Adapter for Calendar if you are using a dedicated Server for ocxhost.exe (MAX_HOST).

Create an SSO Adapter template.

Select the Service Configuration Tab.

Select SSOAdapter

Select New.

Enter a name for your new template and select the existing EXCHANGE-CALENDAR from the list.

Select Next.

In the line for the ocxHost enter the dns-name or IP-Address of the system were oxchost.exe resides, in this case MAX_HOST.

Select Save.

Create an SSO Adapter configuration for your organization.

From the Identity Management tab, select your organization.

Select Services from the scroll down menu

Select SSOAdapter.

Under SSO Adapter Configurations, select New.

Enter a name for the configuration and select the previously created Template.

Select Next.

Modify the properties as needed.

You can provide a default Host name which is your MAIL_HOST (DNS name or IP-Address), or you can leave it blank

Select Save and note the message Changes Saved.

Instructions on using SSO Adapter Templates and Configurations can also be found at Appendix A, "SSO Adapter Templates and Configurations."

To Uninstall ocxhost.exe

Locate the ocxhost.exe.

Select Start and Run.

Type the following in the Run window:

ocxhost.exe /unregserver

Delete the files ocxhost.exe and ocxhostEnglishResourceDll.dll

To Configure Lotus Domino Server for Address Book, Calendar, and Mail

Open the Lotus Administrator by selecting Start, Programs, Lotus Applications, and Lotus Administrator.

Go to Administration, Configuration, Server, Current Server Documents.

In the Security tab, set the following settings:

Under Java/COM Restrictions, set Run restricted Java/Javascript/COM and Run unrestricted Java/Javascript/COM to *.

Under Security Settings, set:

Compare Notes Public keys against those stored in Directory to No.

Allow anonymous Notes connections to No.

Check Passwords on Notes IDs to Disabled.

Under Server Access, set Only allow server access to users listed in this Directory to No.

Under Web Server Access, set Web Server Authentication to More Name Variations with lower security.

In the Ports tab:

Select the Notes Network Ports tab and ensure that TCPIP is ENABLED.

Select Internet Ports tab and the Web tab.

Ensure that TCP/IP port status is Enabled.

Under Authentication options, ensure that Name and password and Anonymous are Yes.

Select the Directory tab and ensure that:

TCP/IP port status is Enabled.

Authentication options items Name and Password and Anonymous are Yes.

SSL port status is Disabled.

Select the Mail tab and ensure that:

TCP/IP port status is Enabled.

Authentication options Name and Password and Anonymous are set as follows:


	Mail (IMAP)	Mail (POP)	Mail (SMTP Inbound)	SMTP (Outbound)
Name and Password	Yes	Yes	No	N/A
Anonymous	N/A	N/A	Yes	N/A

Select the IIOP tab and ensure that:

TCP/IP port status is Enabled.

Authentication options items Name and Password and Anonymous are Yes.

TCP/IP port number is not set to 0. It should be 63148.

SSL port status is Disabled.

Select the Internet Protocols tab and the IIOP sub-tabs. Ensure that the Number of threads is at least 10.

Save and close.

Restart the server by typing the following in the Domino server console:

restart server

Restarting the server enables the settings to take effect.

Enable DIIOP server by typing the following command in the console:

load diiop

Check to see if diiop_ior.txt has been generated at location:

C:\Lotus\Domino\Data\domino\html\diiop_ior.txt

Enable HTTP service by typing the following command in the console:

load http

If there is another service using port 80, the HTTP service will not start. Stop the service running on port 80 and retype the following in the console: load http

Use the existing service. To do this, copy the diiop_ior.txt file into the root or home directory of the web server running on port 80. You can include both the HTTP service and the DIIOP service in the notes.ini file to ensure that both services start when you start the server.

Configuration for Lotus Notes

To access a Lotus Notes system using the Sun Java System Portal Server Mail and Calendar channels, you need to add another file to the Sun Java System Portal Server. This file is called NCSO.jar. It must be obtained from the Lotus Notes product CD or the IBM web site.

It is available with the Domino Designer and Domino Server products from IBM in the domino\java subdirectory. It is also available in a Web download from the following Web site:

Go to the Lotus Domino Toolkit link and then to the Java/Corba R5.0.8 update link.


Note	The download file is a .exe file, which performs the extraction of this file and other files.

Place the NCSO.jar file in the global class path of the web container (web server or application server) as described in the subsequent sections about each of the four possible web containers. For three of the four web containers, the NCSO.jar file is placed in /usr/share/lib. The following table summarizes the steps that follow. The table outlines the process of placing the JAR file in the global class path by indicating where the NCSO.jar file can be placed: in the System Classpath or in the Portal WAR. The table also indicates if special instructions are needed. If so, they are included later in this section.

Web Container	System Classpath	Portal WAR	Special Instructions
Sun Java System Web Server	Yes	Yes	N/A
Sun Java System Application Server	Yes	Yes	N/A
BEA WebLogic Server	Yes	No	How to update system classpath
IBM WebSphere Application Server	No	Yes	How to prune JAR file

For the following steps, you need administrative rights to the web container. Also, you should have access to the web container documentation in order to reference detailed information on various web container processes and commands. For more information concerning the Sun Java System web containers, see Sun Java System Application Server Administrator’s Guide or Sun Java System Web Server, Enterprise Edition Administrator’s Guide.

Sun Java System Web Server

Place the NCSO.jar in the following Sun Java System Portal Server directory:

/usr/share/lib

Update the web container class path to include:

/usr/share/lib/NCSO.jar

Launch the Sun Java System Web Server admin console.

Select the Sun Java System Web Server instance.

Click Manage.

Select the Java tab.

Select the JVM Path Settings.

Add /usr/share/lib/NCSO.jar to the classpath suffix.

Select ok

Select Apply

Restart the Sun Java System Web Server; though often not mandatory, this is a good practice.

Optional Placement of the NCSO.jar File

Place the NCSO.jar file in the following directory:

PortalServer-base/SUNWps/web-src/WEB-INF/lib

Redeploy the web application with the following command:

PortalServer-base/SUNWps/bin/deploy redeploy

Restart the web container.

Sun Java System Application Server

Place the NCSO.jar in the following Sun Java System Portal Server directory:

/usr/share/lib

Update the web container class path to include /usr/share/lib/NCSO.jar using the Sun Java System Application Server admin console.

Launch the Sun Java System Application Server admin console.

Select the domain.

Select the server instance.

Select the JVM Settings tab in the server instance view.

Select Path Settings under the JVM Settings tab.

Add /usr/share/lib/NCSO.jar in the Classpath Suffix list.

Select Save.

Select Apply Changes under the General tab of the instance.

Select Restart.

Optional Placement of the NCSO.jar File

Place the NCSO.jar file in the following directory:

PortalServer-base/SUNWps/web-src/WEB-INF/lib

Redeploy the web application with the following command:

PortalServer-base/SUNWps/bin/deploy redeploy

Where PortalServer-base represents the directory in which the Portal Server was originally installed.

Restart the web container.

BEA WebLogic Server

Place the NCSO.jar in the following Sun Java System Portal Server directory:

/usr/share/lib

Update the web container class path to include /usr/share/lib/NCSO.jar using the command line.

Change directories to the web container install directory:

WebContainer-base/bea/wlserver6.1/config

Where WebContainer-base represents the directory in which the web container was originally installed.

Change directories to the directory that contains the domain instance:

mydomain

Edit the startWebLogic.sh file using the editor of your choice.

Add /usr/share/lib/NCSO.jar to the end of the CLASSPATH.



Note	The startWebLogic.sh file may contain multiple CLASSPATH definitions. Locate the last definition of the variable and add the following string to the very end of the CLASSPATH: /usr/share/lib/NCSO.jar

Restart the web container.

IBM WebSphere Application Server

Prune the classes under org/w3c/dom/ and org/xml/sax/ from the NCSO.jar file and rejar.

The classes should include the following:

org/w3c/dom/Document.class

org/w3c/dom/Node.class

org/xml/sax/InputSource.class

org/xml/sax/SAXException.class

There are many ways to perform this task. Two examples are provided for you here. Follow the method that suits you best:

The following method requires you to manually unjar and rejar the file:

Download and place the file in the following directory:

/tmp/ncsoprune/work

Unjar the file while it is in that directory.

Remove the preceding four classes.

Rejar the file.

The following method requires you to run a script that automates the jar and unjar logic.

Download and place the file in the following directory:

/tmp/ncsoprune/work

Run the following script:

#!/bin/ksh
JAR=/usr/j2se/bin/jar
JAR_FILE=NCSO.jar
RM=/usr/bin/rm
BASE_DIR=/tmp/ncsoprune
WORK_DIR=${BASE_DIR}/work
# cd to director of jar file
cd $WORK_DIR
# unjar
$JAR xvf $JAR_FILE
# prune classes
$RM $WORK_DIR/org/w3c/dom/Document.class
$RM $WORK_DIR/org/w3c/dom/Node.class
$RM $WORK_DIR/org/xml/sax/InputSource.class
$RM $WORK_DIR/org/xml/sax/SAXException.class
# jar
$JAR cvf $BASE_DIR/$JAR_FILE META-INF com lotus org

Place the re-jarred NCSO.jar file in the following directory:

PortalServer-base/SUNWps/web-src/WEB-INF/lib

Redeploy the web application with the following command:

PortalServer-base/SUNWps/bin/deploy redeploy

Where PortalServer-base represents the directory in which the Portal Server was originally installed.

Restart the web container.

Creating a New User Under the Default Organization

From an Internet browser, log on to the Sun Java System Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Identity Management tab to display the View drop down list in the navigation pane.

Select Users in the View drop down list to display the User page.

Click New to display the New User page in the data pane.

Select the services to be assigned to the user.

Select at a minimum Portal Desktop and SSO Adapter.

Enter the user information.

Click Create.

The new user’s name appears in the Users list in the navigation pane.

Configuring the Mail Provider to Work with an HTTPS Enabled Messaging Server

The Mail channel automatically supports the HTTP protocol; it does not automatically support the more secure HTTPS protocol. However, if your Sun Java System Messaging Server is enabled for HTTPS, you can follow the steps in this section to configure the Mail provider to work properly with the Sun Java System Messaging Server. These steps do not apply to Microsoft Exchange Server and IBM Lotus Notes server.

Web Container Facts and Considerations

In terms of configuring the mail provider for HTTPS for Sun Java System Messaging Server, the steps regarding the web container differ depending upon which web container you are using: Sun Java System Web Server, Sun Java System Application Server, BEA WebLogic Server, or IBM WebSphere Application Server. You need administrative rights to the web container regardless of which one you use. Also, you should have access to the web container documentation in order to reference detailed information on initializing a trust database, adding certificates, and restarting the web container. For more information on these tasks and other security-related issues concerning the Sun Java System web containers, see Sun Java System Application Server Administrator’s Guide to Security or Sun Java System Web Server, Enterprise Edition Administrator’s Guide.

To Configure the Mail Provider to Work with an HTTPS Enabled Messaging Server

Initialize the trust database for the web container running Sun Java System Portal Server. For more information, refer to the proper documentation as discussed in the preceding paragraph.

Install the SSL certificate for the Trusted Certificate Authority (TCA) if it is not already installed.

Restart the web container; though often not mandatory, this is a good practice.

Add a new SSO Adapter template specifically for HTTPS. The name of the template used in this example is SUN-ONE-MAIL-SSL, which is descriptive since the security protocol, SSL, is included in the name



Note	You can configure an SSO Adapter template and related SSO Adapter configurations in many ways. The steps presented to you subsequently explain a typical configuration. These steps describe how to create a new template and a new configuration since this is a safer practice than simply editing existing templates and configurations. If you feel comfortable with the editing option, then proceed in that manner. However, if you change the name of the SSO Adapter template and SSO Adapter configuration as part of the edits you make, you will also need to change the SSO Adapter name by editing the properties of the Mail channel. The two items you would need to edit in the SSO Adapter template or SSO Adapter configuration are: clientProtocol clientPort In creating a new SSO Adapter Template for this example, the clientProtocol attribute is set as a default attribute. Therefore, it appears in an SSO Adapter template not in an SSO Adapter configuration. The clientProtocol attribute must be changed from http to https. The edited template fragment for this attribute appears as follows: clientProtocol=https For this example, the clientPort attribute is set as a merge attribute. Therefore, it appears in an SSO Adapter configuration (see Step 5). If the clientPort attribute were set as a default attribute, it would appear in an SSO Adapter template. The client port should be changed to a port reserved exclusively for HTTPS. Here port 443 is used since the HTTPS protocol uses this port number as the default. The edited template fragment for this attribute appears as follows: &clientPort=443

From an Internet browser, log into the Sun Java System Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Service Configuration tab to display the list of configurable services in the navigation pane.

Click the arrow next to SSO Adapter to bring up the SSO Adapter page in the data pane.

Type a template name and select an existing template from the menu.

Click Next.

The Template Properties page appears.

Modify the properties as needed.

Code Example 17-4 is a typical configuration which has been provided for your reference. The template you enter will probably have different information. For example, you will probably enter a different value for the configName property type unless you want to use the name SUN-ONE-MAIL-SSL. Furthermore, the attributes you set as default and merge will probably differ from this example, depending upon the needs of your site.

When done, click Save.

Code Example 17-4 Mail SSO Adapter Template for an HTTPS Messaging Server


default\|imap:///?configName=SUN-ONE-MAIL-SSL
&encoded=password
&default=protocol
&default=clientProtocol
&default=type
&default=subType
&default=enableProxyAuth
&default=proxyAdminUid
&default=proxyAdminPassword
&default=ssoClassName
&merge=host
&merge=port
&merge=uid
&merge=password
&merge=smtpServer
&merge=clientPort
&clientProtocol=https
&enableProxyAuth=false
&proxyAdminUid=[PROXY-ADMIN-UID]
&proxyAdminPassword=[PROXY-ADMIN_PASSWORD]
&type=MAIL-TYPE
&subType=sun-one
&ssoClassName=com.sun.ssoadapter.impl.JavaMailSSOAdapter
&default=enablePerRequestConnection
&enablePerRequestConnection=false

At this point, there may be more than one string that begins with the IMAP protocol. This is acceptable.

Add a new SSO Adapter configuration specifically for HTTPS. The name of the configuration used in this example is sunOneMailSSl because it is similar to the name used for the respective SSO Adapter template.



Note	See the Note from the preceding step, Step 4.

From an Internet browser, log on to the Sun Java System Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Identity Management tab to display the View drop down list in the navigation pane.

Click Services in the View drop down list.

Scroll down the navigation pane to the Single Sign-on Adapter configuration heading and click the arrow next to SSO Adapter to bring up the SSO Adapter page in the data pane.

Click in the blank configuration description field—which is just above the Add and Remove buttons.

Click New under SSO Adapter Configuration to add an SSO adapter configuration.

The New Configuration page appears.

Type a configuration name and select an SSO Adapter template from the menu.

Click Next.

The Configuration Properties page appears.

Modify the properties as needed.

When done, click Save.

Add a new Mail channel to Portal Desktop.

Step 4 and Step 5 explained how to create a new SSO Adapter template and SSO Adapter configuration; those are the steps for creating a new channel. In this step you will make the channel available to end users.

The criteria for choosing a name for the new channel is simply one that is descriptive; therefore the example name chosen here is SunOneMailSSLChannel.

From an Internet browser, log on to the Sun Java System Access Manager admin console at http://hostname:port/amconsole, for example http://psserver.company22.example.com:80/amconsole

Click the Identity Management tab to display the View drop down list in the navigation pane.

Select Services in the View drop down list to display the list of configurable services.

Under the Portal Server Configuration heading, click the arrow next to Portal Desktop to bring up the Portal Desktop page in the data pane

Scroll as needed and click the Manage Channels and Containers link.

Scroll down to the Channels heading and click New.

In the Channel Name field, type your site’s name for the new channel. For example, SunJavaMailSSLChannel.

In the Provider drop down menu, select MailProvider.

Click OK, which returns you to the Channel and Container Management Web page where the channel you just created now exists.

Scroll down to the Channels heading and click Edit Properties next to the name of the channel you just created, which for this example is SunOneMailSSLChannel.

Scroll down to the title field, select and delete any words that currently exist, for example mail, and type a provider title. A possible name is SSL Mail Account.

In the description field, select and delete any words that currently exist, for example mail, and type a provider description. The same example is used here for description as for the title in the preceding substep: SSL Mail Account.

Scroll down the page; select and delete any words that currently exist in the SSO Adapter field, for example sunOneMail; and type the same SSO Adapter configuration name used in Step 5, which for this example is sunOneMailSSL.

Scroll down and click Save.

Scroll back up the page to click the word top, which is the first item following the words Container Path.

Scroll down to the Container Channels heading and click the link for the container that you want to add the new channel to. For example, MyFrontPageTabPanelContainer. Do not click the accompanying Edit Properties link.

Scroll down to the Channel Management heading, scroll as needed in the Ready For Use frame, and click the name of your newly created channel to select it.

Remember, for this example the channel name is SunOneMailSSLChannel.

Add the channel to the Available to End Users on the Content Page list or to the Visible on the Portal Desktop list.

Click the Add button above the list for which you want to add the channel.

Scroll back up the page and click Save under the Channel Management heading.

You should now be able to log in and use an HTTPS enabled messaging server.

Previous Contents Index Next
Sun Java System Portal Server 6 2005Q1 Administration Guide