Oracle® Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework 11g Release 1 (11.1.1) E10139-03 |
|
![]() Previous |
![]() Next |
This chapter provides information about how to secure your integrated Excel workbook with a Fusion web application by providing authentication and authorization capabilities in an authenticated session. The chapter describes how to access integrated Excel workbooks in an authenticated and non authenticated session. It also describes issues that you should be aware of so that you can secure your Excel workbook.
It is recommended that you configure ADF Security for the Fusion web application before you deploy the integrated Excel workbook; however, it is not required. 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.
This chapter includes the following sections:
Section 11.1, "Introduction to Security In Your Integrated Excel Workbook"
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"
If you are using a Fusion web application that does not enforce authentication, then the integrated Excel workbook verifies and creates a valid user session before connecting to the Fusion web application and downloading 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 referenced 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 integrated Excel workbooks are not completely safe. Hence, it is recommended that you enable ADF Security in your Fusion web application before you deploy your web application with integrated Excel workbooks.
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.
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-1.
The end user enters user credentials and, assuming these are valid, an authentication session is created and assigned to the client (the web browser control hosted by the Excel workbook).
Note: If theLogin method is invoked when a session has already been established, it first invokes the Logout action internally to free that session. |
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.
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.
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.
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:
Open the integrated Excel workbook.
Click Workbook Properties in the Oracle ADF tab.
In the Edit workbook Properties dialog, click the Reset WorkbookID link.
Click Yes to confirm and reset the WorkbookID
workbook property in the dialog that appears.
Click OK.
By default, ADF Desktop Integration verifies 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:
Stop your Fusion web application.
Open the web.xml
file of your Fusion web application.
Add an initialization parameter to the adfdiRemote
servlet to disable the metadata tamper-check, as described in Table 11-1.
Table 11-1 Disabling Metadata Tamper-Check
Property | Value |
---|---|
|
Enter the name of the initialization parameter as follows:
|
|
Set the value of |
Figure 11-3 shows the web.xml
editor in JDeveloper.
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>
Rebuild and restart your Fusion web application.
For more information about the web.xml
file, see Appendix E, "ADF Desktop Integration Settings in the Web Application Deployment Descriptor."
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:
Stop your Fusion web application.
Open the web.xml
file of your Fusion web application.
Add an initialization parameter to the adfdiRemote
servlet to allow missing entries in the metadata as described in Table 11-2.
Table 11-2 Allowing Missing Entries in the Metadata
Property | Value |
---|---|
|
Enter the name of the initialization parameter as follows:
|
|
Set the value of |
Figure 11-4 shows the web.xml
editor in JDeveloper.
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>
Rebuild and restart your Fusion web application.
For more information about the web.xml
file, see Appendix E, "ADF Desktop Integration Settings in the Web Application Deployment Descriptor."
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.
Note the following points about securing an integrated Excel workbook with a Fusion web application:
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 and protection in Microsoft Excel
Certain security and protection features that Microsoft Excel provides do not work for workbooks or worksheets that are integrated with a Fusion web application. For example, you cannot use the worksheet protection feature for a worksheet that you integrate with a Fusion web application. You can, however, use Excel's functionality to set a password on an integrated Excel workbook to prevent unauthorized users from opening or modifying it. 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 and you have not installed the security certificate on the client, the integrated Excel workbook gives an error on login and the connection is not established. To establish a connection, you must install the security certificate.
For applications running in an environment using Oracle Access Manager, the system administrator should ensure that the URL for the ADF Desktop Integration Remote servlet is configured as a protected resource for Oracle Access Manager. For more information, see the Oracle Access Manager Access System Administration Guide.
For applications running in an environment using WebGate, set the user-defined parameter filterOAMAuthnCookie
to False
. For more information, see the chapter on registering partners (agents and applications) remotely in the Oracle Access Manager Access System Administration Guide.
System administrators should ensure 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 a 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>