Security

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.
Disable deprecated transport layer protocols, such as SSL, TLS 1.0, and TLS 1.1. Refer to KB5017811—Manage Transport Layer Security (TLS) 1.0 and 1.1 after default behavior change on September 20, 2022 on the Microsoft Support site.
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.

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 with PKCE.
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 section for technical details on the Token Relay authentication mechanism.

Topics:

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

The add-in uses these endpoints to get the authentication token:

Endpoint	Example
UI home page	`https://<my-service-host>/fscmUI/faces/FuseWelcome`
Anti-CSRF endpoint	`https://<my-service-host>/fscmRestApi/anticsrf`
Token relay servlet endpoint	`https://<my-service-host>/fscmRestApi/tokenrelay.`

Note:

In most cases, <my-service-host> is the catalog host. If a Token Relay Host is configured, it is used instead. See Configure Token Relay Authentication for a Catalog.

The login sequence:

If the catalog is configured to use the "Default" authentication method, the add-in makes an initial ping request to the anti-CSRF endpoint.
- If the request returns a 404 or other error, then the add-in abandons the Token Relay authentication mechanism and falls back to using Basic authentication.
- 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.
Note:
If the catalog is configured to use the "Oracle Fusion Application Token Relay" authentication method, the initial ping to the anti-CSRF endpoint is skipped. The ping occurs later during page navigation.
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. See The Embedded Browser.
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.
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.
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 to see whether the user has logged in. See Token Relay Authentication Test.
- 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.
- If the user closes the login window before logging in successfully, the operation that initiated the authentication process is canceled.

Token Relay Authentication Test

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

Details about the test:

When each page navigation event is raised from the browser, the add-in sends a GET request to the anti-CSRF endpoint in order to get an anti-CSRF token.
Once an anti-CSRF token is obtained, the add-in skips this step on subsequent page navigation events.
The add-in then makes a GET request to the Token Relay servlet endpoint. This request includes the ScopesFQ value, if configured. 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 access_token member must be present and non-empty.
2. The value for access_token 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.

Configure Token Relay Authentication for a Catalog

When you configure token relay authentication, you're prompted to provide values for two optional configuration properties: Token Relay Host and ScopesFQ. If your REST service doesn't require values for these settings, you can leave them blank.

Provide a Token Relay Host value if the Fusion Applications token relay service is located on a different host than your REST service. If these services are both hosted on the same pod, you can leave this field blank and Oracle Visual Builder Add-in for Excel will use the catalog's host instead.

Provide a ScopesFQ value if you want to append a scopesfq query parameter value when calling the token relay service. If you leave this field blank, the add-in does not include the scopesfq query parameter.

Consult with your REST service owner or refer to the documentation for your target REST service to determine the appropriate values for these properties.

These optional authentication properties can be configured when you create a catalog during layout creation. They can also be configured for an existing catalog from the Business Object Catalog Editor.

To configure token relay authentication during new layout creation:

Launch the New Layout Setup wizard as described in either Create a Table Layout in an Excel Workbook or Create a Form-over-Table Layout in an Excel Workbook.
From the first screen of the wizard, select Oracle Fusion Applications Token Relay from the Authentication list, then click Next.

The wizard displays a screen for entering token relay properties. This image shows the screen with sample values in the screen's fields.

Description of the illustration token-relay-config.png

Note:
You can also access this screen for an existing catalog from the Advanced page of the Business Object Catalog Editor. To open this screen, select Oracle Fusion Applications Token Relay from the Authentication list, then click Edit Authentication Flow Properties. See Set an Authentication Method for a REST Service.
If the Fusion Applications token relay service is located on a different host than the REST service, type the token relay host in the Token Relay Host field.

The host should use this format: <protocol>://<host>:<port>. For example:

https://my-pod.fa.ocs.oraclecloud.com:443

Note:
Do not include the path to the Fusion Applications token relay service.
If you want to include a scopesfq query parameter, type it in the ScopesFQ field.
If include a value here, the add-in URL-encodes this value and adds it as the scopesfq query parameter value when calling the token relay service.
Click Next to proceed through the New Layout Setup wizard.

The sample values in the image results in this URL (with URL encoding omitted for readability):

https://my-pod.fa.ocs.oraclecloud.com:443/fscmRestApi/tokenrelay?scopesfq=urn:opc:resource:fusion:xxx:erp/

