Cloud Connector: How To

In this guide you’ll learn how to configure and use the Neptune DXP Cloud Connector in your own setup.

The Architecture

The intention is to connect two Open Edition environments with each other with the help of our Cloud Connector. We’ll use from now on the following naming:

  • The Cloud Environment will be our Open Edition environment running as a managed environment.

  • The On-Prem Environment will be our Open Edition environment running in our on-premise datacenter.

Create Cloud Connector Connection

  1. Enable the Cloud Connector feature in the DXP Portal.

  2. Add a Connection in the DXP Portal.

  3. Consult the configuration of your new connection in the DXP Portal.

  4. Keep note of these "Connection Details" (namespace, hybrid connection name, shared access policy name and shared access policy key).

Configure On-Prem Environment

All the following operations are done in the Cockpit of the On-Prem Open Edition environment, unless specified otherwise.

  1. Log in to the Cockpit.

  2. Go to "System Settings".

  3. Go to the "Cloud Connector" tab.

  4. Switch to "edit" mode (Click the "edit" button).

  5. Click the "Add" button and choose "Azure Relay".

  6. Specify an arbitrary name (e.g. My Cloud Connection).

  7. Check the "Active" box.

  8. Specify an arbitrary description (e.g. My secure cloud connection).

  9. Fill out the Namespace, Hybrid Connection Name, Shared Access Policy Name and Shared Access Policy Key from the "Connection Details" (see Create Cloud Connector Connection).

  10. Click the "Ok" button.

  11. Click the "Save" button (Important!).

  12. Now a hard restart is required, this means the "restart" button of the cockpit will not be sufficient. Therefore the actual instance/environment of Open Edition has to be stopped and started again.

Verify the configuration

  1. Log in to the Cockpit.

  2. Go to "System Processes".

  3. Find the "Cloud Connector Servers" section, there should be one visible with status "Running".

  4. Consult the configuration of your connection in the DXP Portal. In the overview of the connections you should see 1 listener for your specific connection.

Configure Cloud Environment

All the following operations are done in the Cockpit of the Cloud Open Edition environment, unless specified otherwise.

Proxy Authentication

There are different ways the Cloud Environment can authenticate towards the On-Prem REST API. Choosing "no authentication" does not mean the connection between the Cloud and On-Prem Environments is not secure. The Cloud Connector in itself is a secure channel, however, the target On-Prem REST API might require some authentication. It is this authentication method of the On-Prem REST API which relates to the "Proxy Authentication Type". Whatever the authentication type, the process of enabling the Cloud Connector is the same. In our example we will list a few examples of configuring a Proxy Authentication with the cloud connector.

Proxy Authentication - No Authentication

  1. Log in to the Cockpit.

  2. Go to "Proxy Authentication".

  3. Add new "Proxy Authentication".

  4. Specify an arbitrary name (e.g. My Cloud Connection).

  5. Make sure no "type" is selected.

  6. Check the "Use Cloud Connector" box.

  7. Go to the "Cloud Connector" tab.

  8. Add an arbitrary header with a value (e.g. x-channel: cloud-connector)

  9. Go to the "Cloud Connector" tab.

  10. Choose "Azure Relay" as type.

  11. Fill out the Namespace, Hybrid Connection Name, Shared Access Policy Name and Shared Access Policy Key from the "Connection Details" (see Create Cloud Connector Connection).

  12. Click the "Save" button (Important!).

API

There are two common use cases we shall showcase:

  1. Call an Open Edition Serverscript API of the On-Prem Environment itself.

  2. Call an any REST API which lives within the same local network that is accessible from the On-Prem Environment.

Open Edition Serverscript API

The http://localhost:<port>/<endpoint>; value must be updated accordingly by specifying the port number which the Open Edition environment is listening on. The <endpoint> value can be found on your On-Prem environment (API Designer > Select your target API > Copy the Endpoint value, example value: /public/serverscript/hello-world ).

  1. Log in to the Cockpit.

  2. Go to "API Designer".

  3. Add a new API.

  4. Choose "External" as type.

  5. Specify http://localhost:<port>/api/serverscript/<server-script-api-name>; as endpoint.

  6. Check the "Enable Proxy" box.

  7. Go to the "Authentication" tab.

  8. Click the "Add" button.

  9. Select the desired "Proxy Authentcation" which was created in Proxy Authentication.

  10. Click "OK"

  11. Add your desired "Operations" in the "Operations" tab (see Configuring Operations).

  12. Click "Save"

Any REST API

The http://<url-to-target-api>:<port>; URL must be accessible from the host which runs the On-Prem environment. Updated the scheme to https if applicable.

  1. Log in to the Cockpit.

  2. Go to "API Designer".

  3. Add a new API.

  4. Choose "External" as type.

  5. Specify http://<url-to-target-api>:<port>; as endpoint.

  6. Check the "Enable Proxy" box.

  7. Go to the "Authentication" tab.

  8. Click the "Add" button.

  9. Select the desired "Proxy Authentcation" which was created in Proxy Authentication.

  10. Click "OK"

  11. Add your desired "Operations" in the "Operations" tab (see Configuring Operations).

  12. Click "Save"

Configuring Operations

When configuring Operations which maps 1:1 to an Open Edition Serverscript API in the On-Prem environment, you can just copy the desired operations from there to your Cloud Environment’s API.

When configuring any REST API, the process of defining operations is just like any other "external" type API you would configure in the API Designer.

Test the API

  1. Log in to the Cockpit.

  2. Go to "API Client".

  3. Find your API that was created in API step.

  4. Test any operation.

HTTP Forward Proxy

Some On-Prem environments might use a forward proxy for all outbound connections from On-Prem environments to the public internet. To support this use-case, you need to configure some environment variable(s) for the On-Prem Environment.

To set the environment variable(s) you do need access to the actual OS of the host which hosts the On-Prem Environment runtime so you can set the variables and restart the runtime. If you use containers, you should have an easy way to modify these environment variables.

  1. Set the CLOUD_CONNECTOR_PROXY_HTTP environment variable which specifies the forward proxy address for all http traffic.

  2. Set the CLOUD_CONNECTOR_PROXY_HTTPS environment variable which specifies the forward proxy address for all https traffic.

    • Example http://10.0.0.1 (Note that some forward proxy configurations can use http for forwarding https traffic)

  3. Restart the On-Prem Environment

    • This must be a hard restart of the DXP Open Edition runtine, meaning, stopping the service and restarting, the restart button in the cockpit will not be sufficient.

  4. You can validate if the environment variables are loaded via Cockpit > System Processes > Master > Click Show

  5. Ready to go