1. Provide your end users with a URL in the following format that they can open in a web browser:

   http://<hostname>:<portnumber>/<context-root>/adfdiRemoteServlet?excel-addin-installer

   For example:

   http://127.0.0.1:7101/summit/adfdiRemoteServlet?excel-addin-installer

2. Depending upon the browser, the end user will be prompted to download, or download and run, the adfdi-excel-addin-installer.exe installer file.

An end user can upgrade ADF Desktop Integration in two ways.

• Run the ADF Desktop Integration installer to upgrade.

  For information about downloading the installer, see How to Install the ADF Desktop Integration Add-in From a Web Server.

• Open and run the integrated Excel workbook.

  Each time the end user logs into the Fusion web application from an integrated Excel workbook, ADF Desktop Integration checks whether a new version of the add-in is available on the server. If a new version is available, the end user will be prompted to download the latest version of ADF Desktop Integration. If the end user accepts the prompt to install the latest version, the end user must also restart the Excel application after the installation completes for the change to take effect. For information, see Verifying the Client Version of ADF Desktop Integration.

If end users are not prompted for user credentials while using integrated Excel workbooks and interacting with a secure Fusion web application, you need to investigate the security configuration of the Fusion web application. For information, see Verifying End-User Authentication for Integrated Excel Workbooks.

