Security in ADF Desktop Integration

23 Security in ADF Desktop Integration

If your Fusion web application enforces authentication, the integrated Excel workbooks help the business user authenticate properly before data transfer happens between the workbooks and application.

For information, see About Security In Your Integrated Excel Workbook.

Business User Authentication

If business 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 User Authentication for Integrated Excel Workbooks.

Business users who have difficulty connecting to a Fusion web application may see the Connection Failure dialog shown in Figure A-10. 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.

For troubleshooting information, visit My Oracle Support (https://support.oracle.com) and search for Doc IDs 2014348.1 and 2971113.1. For more information about ADF Desktop Integration security, search for 2240073.1 (Security in ADF Desktop Integration).

What You May Need to Know About Configuring Security in a Fusion Web Application

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.example.com|WebLogicPort=7101|
</IfModule>
```
where /TestApp is the context root of your application, test.example.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. Business 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 (411) Length Required 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 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 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 the Microsoft .NET Framework. For best results, ensure that:
- Client computers have Microsoft .NET Framework 4.5.2 (or higher) installed
- 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 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.

What You May Need to Know About Resource Grants for Web Pages

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 a business 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 business 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 business 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 business user is authorized to work with.

The worksheet is re-enabled when the business user reopens the workbook and establishes a new session, provided that the business 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.

The Digital Certificate

The artifacts that make up ADF Desktop Integration are signed with a digital certificate. The digital signature proves the authenticity of these artifacts and verifies the identity of the publisher, Oracle. Digital signatures are created using certificates issued from trusted certificate authorities.

Certificates are used to sign artifacts during the product build process. All "sign-able" artifacts are signed starting with the installer (MSI) file and including all the DLLs that make up the add-in.

Note:

This topic provides the procedures in Microsoft Windows File Explorer to view and install the certificate, as well as copy the certificate's public key. Be aware that the steps may be different for different editions and versions of Windows. Check the documentation for your version of Windows for more information.

View the Certificate

You can inspect these certificates before and after installation to verify the authenticity of the add-in's artifacts.

To view the certificate:

Navigate to the installer file (adfdi-excel-addin-installer-all-users.msi for the all-users installer) in File Explorer.
Right-click the file and choose Properties from the context menu.
From the Properties dialog, click the Digital Signatures tab.

Caution:
If the Digital Signatures tab is missing on the installer, discard the file. It may not be authentic.
Select the signature from the Signature list, then click Details.
From the Digital Signature Details dialog, click View Certificate on the General page.

Expired Signatures

An expired certificate doesn't mean that the signature is invalid. A properly timestamped signature remains valid well after the "valid from/to" date range shown in the certificate.

To get the latest certificate, upgrade to the latest available version of the add-in.

Trusted Publishers

Microsoft Excel offers an optional Trust Center setting called Require Application Add-ins to be signed by Trusted Publisher. You can find this setting here: Excel Options > Trust Center > Trust Center Settings > Add-ins. Once it's enabled, exit and restart Excel to have it take effect.

To use this feature, install the certificate:

Open the Certificate dialog for the installer file as described in View the Certificate.
From the Certificate dialog, click the General tab, then click Install Certificate....
From the Certificate Import Wizard, choose either Local Machine for the all users installer or Current User for the current user installer, then click Next.
Select Place all certificates in the following store, then click Browse.
From the Select Certificate Store dialog, select Trusted Publishers, then click OK.
Click Next, then Finish to close the wizard.

The certificate now appears in Excel's Trust Center. Please consult Microsoft documentation for more information.

The Public Key

To get a copy of the public key associated with the add-in's digital certificate:

Open the Certificate dialog for the installer file as described in View the Certificate.
From the Certificate dialog, select the Details tab, then select Public key from the list.
Click Copy to file and follow the instructions in the Certificate Export Wizard.

The Add-in's Certificate Update Cycle

Oracle acquires a new digital certificate approximately every two years. Once available, subsequent releases of the add-in are signed with the new certificate.

If you have installed the certificate and public key previously, you may need to repeat that process after you upgrade to a new version of the add-in signed with a new certificate.