OracleAS Portal Integration Solutions
Oracle Application Server Provider for Microsoft Exchange 2003 - Installation instructions

Contents

Introduction
Requirements
Deploying the Oracle Application Server Provider Microsoft Exchange 2003

Installing the ASP files on Internet Information Server (IIS)
Create a new virtual directory on the IIS default web site
Configure your new virtual directory to use basic authentication
Give users the right to log on locally to the IIS server
Test basic authentication for your new virtual directory
Configure the location of files with the .mmp extension
Test the ASP page access to the sample Exchange 2003 mailbox

Passing on the session context from Portal to Microsoft Exchange Server 2003
Routing through Login Server
Using Microsoft ISAPI Filter

Updating provider.xml

Publishing the Oracle Application Server Provider for Microsoft Exchange 2003

Creating the External Application
Registering the Oracle Application Server Provider for Microsoft Exchange 2003
Adding the Microsoft Exchange 2003 Portlets to a Page

Customizing the Portlet to View Your Mailbox

Introduction

• Exchange 2003 Inbox Portlet

• Exchange 2003 Calendar Portlet

• Exchange 2003 Contacts Portlet

Requirements

• Microsoft Exchange Server 2003
• Microsoft Outlook Web Access (installs with Microsoft Exchange 2003)
• Microsoft Internet Information Server 5.0 or later (IIS)
• PDK-Java runtime and samples v9.0.4 or above
• OracleAS Portal 9.0.2 or above

Deploying the Oracle Application Server Provider for Microsoft Exchange 2003

Installing the ASP Files on Internet Information Server (IIS)

The Oracle Application Server Provider for Microsoft Exchange 2003 come with a set of Active Server Pages (ASP) files, which need to be installed. This stage of the installation assumes that you have successfully installed Microsoft Exchange Server 2003 and Microsoft IIS 5.0 (IIS 5.0 comes as part of Windows 2000 Advanced Server). Also, it is assumed that IIS and Exchange 2003 exist in the same Windows domain.

1. Create a new virtual directory on the IIS default web site
   1. Go to the machine that has Microsoft IIS 5.0. You should have a Default Web Site Content Directory on this computer, e.g.,C:\Inetpub. Create a new directory here, e.g. C:\Inetpub\exchange

The remainder of the instructions contained in this document will refer to this directory as $exchange_dir.

2. Copy the htdocs folder located at:

$IAS_HOME(MID_TIER)/j2ee/$OC4J_INSTANCE/applications/exchange/exchange
into the $exchange_dir directory created in the step a. above on the IIS server machine.

3. From the desktop, click Start
4. Point to Programs, then Administrative Tools, and then click Internet Services Manager.
5. In the left pane of the Internet Information Services screen, you will see the name of your computer. Click on it and expand it.
6. Right-click the Default Web Site, point to New, and then click Virtual Directory. You will be shown a Wizard for creating a Virtual Directory.
   • § Click on the Next for the first Welcome.... screen.
   • Virtual Directory Alias: Enter the alias for this new virtual directory, say exchange

The remainder of the instructions contained in this document will refer to this directory to as your_virtual_directory.

• Click on Next.
• Web Site Content Directory: Click on Browse to select the $exchange_dir\htdocs directory in the Directory field.
  
• Click on Next.
• Access Permissions: Accept the default values in this screen and click on Next.
• Click Finish.
6. Now, you need to create a sub-directory called resources in your_virtual_directory created in the step f. For creating this, please follow these steps:
   • In the left pane of the Internet Information Services screen, right-click on your_virtual_directory.
     
   • Go to context menu’s New option, and then click Virtual Directory.
     
   • You will be shown a Wizard for creating a Virtual Directory.
   • Click on the Next button for the first Welcome.... screen.
   • Virtual Directory Alias: Enter the alias for this new virtual directory, say resources

NOTE: The name of this Virtual directory MUST necessarily be resources.

