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:
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."
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
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."
SSL enabled entry point
SSL must be configured for either the load balancer or OHS, whichever is the edge server of the topology.
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."
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").
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."
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."
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 "Installing and Configuring Oracle Web Tier" in the 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). Note that SSL is required for Microsoft Office integration. For more information, see "Securing the Browser Connection to Spaces with SSL" in the Oracle Fusion Middleware Administrator's Guide for 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 "Securing the Browser Connection to Spaces with SSL" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.
When Spaces is configured with OAM, added the following resource URLs with their Protection Level set to Excluded
:
/wcsdocs* /wcsdocs/.../* /_vti_*
Use the OAM Console to configure the resource URLs as described in "Adding and Managing Resource Definitions for Use in Policies" in the Oracle Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service.
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.
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".
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.
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
This section includes the following sub-sections:
Section 28.4.1, "Clicking Edit with Office Does Not Invoke Word"
Section 28.4.2, "Problem with Editing Document with Word from Document Library"
Section 28.4.3, "Using SSL - Document Cannot be Checked Out"
Section 28.4.4, "Microsoft Office Task Pane Only Shows a Single Tab"
Edit with Microsoft Office feature does not start Word or associated Office application when used with a browser other than Internet Explorer.
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.
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.
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.
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.
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:
Import the Trusted Certificate from the OHS or load balancer to the the WC_Spaces
server.
Export the Trusted Certificate from the OHS Wallet following the steps below:
Log into the Fusion Middleware Control instance that manages OHS.
Select Web Tier > ohs1.
From the OHS drop-down list, select Security > Wallets.
Click default.
Select CN="\"Self-Signed Certificate for ohs1 \"", OU=OAS, O=ORACLE, L=REDWOODSHORES, ST=CA, C=US
Click Export.
Save the file (for example, as "ohsTrustedCertificate").
Copy the file to the local disk of the WC_Spaces
server.
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:
Logging into the WLS Console.
Selecting Environment > Servers > WC_Spaces.
Opening the Configuration tab and then selecting Keystores.
After clicking Edit with Office on a document in Internet Explorer Microsoft Office launches with only one tab on the Task Pane.
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.
Unable to connect to Microsoft Office applications from WebCenter Portal when using Firefox.
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):
at the top left of the browser adjacent to the URL bar, and explicitly enable Java for the site you want.