Overview

There are several integration scenarios in Clio Operate where you will want to make calls to an external API. These calls could be from custom UI components (widgets/blades, etc.) or from the server using custom workflow actions or execution engine scripts.

There are a variety of ways to achieve this, including calling directly using XMLHttpRequest (from the UI) or the HTTP client (from the server). However, both have some complex challenges that need to be resolved, including:

• From the UI
  • Content Security Policy
  • Cross-Origin Requests
  • Configuration
  • Token/Key management
    • Leaking security information
• From the server
  • Configuration
  • Token/Key management

Content Security Policy

The first issue with calling your API from the UI, and the one most easily resolved, is the content security policy (CSP) within Clio Operate itself. The CSP prevents the browser from loading content or making connections to external sources that haven't explicitly been declared in the CSP feature.

As such, by default, a call from your Clio Operate instance URL to your custom API URL will be blocked by the CSP.

This is relatively easy to resolve by navigating to global features, locating the "Content Security Policy" feature, and adding your API URL to the `connect-src` section of the configuration.

Cross-Origin Requests

The second issue, which also applies only to calling your API from the UI, concerns Cross-Origin Resource Sharing (CORS). The default behaviour of the browser is to block any XHR requests across different origins. An origin is the same combination of scheme, subdomain, domain and port. If there are differences between those components of the URL, then XHR will be blocked by default.

The upstream API needs to advertise which origins are allowed to call it, and so, your Clio Operate instance URL would need to be added to its CORS policy to allow the browser to make XHR calls from the Clio Operate UI to your API.

If you are in control of the integration, it's likely this won't pose any problems, as you can control the CORS policy. Most 3rd party services also provide mechanisms to allow CORS on their APIs for your account, etc., but if they don't, you would need to either build a facade over the API to be consumed, which will forward requests on, or build a custom module extension for Clio Operate to allow such a facade to run within Clio Operate's server-side code. CORS does not apply to server-to-server calls; it's purely enforced in the browser.

Configuration

For both UI and execution engine calls to your integration API, there is also a question around configuration. Inevitably, you will need to run your integration in test, UAT, training, and production, each potentially using a different API instance in that environment.

While there are some mechanics in Clio Operate for this, such as the settings API, it still adds reasonable complexity to your UI and EE integrations to inspect this configuration.

Token/Key management (and leaky security)

It would be unusual to have an integration between Clio Operate and some upstream API that does not require any form of security. At a minimum, the upstream service would require presentation of an API key, or, more likely, it will implement one of the standard OAuth flows, such as authorisation code grant, which will require a user to sign in, grant consent to Clio Operate, and then issue access and refresh tokens that then need to be managed.

On the one hand, the simple API key approach could be implemented even in the UI by embedding the appropriate API key in the JavaScript. This is a fundamental security issue, though, as the browser isn't a trusted client, and that secret will be exposed anywhere it is used - there's nothing stopping a nefarious actor from obtaining that secret key and using it for their own malicious intent.

Managing OAuth flows and the tokens required in the auth code flow without leaking them into the browser via cookies or local storage is a non-starter.

Introduction to linked services and the proxy

To address all of these potential issues, Clio Operate features a linked service system. This allows defining an integration service that Clio Operate can connect to, along with its configuration, and specifies how it should implement security, etc. This manages the service configuration, allowing different instances of Clio Operate to configure different locations for upstream integration APIs, etc., and provides all the facilities for the automatic management of keys and tokens.

For instance, where a service is registered as OAuth, using Auth Code flow, it will provide the UI and tooling to link an account to Clio Operate, allow users to link their own personal accounts if appropriate, and manage the flow of authentication and consent, then manage the lifetime of any access and refresh tokens automatically.

To go alongside this, a Linked Service Proxy API is available, allowing your custom UI and workflow actions, etc., to call a Clio Operate API as normal, specify the named service to proxy to, and have Clio Operate wrap all the appropriate security tokens, etc., before forwarding the call onto the service and returning the response.

This proxy and the linked service definition address all the above common problems.

• CSP is no longer in effect because your UI component calls a standard Clio Operate API at a known and allowed location.
• CORS is no longer in effect because your UI component CSP is no longer in effect, as your UI component calls a standard Clio Operate API at a known and allowed location. a standard Clio Operate API on the same origin, which in turn calls the upstream service, and server-to-server calls are not affected by CORS.
• Configuration is managed within the linked service definition, and as such, your UI component or custom WF action doesn't need to concern itself with configuration issues like the API base address.
• Token and key management is handled automatically, server-side, based on the security provider chosen when your service was registered. As the tokens are injected into the request from the proxy, none of this information is leaked out to the browser.

Creating a linked service

To create a linked service, sign in with an administrator-level account and navigate to /admin/oauth or Admin > Integrations > Manage Linked services. This then displays a list of integrations configured for Clio Operate.

Clicking the "+ Add New" button on the ribbon (top right) lets you first select the security mechanism for your service.

The blade presented will vary depending on the type of service being added, but it will allow you to configure the specifics of your service. The base URL, for example. In the screenshot below, we chose the legacy shared secret/API key provider, so we have a configuration to specify the key.

Be sure to enable the proxy!

Congratulations, you've now registered your external API integration, and it's ready for use from the UI or workflow by using the proxy. One final thing you will notice, though, is that all the providers have the option to "enable proxy" - this must be switched on if you wish to use the service via the proxy API!

Using the linked service proxy

With the service registered, linked and enabled for proxy, you are then free to call the Clio Operate proxy API at /api/proxy/{serviceSystemName}/_/{apiPath}, where {serviceSystemName} is the system name of the service you registered earlier and {apiPath} is the URL of the upstream API to be called, but without the scheme, domain or port components. The API supports all the common HTTP verbs, so get, put, post, delete, etc. will all proxy.

For example, assuming you have an upstream service at https://myapi.local:9182/api/info, you would register the linked service using the appropriate authentication provider and configure its base address as https://myapi.local:9182/. Assuming you named this "myapi", then you would issue a GET request to Clio Operate's proxy at `/api/proxy/myapi/_/api/info`. This will then route through the proxy, automatically do any token management for you, then forward the request on with appropriate headers before returning the response.

As with all Clio Operate APIs, your request must be authenticated using a bearer token, but that is handled automatically for you if you are using the UI framework's `$ajax` methods, or the `http` utilities in workflow.

Source code

All source code for this series is available on GitHub here: 
https://github.com/sharedo-tech/sharedo_ide/tree/main/LinkedServiceAndProxy