• Click on Next.
•  Web Site Content Directory: Click on Browse to select the $exchange_dir\htdocs\resources directory in the Directory field.
  
• Click on Next.
•  Access Permissions: Accept the default values in this screen and click on Next.
• Click Finish. 

2. Configure your new virtual directory to use basic authentication
   1.  The Internet Services Manager window should still be open. In the left pane, expand the Default Web Site.
   2. Right-click the your_virtual_directory created in the step 1a, and select Properties.
   3. Select the Directory Security tab.
   4. Click Edit in the Anonymous access and authentication control section.
   5. Select the checkbox for Basic authentication and unselect all other checkboxes. 
   6. When you select basic authentication, a dialog will pop up warning you that passwords will be transmitted unencrypted. Click Yes to continue.
   7. Click Edit next to Select a default domain. 

The domain you should select here is the domain for which your Exchange Server 2003 is the primary domain controller. If this is the domain that Microsoft IIS is on, you can click Use Default.

3. Give users the right to log on locally to the IIS server

In order for users to access your_virtual_directory using basic authentication, they must be given the Log On Locally right for the machine that has IIS.The easiest way to do this is as follows:

1. Go to the machine that has Microsoft IIS. Click Start, point to Programs, then Administrative Tools, and then click Local Security Policy.
2. In the left pane, expand Local Policies.
   
3. Under the expanded node, click User Rights Assignment.
4. In the right pane, double click Log on locally.
   
5. Look to see if the group Users is in the list of assigned users/groups.
6. Make sure the Local Policy Setting is checked for Users. 

Also make sure the group corresponds to the domain for your Exchange Server 2003 (you do not need to worry about this if you only have one domain). If the “Users” group is not in the list, click Add… and add the “Users” group from your Exchange Server 2003’s domain.

4. You will need to assign user rights at the domain controller level.
   
1. Click Start, point to Programs, then Administrative Tools, and then click Domain Controller Security Policy. 
2. Expand Security Settings, then expand Local Policies
   
3. Click User Rights Assignment. In the right pane, double click Log on locally and make sure the Users group has been added to the list. 
5. You must restart the machine for user rights assignment changes to take effect.

4. Test basic authentication for your new virtual directory
    
   1. Open a browser and go to: http://your_IIS_hostname:port/your_virtual_directory/hello.html
   2. A basic authentication dialog should prompt you to authenticate. Enter the credentials for a valid user account.
   3. Do not proceed with the installation if you cannot see the Hello World page. If this happens, review the previous steps and double check that everything has been configured correctly.

5. Configure the location of files with the .mmp extension

The ASP pages you added to the IIS virtual directory in Step 2 use a set of Microsoft APIs called Collaboration Data Objects (CDO). When CDO is used in an ASP page to logon to an Exchange 2003 mailbox, a temporary .mmp file is created and stored in the directory where Windows is installed. Since most users would not have permissions to that directory, they would not be able to log on to Microsoft Exchange 2003 via the ASP pages. This previously caused a [Collaboration Data Objects - [MAPI_E_NOT_FOUND(8004010F)]]error to appear when invoking the Portlet ASP pages.

To avoid this error, configure the Windows Messaging Subsystem to store the temporary .mmp file in a different directory and do following registry configuation:

1. Start Registry Editor (regedt32.exe) on the machine that has IIS.
2. Go to the following key: HKEY_LOCAL_MACHINE/Software/Microsoft/Windows Messaging Subsystem.
3. On the Edit Menu, click Add Value.
4. Enter the following:
   1. Value Name: ProfileDirectory
   2. Data Type: REG_SZ
   3. String: The path to the directory you want the .mmp files to be created in. For example, C:\temp. Make sure everyone has “full control” permissions for this directory.
       

    6. Test the ASP page access to the sample Exchange 2003 mailbox

1. Open a browser and go to:

