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 five 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.
  • OAuth 2.0 Authorization Code (PKCE): See OAuth 2.0 Authorization Code Flow.
  • No Authentication: There is no prompt for credentials. No authentication-related headers are added to requests.

You can choose an authentication method when creating a new catalog. You can also change it later.

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

Oracle Visual Builder Add-in for Excel 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.

OAuth 2.0 Authorization Code Flow

Oracle Visual Builder Add-in for Excel supports authentication for REST services using OAuth 2.0 Authorization Code flow with Proof Key for Code Exchange (PKCE).

This authentication method allows clients like the add-in to authenticate and get an access token which can then be used to make REST requests to service endpoints.

The OAuth 2.0 Authorization Code flow is supported by Visual Builder Business Object services.

Refer to the OAuth 2.0 Authorization Framework documentation for more information.

OAuth 2.0 Authorization Code Flow Configuration

In order to configure your workbook to use OAuth 2.0 Authorization Code flow, you'll obtain a client identifier from the security administrator for the service you are using. You'll also need to provide other details such as required endpoint URLs. Consult with the REST service owner for help.

You can configure this authentication method for a new workbook when you create a catalog. During the new layout setup process, you'll be prompted to provide authentication details when you select "OAuth 2.0 Authorization Code (PKCE)" from the Authentication list. See Create a Form-over-Table Layout in an Excel Workbook or Create a Table Layout in an Excel Workbook.

You can also configure authentication details for an existing catalog from the Advanced page of the Business Object Catalog Editor. When you select this authentication method from the Authentication list, click Edit Authentication Flow Properties to access the OAuth 2.0 Authorization Code (PKCE) screen. See Set an Authentication Method for a REST Service.
OAuth 2.0 Authorization Code (PKCE) screen

  • Client Identifier: The identifier set up for the add-in to use when executing the authorization flow. Obtain this value from the security administrator for your service.
  • Authorization Endpoint: The authorization server endpoint used by the client to obtain authorization from the resource owner via user-agent redirection.
  • Redirection Endpoint: The client endpoint used by the authorization server to return responses containing the authorization code to the client using the resource owner user-agent.
  • Access Token Scope: The authorization and token endpoints allow the client to specify the scope of the access request using the "scope" request parameter.
  • Token Endpoint: The authorization server endpoint used by the client to exchange an authorization grant for an access token, typically with client authentication.

Note:

For more information on these properties, see OAuth 2.0 Authorization Framework.

This screen also includes Import and Export buttons that you can use to upload and download a JSON file with the authentication properties. Here is an example of the JSON: 

{  
  "type": "oauth2",
  "authorizationCode":
  {
    "clientId": "31415926",
    "authorizationEndpoint": "https://demo/oauth2/v1/authorize",
    "redirectionEndpoint": "https://demo/authorization-redirect",
    "accessTokenScope": "scope1 scope2",
    "tokenEndpoint": "https://demo/oauth2/v1/token"
  }
}

Note:

These values are just examples. The correct values will be different for your service. Contact the service admin to obtain the correct values.

Details of the Authorization Flow

The authorization flow follows these steps:

  1. The add-in starts the login sequence by validating the OAuth2 configuration properties. If the properties are valid, the flow proceeds.

    If the properties are missing or otherwise invalid, then the login attempt is aborted and an error is reported. For example, an endpoint property that is not an absolute URL is invalid and results in an aborted login.

  2. The add-in constructs a Uniform Resource Identifier (URI) using the Authorization Endpoint property, along with Client Id and other values saved in the OAuth 2.0 Authorization Code (PKCE) screen.
  3. The add-in displays the login browser window and instructs the browser to navigate to that authorization Uri.
  4. The add-in watches for page transitions and redirects in the browser. All other browser and user interactions are governed by the logic and configuration of the authorization server.

    There could be multiple pages and steps necessary for the user to provide credentials, get consent, and so on.

  5. When the authorization server redirects the browser back to the Redirection Endpoint, the add-in closes the browser.

    If the Redirect indicates an error, the add-in reports it and aborts the login flow. On a successful redirect, the add-in performs some validation on the returned values. If that succeeds, the add-in proceeds with the flow.

  6. After a successful redirect, the add-in harvests the authorization code and sends it, along with other key values, in a POST request to the Token Endpoint.

    The Token Endpoint returns an access token, which the add-in then includes in the Authorization header using the Bearer scheme, when making subsequent REST requests.

Limitations and Known Issues

  • PKCE support is required. See RFC 7636.
  • There is currently no support for token Refresh logic.
  • For the first step in the OAuth2 flow, the code_challenge is set using code_challenge_method=S256. "Plain" is not supported.

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.