11 Securing Your Integrated Excel Workbook

This chapter describes security related features in ADF Desktop Integration.

This chapter includes the following sections:

• Section 11.1, "Introduction to Security In Your Integrated Excel Workbook"

• Section 11.2, "Authenticating the Excel Workbook User"

• Section 11.3, "Checking the Integrity of an Integrated Excel Workbook's Metadata"

• Section 11.4, "What You May Need to Know About Securing an Integrated Excel Workbook"

11.1 Introduction to Security In Your Integrated Excel Workbook

If you are using a Fusion web application that does not enforce authentication, the integrated Excel workbook verifies and creates a valid user session when it connects to the Fusion web application before downloading any data. The session that is established is used for each and every data transfer between the integrated Excel workbook and Fusion web application. The session is also used for web pages displayed from the integrated Excel workbook.

In a Fusion web application that is enforcing authentication, the integrated Excel workbook ensures that a valid, authenticated user session is established before transferring data to or from the web application.

For both authenticated and non-authenticated Fusion web applications, ADF Desktop Integration relies on the establishment of cookie-based sessions. With no authentication mechanism in place, your Fusion web application is not completely safe. Hence, you should enable ADF Security in your Fusion web application before you deploy your web application with integrated Excel workbooks. For information about ADF Security, see the "Enabling ADF Security in a Fusion Web Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

When you open the integrated Excel workbook, ADF Desktop Integration detects if the Fusion web application that the workbook runs against is a secure application and enforces authentication automatically. For authenticated web applications, the end user will always be prompted for credentials, even though the workbooks are downloaded from an authenticated web browser. Since the web browser and Excel are different operating system processes, they cannot share credentials (unless Windows native authentication is used).

When the integrated Excel workbook of a secure Fusion web application opens, a Login dialog appears and prompts you to connect to the Fusion web application, as shown in Figure 11-1. Note that the Login dialog also appears when the Fusion web application is not secure.

Figure 11-1 Dialog to verify Connection

If you click Yes to connect, another dialog prompts you to enter the credentials, as shown by the example in Figure 11-2.

Figure 11-2 Dialog to verify End User's Credentials

The dialog that is shown in Figure 11-2 might be different as it depends on how the Fusion web application is configured to enforce authentication. For example, if Form-based authentication is being used by the web application, then the end-user will see a browser dialog with a web page with fields for user name and password.

11.2 Authenticating the Excel Workbook User

The integration of an Excel workbook with a secure Fusion web application requires an authenticated web session established between the integrated Excel workbook and the server that hosts the Fusion web application. ADF Security determines the mechanism used to authenticate the user.

If the end user opens an Excel workbook without a valid authenticated session, a login mechanism is invoked to authenticate the end user.

11.2.1 What Happens at Runtime: How the Login Method Is Invoked

After the login method is invoked, a new session between the integrated Excel workbook and the Fusion web application is created, and a modal dialog 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 shown in Figure 11-3.

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

The end user enters user credentials and, assuming these are valid, an authenticated session is created and assigned to the client (the web browser control hosted by the Excel workbook).

Note:

If the Login method is invoked when a session has already been established, it first invokes the Logout action internally to free that session.

11.2.2 What Happens at Runtime: How the Logout Method Is Invoked

After the logout method is invoked, a dialog appears informing users that they have logged out of the current session. The user is automatically logged out when the workbook is closed, or when the Clear All Data option is selected from the runtime custom tab in Excel ribbon.

Figure 11-4 Dialog 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) and running against the same Fusion web application, 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 running against the same Fusion web application are closed.

11.3 Checking the Integrity of an Integrated Excel Workbook's Metadata

ADF Desktop Integration provides a mechanism to verify 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. It generates a hash code value and inserts the value into the ADF Desktop Integration client registry file (adfdi-client-registry.xml) that it also creates when you publish the integrated Excel workbook as described in Section 14.3, "Publishing Your Integrated Excel Workbook." ADF Desktop Integration stores the adfdi-client-registry.xml file in the WEB-INF directory of the Fusion web application.

If you republish the integrated Excel workbook, ADF Desktop Integration generates a new hash code value and replaces the value in the adfdi-client-registry.xml file. ADF Desktop Integration creates the adfdi-client-registry.xml file if it does not exist.

The ApplicationHomeFolder and WebPagesFolder workbook properties allow the integrated Excel workbook to identify the location of the Fusion web application's WEB-INF directory. You must set valid values for these properties before you can publish the integrated Excel workbook and ADF Desktop Integration can generate a hash code value.

ADF Desktop Integration generates the hash code value using most of the elements in the metadata for the workbook and the value of the WorkbookID workbook property. The WorkbookID workbook property is read-only and uniquely identifies the integrated Excel workbook. You must reset the WorkbookID workbook property if you create a new integrated Excel workbook by copying an existing integrated Excel workbook. ADF Desktop Integration excludes the WebAppRoot property from the hash code calculation since its value is expected to change at runtime.

For more information about the workbook properties discussed here, see Table A-18.

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. Open the integrated Excel workbook.

2. In the Workbook group of the Oracle ADF tab, click Workbook Properties.

3. In the Edit Workbook Properties dialog, click the Reset WorkbookID link.

4. Click Yes to confirm and reset the WorkbookID workbook property in the dialog that appears., as shown in Figure 11-5.

   Figure 11-5 Reset Workbook ID Dialog

   
   

5. Click OK.

11.3.2 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 cannot 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.

11.4 What You May Need to Know About Securing an Integrated Excel Workbook

Note the following points about securing an integrated Excel workbook with a Fusion web application:

• Data security

  If you save an Excel workbook containing data downloaded from a Fusion web application to a location, such as a network directory, where other users can access the Excel workbook, the data stored in the Excel workbook is accessible to other users.

• Security in Microsoft Excel

  You can enhance the security of an integrated Excel workbook using Excel's functionality to set a password on a workbook. It prevents unauthorized users from opening or modifying the workbook. For more information about Excel security features, see Excel's documentation.

• Integrated Excel workbooks can be configured to cache data, as described in Section 15.2, "Restore Server Data Context Between Sessions." Make sure that you do not cache sensitive data in the integrated Excel workbook.

• If the Fusion web application is running on the https protocol, you may receive a certificate error while connecting from an integrated Excel workbook. You can either install the required certificate using Microsoft Internet Explorer, or choose to continue to log in and connect to the web application.

• End users that download integrated Excel workbooks using Microsoft Internet Explorer may be prompted unexpectedly for credentials before the Excel application is visible, and then prompted again once the workbook opens. This may occur when the web application is configured to use certain authentication methods like Basic or Digest. The extra prompt is due to Internet Explorer making an OPTIONS request on the web directory containing the workbook.

  To avoid the extra login prompt, end users can choose to save the workbook locally instead of opening it directly from the browser.

If you are an administrator, you should also see the "What You May Need to Know About Configuring Security in a Fusion Web Application" section in Oracle Fusion Middleware Administrator's Guide for Oracle Application Development Framework.