Opscotch has been designed to make HTTP calls to HTTP-enabled services like APIs and websites. As security is always a top priority, HTTP calls are strictly controlled in several ways.

How does this work?

Firstly, workflows cannot simply call any arbitrary host - workflows can ONLY call hosts that have been specified in the bootstrap using the allowExternalHostAccess property. Since the bootstrap cannot be changed remotely, the hosts available to opscotch workflows are limited to those defined by the administrator who installs opscotch.

Hosts in the allowExternalHostAccess property must include at a minimum: an id and a host (the base URL). When workflows request an HTTP call to be made, the id is used to select the host from the bootstrap, and the workflow can append a path to the base URL -the workflow cannot change the base URL, only extend it.

A second level of security is the use of the allowList on the bootstrap host record. The allowList is a set of HTTP method and path regex patterns. For example, you can allow GET methods to .* (all paths) and POST to /records. Note that without an allowList, all paths can be called with any method. Once you supply an allowList, all calls must match at least one entry in the allowList. In the above example, calls with the DELETE method (and any other method) would fail.

Take a look at the documentation and note the key properties:

• id: This is how you will refer to the host from your workflow (e.g., anApiHost).
• host: This is the base URL that you permit your workflow to make calls to (e.g., https://api.example.com/an-allowed-path).
• headers: You can specify any headers that you want to add to all calls to the host.
• allowList: You can specify a list of allowed HTTP methods and regex patterns to match URL paths.
• authenticationHost: When this is set to true, this host is only callable from a step authenticationProcessor.

A third security mechanism is the authenticationHost - set this to true for any host that you use to perform authentication, such as logging in or obtaining a token. This will restrict access to step authenticationProcessors.

How to use allowExternalHostAccess from Workflows

In the bootstrap, you will need to add the host we described to the allowExternalHostAccess property:

Bootstrap:

{
    ...
    "allowExternalHostAccess" : [
        {
            "id" : "anApiHost",
            "host" : "https://api.example.com/an-allowed-path",
            "allowList" : [
                {
                    "method" : "GET",
                    "uriPattern" : ".*"
                },
                {
                    "method" : "POST",
                    "uriPattern" : "/records"
                }
            ]
        }
    ],
    ...
}

From a step processor JavaScript script, use the setHttpMethod(...), setUrl(...), and setBody(...) functions. For example, to use the host defined above (id: anApiHost) and call POST /records with the payload body { 'some': 'json' }, you would have the following JavaScript processor:

context.setHttpMethod("POST");
context.setUrl("anApiHost", "/records");
contett.setBody("{ 'some' : 'json' }");

This would make an HTTP POST call to https://api.example.com/an-allowed-path/records with the payload { 'some': 'json' }. `