28 Managing Microsoft Office Integration

This chapter provides an overview of system administrator tasks required to configure Microsoft Office integration with the Spaces application in 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 chapter on "Working with Microsoft Office and Explorer Integration" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

This chapter includes the following sections:

Audience

The content of this chapter is intended for Fusion Middleware administrators (users granted the Admin or Operator role through the Oracle WebLogic Server Administration Console). For more information, see Section 1.8, "Understanding Administrative Operations, Roles, and Tools."

28.1 About Microsoft Office Integration

Figure 28-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 28.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 chapter on "Working with Microsoft Office and Explorer Integration" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces for the activities that are supported for each Windows version.

Figure 28-1 Microsoft Office Integration Topology

Description of Figure 28-1 follows
Description of "Figure 28-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 32.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 32.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 registry to allow Microsoft Office to authenticate over HTTP. For more information, see Section 28.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 28.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 28.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 28.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 28.4.2, "Problem with Editing Document with Word from Document Library."

28.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:

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 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 Spaces, so it is important to avoid logging into multiple Spaces 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 Spaces from the same Windows user account without unintended consequences. See the troubleshooting note in Section 28.4.2, "Problem with Editing Document with Word from Document Library" for more information.

  1. Add a <location /> in the Oracle HTTP Server (OHS) by doing one of the following:

    • Adding the following to the OHS ssl.conf (or mod_wl_ohs.conf if you are configuring OHS to front-end WebCenter Portal in a non-SSL environment (not recommended)) file located in OHS_INSTANCE_HOME/config/OHS/ohs1/:

      # Spaces Application
<location />
  SetHandler weblogic-handler
  WebLogicHost webcenter.example.com
  WebLogicPort 8888
</location>

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

    • Or creating a virtual host in OHS for access with Word, and route both "/" and "/wcsdocs" to the WC_Spaces server in this virtual host (required when OAM single sign-on is used) as shown in the example below:

      # Virtual Hosts - Sharepoint
  <VirtualHost *:4444>
     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>

      For more information, see Section 32.6, "Configuring SSO with Virtual Hosts".

  2. Add the required parameters to the setDomainEnv.sh file, making sure to set the non_sso_host to the alias as shown in the example below. You'll find the setDomainEnv.sh file at the following location:

    • Unix: DOMAIN_HOME/bin/setDomainEnv.sh

    • Windows: DOMAIN_HOME\bin\setDomainEnv.cmd

    EXTRA_JAVA_PROPERTIES=
"${EXTRA_JAVA_PROPERTIES}
-Dnon_sso_protocol=https
-Dnon_sso_host=<hostname_of_OHS_frontend>.oracle.com
-Dnon_sso_port=4444
-Dsso_base_url=http://<hostname_of_OHS_frontend>.oracle.com:4443"
export EXTRA_JAVA_PROPERTIES

    Where:

    • non_sso_protocol is the protocol of the URL used to access the WC_Spaces from Microsoft Word.

    • non_sso_host is the host that points to the WC_Spaces server and is not protected by OAM SSO.

    • non_sso_port is the host port that points to the WC_Spaces server and is not protected by OAM SSO.

    • sso_base_url is the URL to access SSO (often the same as the one used by Spaces)

    For more information, see Section 32.5.3, "Configuring Microsoft Clients."

    Note:

    If the protocol used externally to access Microsoft Office is SSL and the certificate is invalid, add the following parameters in setDomainEnv.sh:

    JAVA_OPTIONS="${JAVA_OPTIONS}
-Dweblogic.security.SSL.enforceConstraints=off
-Dweblogic.security.SSL.ignoreHostnameVerification=true"

    Note that the ignoreHostnameVerfication=true setting is only needed if the site is using wildcard certificates. Hostname verification must be disabled in this case because the wildcard certification does not match the specific server name.

28.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

28.4 Troubleshooting Microsoft Office Integration

This section includes the following sub-sections:

28.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.

28.4.2 Problem with Editing Document with Word from Document Library

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 Spaces 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.

28.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 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.

28.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 deselect 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.

28.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 28-2):

Figure 28-2 Plug-in Icon

Description of Figure 28-2 follows
Description of "Figure 28-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.