http://your_IIS_hostname:port/your_virtual_directory/test.asp?mailbox=mailbox_alias_for_sample_account&server=your_exchange_server

For example, suppose IIS is on a machine called “server-iis”, Exchange 2003  is on “server-ex”, and you created a user called “john.doe” (mailbox alias “john.doe”). Then URL would be:

http://server-iis/your_virtual_directory/test.asp?mailbox=john.doe&server=server-ex

When prompted by the authentication dialog, enter the credentials for the "john.doe" user account. You should see the word VALID appear.

2. You can run this same test by invoking inbox.asp instead of test.asp. You should then see the sample user's inbox.
3. Do not proceed with the installation if you cannot successfully view test.asp and inbox.asp. If this happens, review the previous steps and double check that everything has been configured correctly.

Passing-on the Session context from Portal to Microsoft Exchange Server 2003

In order to pass-on the Session context from Portal to Microsoft Exchange Server 2003, we have 2 options available :

1. Routing through Login Server
   
2. Using Microsoft ISAPI Filter
   

Routing through Login Server

Using Microsoft ISAPI Filter

1. ISAPI filter can be downloaded from Microsoft Download Center with location as http://support.microsoft.com/default.aspx?scid=kb;EN-US;837104
2. Browse to above Microsoft site and download samples.exe package.
3. Extract samples.exe in a temporary directory say your_ temporary_directory.
4. Locate filter DLL file i.e. 837104_IsapiFilter.dll under your_ temporary_directory\ISAPI folder.
5. Copy the filter 837104_IsapiFilter.dll from your_ temporary_directory\ISAPIto subfolder underDefault Web Site Content Directoryc:\Inetpub\scripts.
6. Click Start, point to Programs, then Administrative Tools, and then click Internet Services Manager.
7. In the left pane of the Internet Information Services screen, you will see the name of your computer. Click on it and expand it.
8. Navigate to ‘Scripts’ under 'Default Web Site'.
9. Select 837104_IsapiFilter.dll and then right click to select Properties.
10. Select the File Securitytab.
11. Click Edit in the Anonymous access and authentication control section.
12. Select the checkbox for Anonymous authentication and unselect all other checkboxes.

Configure the ISAPI filter

1. Click Start, point to Programs, then Administrative Tools, and then click Internet Services Manager.
2. In the left pane of the Internet Information Services screen, you will see the name of your computer. Click on it and expand it.
3. Select the Default Web Site and then right click to select Properties.
4. Select the ISAPI FILTERS tab.
5. Click Add and then browse to \Inetpub\scripts\ to select the ISAPI filter that you copied.
6. Restart the IIS server.

Updating provider.xml

At this point, you should have successfully installed and tested your Microsoft Exchange 2003 ASP pages. The rest of this installation involves installing and registering the provider for the Exchange 2003 Portlets.

• Open the given provider.xml file for the Exchange 2003 Portlets.  Look for tag called <pageUrl> tags and change each of these tag values to point to the URLs of the corresponding Inbox/Contacts/Calendar asp page on your IIS server. For the Inbox Portlet, the <pageUrl> tag should look like this:

<pageUrl>http://your_IIS_hostname:port/your_virtual_directory/inbox.asp</pageUrl>

• If you installed the ASP files on a separate machine from Microsoft Outlook Web Access (OWA), you must specify the URL used to access OWA. OWA is the web client for Microsoft Exchange 2003. All Portlet links for creating a new message, reading a message, etc. open OWA to display the inbox, contacts and calendar in detail. To specify a URL for OWA, add the URL as a parameter called "owapath" to the pageUrl (do this only if you installed the ASP files on a separate machine from OWA).  For example:

<pageUrl>http://your_IIS_hostname:port/your_virtual_directory/inbox.asp?owapath=http://your_OWA_hostname:port/exchange</pageUrl>

• If there is a proxy server between your OracleAS HTTP Server and your Microsoft IIS Server, you will need to add the following proxy tags just below the provider tag :
  

