Note:

Configure Custom App URL and OCI Web Application Firewall for Visual Builder Cloud Service Apps on Oracle Integration

Introduction

By default, PaaS Visual Builder Cloud Service Apps (VBCS)/Oracle Integration instances generate URLs with Oracle domains. However, customers can access their deployed apps using personalized domains for branding purposes or to shield the underlying infrastructure from direct exposure. To set up this customization, VBCS offers the option to configure custom URLs or Vanity domains for apps deployed on the VBCS/Oracle Integration instance.

Advantages of using vanity domains:

The default URL for VBCS/Oracle Integration instance is typically structured in the following format:

https://<instance-display-name>-<tenancy-name>-<region-code>.integration.ocp.oraclecloud.com

Objectives

This tutorial will demonstrate the step-by-step process of setting up a Custom URL for apps deployed on a VBCS instance enabled on an Oracle Integration instance.

For the purpose of demonstration, consider there are two apps deployed on the instance.

APP NAME Custom URL
VBCS APP1 myapp1.mydomain.com
VBCS APP2 myapp2.mydomain.com

VBCS app image

Prerequisites

Configuration

To make the configuration simple and clear, let’s break the configuration into two major tasks. First task details the configuration required at the Oracle Integration layer and second task details the configuration required at the VBCS layer.

  1. Configure custom endpoints for Oracle Integration instance.

  2. Configure custom URLs for VBCS App.

Task 1: Configure custom endpoints for Oracle Integration instance

In order to configure custom URLs for the VBCS Apps, Oracle Integration instance must be configured with the custom endpoints.

Oracle Integration instance can be configured with single primary custom endpoint and multiple alternate custom endpoints. Primary endpoint can be configured via Oracle Cloud Infrastructure (OCI) console, whereas alternate custom endpoints are currently only supported through OCI SDKs like Python and Java. Alternate custom endpoints are required when you want to have custom URLs configured for each of the APPs in VBCS.

In this tutorial, we will use the Python SDK to configure alternate custom endpoint at Oracle Integration.

Task 1.1: Obtain CA signed certificates

Obtain CA signed certificates for the desired custom URLs.

myapp1.mydomain.com
myapp2.mydomain.com

Task 1.2: Store certificate chain as a secret in OCI Vault

Oracle Integration accepts OCI Vault secret as input for the certificate chain. For details about the secret syntax, see Configure a Custom Endpoint for an Instance.

High level steps include create vault, create key, and create secret.

Copy the Oracle Cloud Identifier (OCID) of the vault secret.

{
  "key": "-----BEGIN PRIVATE KEY-----\n<key string>..-----END PRIVATE KEY-----\n",
  "cert": "-----BEGIN CERTIFICATE-----\n<cert string>-----END CERTIFICATE-----\n",
  "intermediates": [
    "-----BEGIN CERTIFICATE-----\n<cert string>-----END CERTIFICATE-----\n",
    "-----BEGIN CERTIFICATE-----\n<cert string>-----END CERTIFICATE-----\n"
  ],
  "passphrase": "<private key password if encrypted key is provided>"
}

Task 1.3: Create alternate custom endpoint

Now let’s create alternate custom endpoint using Python SDK.

Note:

  1. Create the Python script.

    import oci

config = oci.config.from_file(file_location="<location to the OCI config file>")

# Initialize service client with default config file
integration_client = oci.integration.IntegrationInstanceClient(config)

# Send the request to service, some parameters are not required, see API
# doc for more info
update_integration_instance_response = integration_client.update_integration_instance(
    integration_instance_id="<OIC Instance OCID>",
    update_integration_instance_details=oci.integration.models.UpdateIntegrationInstanceDetails(
        alternate_custom_endpoints=[
            oci.integration.models.UpdateCustomEndpointDetails(
                hostname="myapp1.mydomain.com",
                certificate_secret_id="<OCID of the Secret>"),
                oci.integration.models.UpdateCustomEndpointDetails(
                hostname="myapp2.mydomain.com",
                certificate_secret_id="<OCID of the Secret>")]),
    )

