18 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.
- 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.
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 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 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 following endpoints to obtain the authentication token:
- The UI home page: for example,
https://my-service-host/fscmUI/faces/FuseWelcome
. - The Anti-CSRF endpoint: for example,
https://my-service-host/fscmRestApi/anticsrf
. - The token relay servlet endpoint: for example,
https://my-service-host/fscmRestApi/tokenrelay.
The Login Sequence Starts in the Embedded Browser
- 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 Embedded Browsers.
- 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 (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.
- If the user closes the login window before logging in successfully, the operation that initiated the authentication process is canceled.
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:
- 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.
- 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
:- The payload is parsed and validated. The
token_type
member must have the value "JWT" and theaccess_token
member must be present and non-empty. - The value for
access_token
is captured in memory and used for subsequent REST requests. - If the parsing succeeds, the test is considered to have passed. The login window is closed, and the target REST request continues.
- Otherwise, the test is considered to have failed and the login window remains open.
- The payload is parsed and validated. The
Variations
- 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.
- 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.
- If the request returns a 200, with content-type
application/json
, and the payload contains a non-emptyxsrftoken
member, then the add-in proceeds with the login sequence.
- 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 atoken_type
member which must have the value "JWT" and also aaccess_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 Visual Builder Business Object (VBBO).
OAuth 2.0 Authorization Code Flow with PKCE
This authentication method is required by some services such as Visual Builder Business Objects.
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 Embedded Browsers.
- 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:
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 usingcode_challenge_method=S256
. "Plain" is not supported.
Service Authorization and User Privileges
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.
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.