End users who have difficulty connecting to a Fusion web application may see the Connection Failure dialog shown in Figure C-3. Ask these users to save the connection failure report by clicking the Save Report button in the dialog. The report contains diagnostic information that may help resolve the connection failure. As an administrator, you may want to review the connection failure report for clues to solving the problem. See the documents that you can retrieve from My Oracle Support (https://support.oracle.com) if you search for Doc IDs 2014348.1 and 2094772.1.

For more information about ADF Desktop Integration security, see the "Oracle ADF Desktop Integration Security whitepaper" on OTN at:

http://www.oracle.com/technetwork/developer-tools/adf/overview/index-085534.html

Note the following points before you secure your application:

• In order for the end-user login sequence to complete successfully, the authentication provider must redirect the browser back to the originally requested ADF Desktop Integration servlet URL after a successful login.

• For applications running in an environment using Oracle Access Manager, the system administrator should make sure that the URL for the ADF Desktop Integration Remote servlet is configured as a protected resource for Oracle Access Manager.

  For information, see Introducing Oracle Access Management in Oracle Fusion Middleware Administrator's Guide for Oracle Access Management.

• Make sure that applications using ADF Desktop Integration have a security constraint configured in web.xml that protects the ADF Desktop Integration remote servlet.

  The following code extract from web.xml shows an example security constraint protecting the remote servlet:

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>adfdiRemote</web-resource-name>
      <url-pattern>/adfdiRemoteServlet</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>valid-users</role-name>
    </auth-constraint>
  </security-constraint>
  

• When using Oracle WebGate and a SSL URL to access the Fusion web application (such as https:// ...) it may be necessary to configure WebGate's mod_wl_ohs.conf configuration file as follows:

  <IfModule mod_weblogic.c>
    	WLProxySSLPassThrough ON
    	WLProxySSL ON
    	MatchExpression /TestApp 
    	WebLogicHost=test.host.com|WebLogicPort=7101|
  </IfModule>
  

  where /TestApp is the context root of your application, test.host.com is the host name and domain, and 7101 is the port number for the web application.

• When opening an integrated Excel workbook, or any Microsoft Office document, directly (without downloading the file) from a link in the Fusion web application, the Windows Login dialog may appear twice asking for user credentials. This happens because Microsoft Office sends its own authentication request to the web server, making the Login dialog appear twice. End users may click Cancel and ignore the first authentication request.

• Applications secured via a digital certificate where clients use https URLs to access the application should make sure that the certificate is valid. Valid certificates have host names that match the host to which they are deployed, have not expired, and have a valid path to a trusted issuing authority. In the case where the certificate is invalid, the client will be prompted during login to accept the invalid certificate.

• ADF uses chunked encoding for some requests to the server. If you have any network devices between Excel and the web application server configured to block requests that do not contain a content length header, you should configure them to allow chunked encoding (no content length header). Some network devices such as content caching servers may have a default configuration that blocks requests with no content length header. For information, see the “ADFDI-07528 WebException During TamperCheck” document that you can retrieve from My Oracle Support (https://support.oracle.com) if you search for Doc ID 2013517.1.

• Before you secure your application, note that the HTTPS communication that the ADF Desktop Integration add-in initiates during the login sequence requires a successful SSL/TLS protocol handshake. This handshake can fail if the server and ADF Desktop Integration add-in cannot agree on a protocol to use. For example, if the client computer supports SSL 3.0 and TLS 1.0, but the server only supports TSL 1.1 and TLS 1.2. The ADF Desktop Integration add-in makes HTTPS connections using portions of the Microsoft Internet Explorer technology stack as well as the Microsoft .NET Framework. For best results, ensure that:

  • Client computers have Microsoft .NET Framework 4.5.2 (or higher) installed

  • Microsoft Internet Explorer is configured on the client computer to support TLS 1.1 and TLS 1.2. For information, see the "ADFDI-00500: unable to execute Wininet method HttpSendRequest; error code: 12029" During Login" document that you can retrieve from My Oracle Support (https://support.oracle.com) if you search for Doc ID 2025331.1.

  • Ensure that the Oracle Weblogic Server that hosts the web application is configured to support TLS 1.1 and TLS 1.2. For information, see "Specifying the SSL Protocol Version" in the Oracle WebLogic Server security guide for the release of Oracle WebLogic Server that you use.

    The ADF Desktop Integration add-in may initiate HTTPS communication by offering the TLS 1.2 protocol for the SSL/TLS protocol handshake. While ADF Desktop Integration does not require TLS 1.2, servers (such as Oracle WebLogic Server, Oracle HTTP Server, and Oracle Application Server WebCache) must successfully negotiate a mutually agreed-upon protocol when offered the TLS 1.2 protocol. Some older versions of servers are known to reject TLS 1.2 offers rather than negotiate to use a lower version (for example, TLS 1.0). Such server versions are not supported. If older versions of server are in use, please make sure that the most recent Critical Patch Updates are applied. See also the "WebException: The request was aborted: Could not create SSL/TLS secure channel - during or right after ADFdi login sequence" document that you can retrieve from My Oracle Support (https://support.oracle.com) if you search for Doc ID 2087746.1.

For information about securing integrated Excel workbooks, see What You May Need to Know About Securing an Integrated Excel Workbook.

In an integrated Excel workbook, each worksheet is bound to a specific page definition. Users' access to pages may be controlled by resource grants. If an end user is not authorized to work with a page definition, ADF Desktop Integration disallows all data transactions in worksheets bound to that page definition, displays a failure message, and disables those integrated worksheets. The end user can alter any existing data in the worksheet, but cannot download or upload it. The tracking of changes in ADF Table components is also disabled. The end user can continue to use ADF Desktop Integration features in other worksheets in the same workbook, provided those worksheets are bound to page definitions that the end user is authorized to work with.

The worksheet is re-enabled when the end user reopens the workbook and establishes a new session, provided that the end user has obtained the necessary resource grants for the corresponding page definition.

For information about securing your Fusion web application, see Enabling ADF Security in a Fusion Web Application in Developing Fusion Web Applications with Oracle Application Development Framework.

1. Open the web.xml file of your Fusion web application.
2. Add an initialization parameter to the adfdiRemote servlet to disable the option to install from the Client-Server Version Check dialog, as described in Table 17-3.

   Table 17-3 Disabling the install option on the Client-Server Version Check dialog

   Property	Value
   Name	Enter the name of the initialization parameter as follows: ClientUpgradePrompt.Enabled Note that the name is case-sensitive.
   Value	Set the value of ClientUpgradePrompt.Enabled to False. Note that any value other than False will be interpreted as True.

3. Save the web.xml file.

   The web.xml file of your Fusion web application will now have the ClientUpgradePrompt.Enabled entry:

   <servlet>
       <servlet-name>adfdiRemote</servlet-name>
       <servlet-class>oracle.adf.desktopintegration.servlet.DIRemoteServlet</servlet-class>
       <init-param>
         <param-name>ClientUpgradePrompt.Enabled</param-name>
         <param-value>False</param-value>
       </init-param>
     </servlet>
   

4. Restart your Fusion web application.

1. Open the web.xml file of your Fusion web application.
2. Add an initialization parameter to the adfdiRemote servlet to disable the metadata tamper-check, as described in Table 17-4.

   Table 17-4 Disabling Metadata Tamper-Check

   Property	Value
   Name	Enter the name of the initialization parameter as follows: TamperingCheck.Enabled Note that the name is case-sensitive.
   Value	Set the value of TamperingCheck.Enabled to False. Note that any value other than False will be interpreted as True.

   Figure 17-6 shows the web.xml editor in JDeveloper.

   Figure 17-6 Disabling the Metadata Tamper Check In JDeveloper

   
   Description of "Figure 17-6 Disabling the Metadata Tamper Check In JDeveloper"
3. Save the web.xml file.

   The web.xml file of your Fusion web application will now have the TamperingCheck.Enabled entry:

   <servlet>
           <servlet-name>adfdiRemote</servlet-name>
           <servlet-class>...</servlet-class>
           <init-param>
               <param-name>TamperingCheck.Enabled</param-name>
               <param-value>False</param-value>
           </init-param>
   </servlet>
   

4. Restart your Fusion web application.