11 Securing Your Integrated Excel Workbook

11.2.1 How a Fusion Web Application Determines If an Excel Workbook Has a Web Session ID

The server that hosts the Fusion web application determines whether the client has an authenticated cookie-based web session ID by locating and validating the web session ID in the request header from the client. If the client already has a valid cookie-based web session ID, all subsequent requests sent to the server hosting the Fusion web application include the web session ID attached to the request header. If the cookie-based web session ID is expired, the server responds with the login mechanism specified by the Fusion web application. If the client does not have a cookie-based web session ID, the client sends a request to the server for the page referenced by the ProtectedWebPage workbook property. The server responds with the login mechanism. In both instances (cookie-based web session ID expired and no cookie-based web session ID), the login mechanism to authenticate the user appears in the browser control hosted by the Excel workbook.

The value of ProtectedWebPage is a URL that references a protected web page. You specify a value for ProtectedWebPage when you want to run the integrated Excel workbook in test mode. For information about how to specify a value for ProtectedWebPage, see Section 4.4.2, "How to Open an Excel Workbook for the First Time".

11.2.2 What Happens at Runtime When the Login Mechanism Is Invoked

After the login mechanism is invoked, a modal dialog box appears that contains a web browser control. This web browser control displays whatever login mechanism the Fusion web application uses. For example, if the Fusion web application uses HTTP Basic Authentication, the web browser control displays the simple dialog box shown in Figure 11-1.

Figure 11-1 Dialog Box That Appears When a Fusion Web Application Uses Basic Authentication

The user enters user credentials and, assuming these are valid, a cookie-based web session ID is created and assigned to the client (the web browser control hosted by the Excel workbook).

11.2.3 What Happens at Runtime When the Logout Mechanism Is Invoked

After the logout mechanism is invoked, a dialog box appears informing that user has been logged out of the current session. The user is automatically logged out when the worksheet or workbook is closed, or Clear All Data option is selected from the menu.

Figure 11-2 Dialog Box That Appears When a User Logs Out

After logging out, the user must log in again to upload or download data.

If two or more workbooks are open (in Test or Runtime mode) with same credentials, closing one workbook does not initiate the logout mechanism. The user continues to stay logged in and may continue to work on remaining open workbooks, and can open the closed workbook without being asked for credentials again. The user is logged out when all workbooks, requiring same credentials, are closed.

11.3.1 How to Reset the Workbook ID

The value of the WorkbookID workbook property is unique to each workbook and cannot be modified by you. You can, however, reset the WorkbookID workbook property. You must do this when you create a new integrated Excel workbook by copying an existing integrated Excel workbook.

To reset a workbook ID:

1. Click Tools > Reset WorkbookID in the Oracle ADF Desktop Integration Designer toolbar.

2. Click Yes to confirm that you want to reset the WorkbookID workbook property in the dialog box that appears.

3. Click OK.

11.3.2 How to Disable the Metadata Tamper-Check in the Fusion Web Application

By default, the Oracle ADF Desktop Integration module checks that the metadata it uses to integrate an Excel workbook with a Fusion web application is not tampered with after you publish the Excel workbook for end users. You can disable the metadata tamper-check by configuring a parameter in the deployment descriptor file (web.xml) of the Fusion web application, although this is not recommended.

To disable the metadata tamper-check in the Fusion web application:

1. Stop your Fusion web application.

2. Open the web.xml file of your Fusion web application.

3. Add an initialization parameter to the adfdiRemote servlet to disable the metadata tamper-check, as described in the following table.

   Property	Value
   Name	Enter the name of the initialization parameter as follows: TamperingCheck.Enabled
   Value	Set the value of TamperingCheck.Enabled to False.

   
   

4. Save the web.xml file.

   The web.xml file of your Fusion web application has the following entries:

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

5. Rebuild and restart your Fusion web application.

For more information about the web.xml file, see Appendix E, "Desktop Integration Settings in the Web Application Deployment Descriptor".

11.3.3 How to Allow Missing Entries in the Oracle ADF Desktop Integration Client Registry

You can configure the metadata tamper-check so that a missing entry for the WorkbookID workbook property is allowed in the adfdi-client-registry.xml file. To do this, you configure a parameter in the deployment descriptor file (web.xml) of the Fusion web application, although this is not recommended.

To allow missing entries in the metadata of the Fusion web application:

1. Stop your Fusion web application.

2. Open the web.xml file of your Fusion web application.

3. Add an initialization parameter to the adfdiRemote servlet to allow missing entries in the metadata as described in the following table.

   Property	Value
   Name	Enter the name of the initialization parameter as follows: TamperingCheck.AllowMissingEntries
   Value	Set the value of TamperingCheck.AllowMissingEntries to True.

   
   

4. Save the web.xml file.

   The web.xml file of your Fusion web application has the following entries:

   <servlet>
           <servlet-name>adfdiRemote</servlet-name>
           <servlet-class>...</servlet-class>
           <init-param>
               <param-name>TamperingCheck.AllowMissingEntries</param-name>
               <param-value>True</param-value>
           </init-param>
   </servlet>
   

5. Rebuild and restart your Fusion web application.

For more information about the web.xml file, see Appendix E, "Desktop Integration Settings in the Web Application Deployment Descriptor".

11.3.4 What Happens When the Metadata Tamper-Check is Performed

At runtime, the integrated Excel workbook regenerates the metadata hash code and provides it to the Fusion web application with the first server request. If the Fusion web application is unable to get a match on this hash code, it returns an error to the integrated Excel workbook. On receiving an error from the tamper check process, the integrated Excel workbook reports this failure to the end user and closes the integration framework.