26 Managing Microsoft Office Integration

This chapter provides an overview of system administrator tasks required to configure Microsoft Office integration with Oracle WebCenter Portal 11g (11.1.1.1.0) and later. For a description of how Microsoft Office can be used with Webcenter Portal, see the "Working with Microsoft Office and Explorer Integration" chapter in Oracle Fusion Middleware Using Oracle WebCenter Portal.

This chapter includes the following topics:

• Section 26.1, "About Microsoft Office Integration"

• Section 26.2, "Configuring Microsoft Office Integration"

• Section 26.3, "Configuring Non-SSL Integrations"

• Section 26.4, "Troubleshooting"

Permissions:

To perform the tasks in this chapter, you must be granted the following roles:

• WebLogic Server: Admin role granted through the Oracle WebLogic Server Administration Console.

• WebCenter Portal: Administrator role granted through Portal Builder Administration.

See also, Section 1.8, "Understanding Administrative Operations, Roles, and Tools."

26.1 About Microsoft Office Integration

Figure 26-1 shows a typical Microsoft Office integration topology with notes describing configuration concerns specific to each component in the topology. For an end-to-end description of how to configure Microsoft Office integration, see Section 26.2, "Configuring Microsoft Office Integration."

After configuring Microsoft Office integration you can interact with Microsoft Office and Microsoft Office Enterprise Edition applications from within your WebCenter Portal environment. Refer to the matrix in the "Working with Microsoft Office and Explorer Integration" chapter in Oracle Fusion Middleware Using Oracle WebCenter Portal for the activities that are supported for each Windows version.

Figure 26-1 Microsoft Office Integration Topology

Description of "Figure 26-1 Microsoft Office Integration Topology"

1. Oracle HTTP Server and load balancer

   OHS (or the load balancer) must be properly configured so that requests are routed to the Sharepoint servlet. If single sign-on is being used, you must create a virtual host that is not protected by SSO as described in Section 33.6, "Configuring SSO with Virtual Hosts." This should be done on the edge server of the topology (i.e., either the load balancer or OHS). Note that the -Dnon_sso* java parameters must be set to point to the non-SSO protected virtual host as described in Section 33.6.5, "Configuring WebCenter Portal for Virtual Hosts."

2. SSL enabled entry point

   SSL must be configured for either the load balancer or OHS, whichever is the edge server of the topology.

3. Microsoft Office client

   Although not using SSL imposes a security risk (in that user credentials are passed without encryption) and is strongly discouraged, you can configure each client machine's registry to allow Microsoft Office to authenticate over HTTP. For more information, see Section 26.3, "Configuring Non-SSL Integrations."

4. WC_Spaces managed server

   Document the applicable JVM arguments, and review specifically which ones are needed and under what conditions. For more information, refer to step 2 in Section 26.2, "Configuring Microsoft Office Integration."

   Note that if SSL is enabled on the edge server (either OHS or a load balancer), the Trusted Certificate of the SSL certificate of the edge server must be imported into the WC_Spaces server's keystore (see Section 26.4.3, "Using SSL - Document Cannot be Checked Out").

5. Internet Explorer or supported browser

   For Internet Explorer, ActiveX must be enabled. For browsers other than Internet Explorer, such as Firefox and Google Chrome, the Java plug-in must be installed. For more information, see Section 26.4.1, "Clicking Edit with Office Does Not Invoke Word."

6. Windows/WebCenter Portal user accounts

   There must be a 1:1 relationship between Windows user accounts and WebCenter Portal login accounts. Due to the way in which integration with Microsoft Office works, WebCenter Portal user accounts must be uniquely associated with Windows user accounts. For Windows 7 in particular, the Windows 7 WebClient caches user credentials in the Windows 7 user context and consequently cannot support more than one WebCenter Portal user per Windows 7 user. For more information, see Section 26.4.2, "Problem Editing Documents from Document Library in Windows 7."

26.2 Configuring Microsoft Office Integration