# Get the data from response
print(update_integration_instance_response.headers)

    {OIC Instance OCID} - replace with OIC instance OCID.

    {OCID of the Secret} - replace with Vault Secret OCID copied in previous step.

  2. Execute the Python script.

    python <scriptname.py>

  3. Verify the workrequest job status in the OCI console, it should take approximately 15 minutes.

Note: Alternate custom endpoint can also be configured through OCI CLI, see Update integration instance .

Task 1.4: Get custom endpoint alias details

Each custom endpoint that was created will have a unique alias associated with it. This information can be seen via API and is not visible on the console.

Execute the following script to get the details:

import oci
config = oci.config.from_file(file_location="<config file>")
integration_client = oci.integration.IntegrationInstanceClient(config)
# Send the request to service, some parameters are not required, see API
# doc for more info
get_integration_instance_response = integration_client.get_integration_instance(
    integration_instance_id="<OIC Instance OCID>")
print(get_integration_instance_response.data)

{OIC Instance OCID} - replace with OIC instance OCID.

Below is the sample output:

vbcs custom alias

Task 1.5: Create DNS records

To access VBCS/Oracle Integration instance, create CNAME DNS records that resolves to the alternate custom endpoint alias associated with the respective custom URL.

CNAME Records

Custom Hostname Alias Target
myapp1.mydomain.com <alias1-xxxyyyy.integration.ocp.oraclecloud.com>
myapp2.mydomain.com <alias2-xxxyyyy.integration.ocp.oraclecloud.com>

VBCS builder page can now be accessed using the configured alternate custom endpoint URLs.

https://myapp1.mydomain.com/ic/builder (VBCS builder page for app1).

https://myapp1.mydomain.com/ic/home (Oracle Integration page).

https://myapp2.mydomain.com/ic/builder (VBCS builder page for app2).

https://myapp2.mydomain.com/ic/home (Oracle Integration page).

vbcs app builder

Task 2: Configure custom URLs for VBCS APPS

Configuring custom URLs for VBCS APPS involves updating custom URL for the VBCS App in the App Settings options.

  1. Log in to the builder page, ensure to use the custom host of APP1 https://myapp1.mydomain.com/ic/builder.

  2. Click on hamburger menu against the app.

    vbcs custom app url

  3. Select New Version.

    vbcs app new version

  4. Once the app is in development mode, click Settings.

    vbcs app settings

  5. Update the vanity URL field with custom URL.

    vbcs app update vanity url

  6. Next, stage the app.

    vbcs app stage

    vbcs app stage2

  7. Finally, publish the app.

    vbcs app1 publish

    Note: Custom URLs for VBCS apps works only for the published apps, custom URLs cannot be accessed in development mode.

  8. Repeat the above steps for APP2.

Now, Let’s access the app with the custom URL.

APP1 Image:

https://myapp1.mydomain.com

myapp1

APP2 Image:

https://myapp2.mydomain.com

myapp2

Task 3: Configure WAF

Web Application Firewall protects web applications from a wide range of online threats including SQL injection, cross-site scripting (XSS), remote code execution and more. Thus it is strongly recommended to protect VBCS applications using OCI WAF (Edge or regional).

For more details, see Protect Visual Builder Cloud Service Apps with OCI Web Application Firewall on Oracle Integration.

Conclusion

Vanity Domains or Custom URLs presents a valuable opportunity for customers to enhance their applications hosted on the VBCS instance. By opting for personalized domains, customers can reinforce their brand identity, promote a professional online image, and create a more memorable experience for users. Utilizing Vanity Domains/Custom URLs allows customers to shield their applications’ underlying infrastructure, safeguarding against direct exposure to actual hostnames.

Furthermore, customers can take their security measures a step further by implementing a Web Application Firewall (WAF) in front of their applications. The WAF acts as a proactive defense mechanism, analyzing and filtering incoming web traffic, thus reducing the risk of malicious attacks and ensuring a safer browsing experience for end-users.

In summary, the combination of Vanity Domains/Custom URLs and the implementation of a WAF reinforces both branding and security aspects for applications hosted on the VBCS instance, providing a comprehensive and robust solution for businesses to thrive in the digital landscape.

Acknowledgments

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.