1. Developing Integrated Spreadsheets Using Oracle Visual Builder Add-in for Excel
  2. Security

16 Security

When using Oracle Visual Builder Add-in for Excel, refer to this topic for security information including security-related best practices and recommendations.

Security Guidelines

Follow these best practices:

  • Update the add-in to the latest version available.
  • Restrict access to Excel documents containing sensitive data.
  • Consider adding passwords to workbooks to further reduce exposure.
  • Always use HTTPS endpoints instead of HTTP.
  • Do not use basic authentication.
  • Ensure that the latest Windows updates and security patches have been applied to the computers where you install the add-in.
  • Turn off older obsolete security protocols, such as SSL.
  • Consider using Excel's Inspect Workbook feature (available on Excel's File menu) to review and remove personal information from the workbook before you distribute it. When you use the Document Inspector, make sure the Hidden Worksheets check box is not selected. You must not remove hidden worksheets, because the add-in uses hidden worksheets to integrate a workbook with the REST service.

Microsoft Components

Oracle Visual Builder Add-in for Excel relies on a number of Microsoft technologies. These Microsoft technologies are subject to Microsoft's privacy policies and other Microsoft terms.

By installing and using this add-in, you are agreeing to those policies and terms and this add-in's direct or indirect usage of these technologies. See the Microsoft Privacy Statement.

See also Software Dependencies.

Authentication Options

At log in, the add-in uses the catalog's authentication setting to determine how to log in.

The add-in supports four authentication options:

  • Default: At login, the add-in pings an Oracle Cloud Application anti-CSRF servlet endpoint. If the ping succeeds, Oracle Fusion Applications Token Relay is used. If the ping fails, Basic authentication is used instead.
  • Basic Access Authentication: See Basic Authentication.
  • Oracle Fusion Applications Token Relay: See Oracle Fusion Applications Token Relay Authentication.
  • None: There is no prompt for credentials. No authentication-related headers are added to requests.

When you create a new catalog from a URL, the add-in sets the authentication method to "Default" by default. If it instead detects one of the following catalog types, it sets the authentication method to Basic:

  • An Oracle REST Data Services (ORDS) or other API-type catalog
  • A Visual Builder Business Object (VBBO) catalog

For all other Oracle Business Object REST API Services catalogs, the Default method is used.

For information about how to configure your authentication settings, see Set an Authentication Method for a REST Service.

Basic Authentication

Oracle Visual Builder Add-in for ExcelThe add-in supports basic authentication:

  • When a catalog is configured to use Basic Access Authentication, the business user is prompted for basic credentials before the first request is sent to that catalog's endpoints. See Authentication Options.
  • The add-in sends the user credentials in the Authorization header for REST requests to the endpoint. See RFC 7617 for more information.
  • When used with HTTP, basic authentication is not secure. Basic authentication should only be used with HTTPS, and preferably only in non-production environments.
  • Valid credentials for a given service using Basic authentication may be different from valid credentials for Token Relay.

Oracle Fusion Applications Token Relay Authentication

In addition to basic authentication, Oracle Visual Builder Add-in for Excel also supports authentication for REST services exposed by Oracle Cloud applications that use the Oracle Fusion Applications Token Relay servlet. Refer to this topic for technical details on the Token Relay authentication mechanism.

The add-in uses an embedded web browser control to host the login interaction sequence between the workbook user and the Fusion Application (FA) authentication provider. During a successful login, the add-in captures the necessary authentication tokens and then uses them with subsequent REST requests. In particular, the access token is sent using the Bearer authentication scheme in the Authorization header. For more information, see RFC 6750.

What Happens During the Login Sequence?

The add-in performs the authentication process just prior to any business operation initiated by the business user that requires access to the REST service. The add-in uses the catalog's host and basepath properties to compose three other key URLs for the login sequence. For example, if the host is https://<host> and the basepath is /fscmRestApi/resources/v14, then the URLs needed for token relay authentication would be:

  • The UI home page: https://<host>/fscmUI/faces/FuseWelcome
  • The Anti-CSRF endpoint: https://<host>/fscmRestApi/anticsrf
  • The token relay servlet endpoint: https://<host>/fscmRestApi/tokenrelay