This section describes how to configure Microsoft Office clients for desktop integration. Prior to following these configuration steps you should already have:

• Installed the Web Tier (Oracle HTTP Server) in front of Oracle WebCenter. For more information about installing the Oracle HTTP Server, see the "Installing and Configuring Oracle Web Tier" section in Oracle Fusion Middleware Installation Guide for Oracle Web Tier.

• Configured and enabled SSL on the Oracle HTTP Server (or the Load Balancing Router, if one is being used). SSL setup is mandatory if you are using Microsoft Office 2010 for desktop integration. SSL setup is recommend but not mandatory if using Microsoft Office 2007. For more information, see the "Securing the Browser Connection to WebCenter Portal with SSL" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

• Imported the public certificate of the SSL certificate being used to the WebLogic Trust Store if the certificate is not one of the well known certificate authorities that is already seeded in cacerts or the WebLogic default Trust Store. For more information, see the "Securing the Browser Connection to Spaces with SSL" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

• When WebCenter Portal is configured with OAM, the OAM administrator should have added the following resource URLs with their Protection Level set to Excluded:

  /wcsdocs*
  /wcsdocs/.../*
  /_vti_*
  

  For more information about setting resource URLs, see the "Adding and Managing Resource Definitions for Use in Policies" section in Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.

  The OAM protection invoked within the OHS configuration must be specifically applied to the main connection port and not to the secondary unprotected SharePoint port we are configuring in the steps below (4444 in the example). You must remove the Oblix values from webgate.conf (or httpd.conf in some cases) and replace them within the valid Virtual Host container for the main WebCenter connection (port 80 or 7777). Then, creating the new virtual hosts in steps 1 and 2 below will create a port (4444 in the example) that the SharePoint protocols can use to communicate without OAM SSO. For more information, see Section 33.6.4, "Configuring Virtual Hosts for OAM 11g."

Note:

WebCenter Portal integration with Microsoft Office follows the model established by Microsoft for Microsoft desktop applications interacting with a SharePoint server. For WebCenter Portal integration, the WC_Spaces server emulates the SharePoint server's role in that model.

On the client side, the logged in Windows user may be associated with the user account used to log into WebCenter Portal, so it is important to avoid logging into multiple WebCenter Portal accounts with the same Windows user account. In particular, the Windows 7 WebClient service caches credentials used to log in to the emulated SharePoint service endpoints, so it is not possible to support various login accounts to WebCenter Portal from the same Windows user account without unintended consequences. See the troubleshooting note in Section 26.4.2, "Problem Editing Documents from Document Library in Windows 7" for more information.

To configure WebCenter Portal for desktop integration:

1. Ensure that the following mappings exist in the webtier mod_wl_ohs.conf file, which is located under the OHS_HOME/Oracle_WT1/instances/instance1/config/OHS/ohs1 directory:

   <Location /wcsdocs>
            SetHandler weblogic-handler
            WeblogicHost webcenter.example.com
            WeblogicPort 8888
   </Location>
   
   <Location /_vti_bin>
            SetHandler weblogic-handler
            WeblogicHost webcenter.example.com
            WeblogicPort 8888
   </Location>
   

   Where, webcenter.example.com refers to the host on which WebCenter Portal is installed.

   For an example the OHS mod_wl_ohs.conf file, see Appendix B, "Oracle HTTP Server Configuration for WebCenter Portal."

2. If your environment is a cluster, it is recommended that you use the virtual host setup to route to the SharePoint root application.

   Note:

   When you have a single node setup, there is no need for a virtual host even if SSO is configured.

   In a cluster environment, ensure the following entries are present in the httpd.conf file, which is located under the OHS_HOME/Oracle_WT1/instances/instance1/config/OHS/ohs1/ directory:

   NameVirtualHost *:7777
    
   <VirtualHost *:7777>
     ServerName webtier.example.com
   </VirtualHost>
    
   <VirtualHost *:7777>
     ServerName webtier-spaces.example.com
     <Location  />
         SetHandler weblogic-handler
         WebLogicHost webcenter.example.com
         WebLogicPort 8888
     </Location>
     <Location /webcenter>
         Deny from all
     </Location>
     <Location /webcenterhelp>
         Deny from all
     </Location>
     <Location /rest>
         Deny from all
     </Location>
   </VirtualHost>
   

   Where:

   • webtier.example.com refers to the OHS host.

   • webtier-spaces.example.com refers to the virtual host. Ensure that you update the DNS with entries for webtier-spaces.example.com.

   • webcenter.example.com refers to the host that has the WC_Spaces managed server installed.

   If your environment has SSO set up, configure virtual hosts such that they can bypass SSO. For more information, see Section 33.6, "Configuring SSO with Virtual Hosts."

3. Add the following required parameters to domain_home/bin/setDomainEnv.sh (on UNIX) or domain_home\bin\setDomainEnv.cmd (on Windows):

   EXTRA_JAVA_PROPERTIES=
   "${EXTRA_JAVA_PROPERTIES} -Dnon_sso_protocol=http
   -Dnon_sso_host=webcenter.example.com -Dnon_sso_port=8888
   -Dsso_base_url=http://webtier.example.com:7777"
   export EXTRA_JAVA_PROPERTIES
   

   Where:

   • non_sso_protocol is the protocol of the URL used to access the WC_Spaces managed server from Microsoft Office applications.

   • non_sso_host is the host that points to the WC_Spaces managed server (that is webcenter.example.com) or the virtual host (that is webtier-spaces.example.com), if it is set up.

   • non_sso_port is the host port that points to the WC_Spaces managed server port 8888, or to the virtual host port 7777, if it is set up.

   • sso_base_url is the URL to access SSO or OHS, which is often the same as the one used by WebCenter Portal.

26.3 Configuring Non-SSL Integrations

For installations that for one reason or another do not configure SSL on the OHS or Load Balancer, you must configure client registry information for each client to override the restrictions built in to the Microsoft Office products. Refer to the following Microsoft support site and follow the instructions below. Note that the instructions may differ slightly between Windows versions:

http://support.microsoft.com/kb/2123563

26.4 Troubleshooting

This section includes the following sub-sections:

• Section 26.4.1, "Clicking Edit with Office Does Not Invoke Word"

• Section 26.4.2, "Problem Editing Documents from Document Library in Windows 7"

• Section 26.4.3, "Using SSL - Document Cannot be Checked Out"

• Section 26.4.4, "Microsoft Office Task Pane Only Shows a Single Tab"

• Section 26.4.5, "Unable to Connect to Microsoft Office Using Firefox"

26.4.1 Clicking Edit with Office Does Not Invoke Word

Problem

Edit with Microsoft Office feature does not start Word or associated Office application when used with a browser other than Internet Explorer.

Solution

The Java plug-in is required for Microsoft Office integration to work with non-IE browsers. Check that you have the Java plug-in enabled in your browser. Refer to your browser's documentation for instructions for installing the Java plug-in.

26.4.2 Problem Editing Documents from Document Library in Windows 7

Problem

The first user logging into Windows 7 is able to use the Microsoft Office integration feature without any issues. However, subsequent users logging into WebCenter Portal on the same desktop in the same Windows 7 login may experience issues, especially when checking in and checking out documents. These issues may persist even though all browsers and Microsoft Office have been shut down.

The problem is due to the WebClient service, a Windows native service that allows the operating system to make HTTP and WebDAV requests, which caches the first credential. The WebClient service is intended to be used by other Windows features (for example, when a user adds a network location) and it makes sense that it caches the credential rather than asking for it every time it's accessed. However, the credential is cached in the context of the Windows 7 logged in user; it is not tied to the Spaces login.

Consequently, the WebClient service sends a request to the WebCenter Portal Document Service using the first user's credentials. For the second user, this will cause an issue because the WebCenter security model may prevent the first user credential from accessing the document (if it doesn't have the necessary rights) on the folder being accessed by the second user. Even if it succeeds, it will appear as if the first user did the check out.

Solution

To fix the problem you can:

• Reboot the machine before a second user starts using the feature.

• Log out of Windows and log in using a different Windows 7 user.

• Restart the WebClient service:

The problem with these fixes is that they require system administrator privileges, and as the WebClient service is used by other Windows 7 features, stopping it may affect them. The easiest way to avoid this problem is to not share the same desktop and Windows 7 login across multiple WebCenter Portal or Fusion Applications user accounts.

26.4.3 Using SSL - Document Cannot be Checked Out

Problem

After clicking Edit with Office a dialog appears indicating that the document could not be checked out. After several login challenges, Microsoft Office opens but the document is in Read-only mode and is not checked out.

Solution

This problem relates specifically to the following environment:

• The browser is Internet Explorer

• OHS or a load balancer is set up in front of the WC_Spaces server

• SSL is enabled on OHS and terminates at OHS (i.e., the connection from OHS to the WC_Spaces server is non-SSL)

This symptom occurs because there is a second HTTPS request from the backend (WC_Spaces server) to the OHS (or load balancer), which throws a SSL Key exception because the WC_Spaces server is not trusted. This is the request that is responsible for doing the document check-out.

To resolve this issue:

1. Import the Trusted Certificate from the OHS or load balancer to the WC_Spaces server.

2. Export the Trusted Certificate from the OHS Wallet following the steps below:

   1. Log into the Fusion Middleware Control instance that manages OHS.

   2. Select Web Tier > ohs1.

   3. From the OHS drop-down list, select Security > Wallets.

   4. Click default.

   5. Select CN="\"Self-Signed Certificate for ohs1 \"", OU=OAS, O=ORACLE, L=REDWOODSHORES, ST=CA, C=US

   6. Click Export.

   7. Save the file (for example, as "ohsTrustedCertificate").

   8. Copy the file to the local disk of the WC_Spaces server.

3. Import the OHS Trusted Certificate to the WLS DemoTrust.jks using the following keytool command:

   JAVA_HOME/bin/keytool -importcert -v -alias ohscert -file /mycert/ohsTrustedCertificate -keystore /my_mw_home/wlserver_10.3/server/lib/DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase
   

   where DemoTrustKeyStorePassPhrase is the default password for the DemoTrust.jks.

   The path for the keystore can be found by:

   1. Logging into the WLS Console.

   2. Selecting Environment > Servers > WC_Spaces.

   3. Opening the Configuration tab and then selecting Keystores.

26.4.4 Microsoft Office Task Pane Only Shows a Single Tab

Problem

After clicking Edit with Office on a document in Internet Explorer Microsoft Office launches with only one tab on the Task Pane.

Solution

This problem occurs because the Use my local drafts folder option was selected in Internet Explorer when the document was opened, resulting in the file being copied to the user's local folder rather than connected to the server. If the file is not subsequently checked in, the same symptom will occur for other users trying to edit the document with other browsers such as Firefox or Chrome. To avoid this problem, be sure all users uncheck the Use my local drafts folder option in Internet Explorer when prompted. For all other browsers, be sure that users use Options > Save with each of the MS Office applications.

26.4.5 Unable to Connect to Microsoft Office Using Firefox

Problem

Unable to connect to Microsoft Office applications from WebCenter Portal when using Firefox.

Solution

Due to security issues with Java 7, Firefox is now blocking the Java Platform Plug-In even when it appears to be enabled in the plug-ins list, which will effectively disable Microsoft Office integration.

In order to use Java and Microsoft Office integration in Firefox, you must now additionally click the plug-in icon (see Figure 26-2):

Figure 26-2 Plug-in Icon

Description of "Figure 26-2 Plug-in Icon"

at the top left of the browser adjacent to the URL bar, and explicitly enable Java for the site you want.