Requirements for Token Relay Authentication

Before configuring Token Relay Authentication for an integrated workbook's catalog, review these 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.
Oracle Fusion Applications Token Relay is only supported for Oracle Cloud Application deployments that include standardized /anticsrf and /tokenrelay endpoints with standardized payloads.

OAuth 2.0 Authorization Code Flow with PKCE

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.

This authentication method is required by some services such as NetSuite.

The easiest way to configure OAuth is to fill in and import a JSON configuration file with the required OAuth properties. See Configure OAuth 2.0 Authorization for a Catalog for the steps to configure OAuth for your workbook.

To configure your workbook to use OAuth 2.0 Authorization Code flow, you'll need to obtain some authentication details from your REST service owner. See OAuth 2.0 Authorization Properties.

OAuth 2.0 Authorization Properties

In order to configure your workbook to use OAuth 2.0 Authorization Code flow, you'll need to 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.

Here are the required OAuth properties:

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:

The add-in does not require the Client Secret.

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

OAuth 2.0 Authorization Code Flow Steps

The authorization flow follows these steps:

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.
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.
The add-in displays the login browser window and instructs the browser to navigate to that authorization Uri. See The Embedded Browser.
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.
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.
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.

Refer to Authorization Code Grant for information on authorization code flow. See also Proof Key for Code Exchange by OAuth Public Clients for information on PKCE.

Configure OAuth 2.0 Authorization for a Catalog

You can configure your integrated workbook to authenticate with the REST service using OAuth 2.0 Authorization code flow. You can provide the required authentication properties when you create a catalog during the creation of a layout.

You can also configure an existing catalog to use this authentication method from the Business Object Catalog Editor.

The easiest way to configure this authentication method is to export a blank JSON file from Oracle Visual Builder Add-in for Excel, fill in the required values, and import the completed configuration file.

Before you proceed, obtain the required properties from the REST service owner. See OAuth 2.0 Authorization Properties.

To import a configuration file during new layout creation:

Launch the New Layout Setup wizard as described in either Create a Table Layout in an Excel Workbook or Create a Form-over-Table Layout in an Excel Workbook.
From the first screen of the wizard, select "OAuth 2.0 Authorization Code (PKCE)" from the Authentication list, then click Next.

The wizard displays a screen for entering OAuth 2.0 properties. This image shows the screen with sample values in the screen's fields.

Description of the illustration oauth-properties-screen.png

Note:
You can also access this screen for an existing catalog from the Advanced page of the Business Object Catalog Editor. To open this screen, select "OAuth 2.0 Authorization Code (PKCE)" from the Authentication list, then click Edit Authentication Flow Properties. See Set an Authentication Method for a REST Service.
Click the Export icon () to save a blank JSON file with the required properties to your local drive.

Provide this file to the service owner to fill in.

Here is an example of the JSON file showing sample values:

{  
  "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"
  }
}

When you get the JSON file back with the required values, click the Import icon () to import the file to the add-in.
Click Next to proceed through the New Layout Setup wizard.

OAuth Limitations and Known Issues

Before configuring OAuth 2.0 for an integrated workbook's catalog, review the limitations here:

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.

Service Authorization and User Privileges

In addition to authentication ("who am I"), REST services often enforce authorization ("what am I allowed to do") on every service request (GET, POST, PATCH, and so on). REST services may require business users to have specific privileges in order for them to view and update data.

Oracle Visual Builder Add-in for Excel does not have access to the user identity or any kind of privilege/role/authorization information and can't check authorization prior to an operation. Instead, it is the service that enforces authorization and returns an error if the current user is not authorized to perform the requested operation.

If the workbook is configured to allow an operation the business user is not authorized for, the user may see an error such as an 403 Forbidden error. For these cases, the business user should follow up with the REST service owner or system administrator in order to be granted the appropriate privileges.

Transport Layer Security

When the add-in connects to a REST endpoint using HTTPS, the add-in relies on 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 Framework 4.8 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:

From the Digital Signatures tab, select the signature from the Signature list and click Details.
From the Digital Signature Details dialog, select the General tab, then click View Certificate.
From the General tab of the Certificate dialog, 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.
Click Next.
Select Place all certificates in the following store and then click Browse.
From the Select Certificate Store dialog, select "Trusted Publisher" and 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:

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