The Login Sequence Starts in the Embedded Browser

  1. The add-in displays a modal pop-up login window that contains an embedded browser control, and directs the browser control to navigate to the UI Home Page URL.

    Note:

    The embedded browser may be Microsoft's Edge/Chromium-based WebView2, or it may be Microsoft .NET WebBrowser (based on MS Internet Explorer). See Embedded Browsers.
  2. Since the business user has not yet successfully logged in, the browser is redirected to a page with a login form. This form typically contains user name and password fields and a Submit button.
  3. The login user interface pages are controlled by the FA environment. There could be multiple steps involved, such as SSO, multi-factor authentication, and so on.
  4. Each time a user's gesture or login page logic causes a page navigation event in the browser, the add-in's event handler is notified and the add-in performs an authentication test (see Authentication Test) to see whether the user has logged in.
    • If the user has successfully logged in, the login sequence is complete. The add-in automatically closes the login window and can continue with the REST request that triggered the login sequence using the harvested authentication tokens.
    • If the user has not yet logged in, the login window remains visible and the add-in continues listening for page navigation events.

Authentication Test

The add-in watches for page transitions in the embedded browser and performs a test to see if the user has successfully logged in. If, using the cookies from the embedded browser, the add-in can obtain a token from the Token Relay servlet, then the user has successfully authenticated.

Details about the test:

  1. When each page navigation event is raised from the browser, the add-in attempts to get an anti-CSRF token by making a GET request to the anti-CSRF endpoint. This step is skipped once an anti-CSRF token is obtained.
  2. The add-in then makes a GET request to the Token Relay servlet endpoint. If the request is denied, the test fails; Otherwise, on a 200 OK with a response payload of content-type application/json:
    1. The payload is parsed and validated. The token_type member must have the value "JWT" and the access_token member must be present and non-empty.
    2. The value for token_type is captured in memory and used for subsequent REST requests.
    3. If the parsing succeeds, the test is considered to have passed. The login window is closed, and the target REST request continues.
    4. Otherwise, the test is considered to have failed and the login window remains open.

Variations

  1. If the authentication method in the service catalog of the integrated workbook is configured to be "Default", an initial ping request to the anti-CSRF endpoint is made before the login sequence begins.
    1. If the request returns a 404 or other error, then the add-in abandons the Token Relay authentication mechanism. This means it falls back to using Basic authentication.
    2. If the request returns a 200, with content-type application/json, and the payload contains a non-empty xsrftoken member, then the add-in proceeds with the login sequence.
  2. If the authentication method property in the service catalog of the integrated workbook is configured to be "Oracle Fusion Application Token Relay", the initial ping to the anti-CSRF endpoint is skipped. The ping occurs later during page navigation.

Requirements

  • The UI Home Page must be protected in such a way that an unauthenticated request in a browser redirects the browser and initiates a login sequence by redirecting to a login page.
  • The /anticsrf endpoint should allow anonymous ("unauthenticated") access. The response payload must contain the token in the xsrftoken member.
  • The /tokenrelay endpoint must be protected so that only authenticated users, identified by cookies issued during the browser login sequence, may access it. The response payload must contain a token_type member which must have the value "JWT" and also a access_token member, which must be non-empty. See RFC 7519 for more information.
  • Oracle Fusion Applications Token Relay is only supported for Oracle Cloud Application deployments that include standardized /anticsrf and /tokenrelay endpoints with standardized payloads. This behavior is not configurable at this time.
  • Token Relay is not supported for other service types such as ORDS or VBBO.

Transport Layer Security

When the add-in connects to a REST endpoint using HTTPS, the add-in enables the system default behavior for Transport Layer Security (TLS) to determine which TLS protocol is to be used.

Because the add-in runs within the Excel process, it cannot rely entirely on the .NET 4.7 default setting to do this. To ensure that the system default behavior is in effect, the add-in sets the AppContext.DontEnableSystemDefaultTlsVersions property to false for the current app domain.

See the following Microsoft documentation:

The Digital Certificate

The artifacts that make up the Oracle Visual Builder Add-in for Excel 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 Windows 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.

Can I inspect the certificate?

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

To do so, navigate to the installer file (vbafe-installer-all-users.msi for the all-users installer), open the Properties window, then select the Digital Signatures tab.

Caution:

If the Digital Signatures tab is missing on the installer, discard the file. It may not be authentic.

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.

To use this feature, install the certificate:

  1. From the Digital Signatures tab, select the signature from the Signature list and click Details.
  2. From the Digital Signature Details dialog, select the General tab, then click View Certificate.
  3. From the General tab of the Certificate dialog, click Install Certificate....
  4. From the Certificate Import Wizard, choose either Local Machine for the all users installer or Current User for the current user installer.
  5. Click Next.
  6. Select Place all certificates in the following store and then click Browse.
  7. From the Select Certificate Store dialog, select "Trusted Publisher" and then click OK.
  8. 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:

  1. From the Digital Signatures tab, select the signature from the Signature list and click Details.
  2. From the Digital Signature Details dialog, select the General tab, then click View Certificate.
  3. From the Certificate dialog, select the Details tab, then select Public Key from the list.
  4. Click Copy to file....
  5. 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.