<provider class="oracle.portal.provider.v2.DefaultProviderDefinition">
....

....

• If you are making use of the ISAPI filter, then change all the occurance of <useISAPIFilter> tag in the entire provider.xml to have true value. This indicates the provider that each portlet needs to run under the filter mechanism.
  

• Else if you are making use of Routing through Login Server then all the occurances <useISAPIFilter> tag in the entire provider.xml to have false value

• Save and close the provider.xml file.
  

• You should now be able to test your Exchange 2003 provider by going to the URL:

http://your_oc4j_hostname:port/exchange/providers/exchange

Publishing the Oracle Application Server Provider for Microsoft Exchange 2003

Creating the External Application

• Log on to OracleAS Portal as an OracleAS Portal Administrator.  Go to the Administer tab of the OracleAS Portal Builder.  In the SSO Server Administration Portlet, click Administer External Applications.
• Click on Add External Application.  In the External Application Login, Authentication Method and Additional Fields sections, enter the following:
  • Application Name: Exchange Basic Authentication
  • Login URL: http://your_IIS_hostname:port/your_virtual_directory/hello.html
  • User Name/ID Field Name: <leave blank>
  • Password Field Name: <leave blank>
  • Type of Authentication Used: Select BASIC AUTHENTICATION
  • Enter the mailbox alias for the user account and the Exchange Server 2003 name as additional fields given below:

• Click OK. 
  
• Click on the link for your new Exchange 2003 External application and enter valid user account credentials. 
  
• Check box for "Remember My Login Information... " must be selected.

Registering the Oracle Application Server Provider for Microsoft Exchange 2003

After deploying the OracleAS Provider for Microsoft Exchange 2003 Provider, you must register the provider with OracleAS Portal in order to add Microsoft Exchange 2003 Portlets to a page.

1. Login to OracleAS Portal using an account that has build privileges. If your home page is not the Build/Administer page, click on the Builder link in the top right corner of the screen. Click on the Build tab if that is not the active tab.
2. Under the Build tab (on OracleAS Portal Home Page), click on Register Portlet Provider within the portlet called Providers.
3. Fill out provider information for the Microsoft Exchange 2003Provider.
   • Name: Exchange
   • Display Name: Exchange Provider
   • Timeout: 100
   • Timeout Message: Exchange Provider Timed Out
   • Implementation Style: Web
4. Click on the Next button to enter the Web Provider specific information
5. Enter the Web Provider location

URL: http://your_oc4j_hostname:port/exchange/providers/exchange

6. Select the radio button labeled The user's identity needs to be mapped to a different name.... 
7. In the External Application ID field, select the ID corresponding to the Exchange Basic Authentication application you created in the previous step.
8. Under User/Session Information section, specify the login frequency. Login Frequency: Once Per User Session.
9. Click on the Finish button to complete the registration

Note: When registering a new provider with Oracle Portal, only the user who registered the provider has privileges to see the provider/portlets. If necessary, go to the Folder with the name of the provider within the Portlet Repository content area and update the provider privileges as required.

Adding the Microsoft Exchange 2003 Portlets to a Page

When you add the portlet to a page, you will view Exchange 2003 mailbox content in the portlet for mailbox alias and Exchange Server 2003 name you specified while creating the external application.

Customizing the Portlet to View Your Mailbox

Click the portlet's Customize link. You may customize portlet settings at this screen i.e. number of rows per page, filters, etc. Click OK to see the portlet.

To switch to another Exchange 2003 mailbox, you will have to change the Mailbox/Server values and the credentials entered for the Exchange  2003 Basic Auth external application or create a new External Application. You can do this via External Applications portlet.

Oracle and the Oracle logo are trademarks or registered trademarks of Oracle Corporation in the United States and other countries.

All other names are trademarks and/or registered trademarks of their respective owners.