Note: If you have never upgraded from pre-2019.6, or have never created custom legacy "widget" style apps in the agent interface, then this article does not apply to you and you can safely ignore this.

Deskpro has an old proxy API to enable the old "widgets" system to consume APIs that do not have CORS enabled. This old proxy was open to any logged-in agent and could be used to perform any HTTP request.

As of version 2019.6, this proxy is controlled with a whitelist to ensure only specific whitelisted APIs are allowed to be called through the proxy. This whitelist is completely empty by default, which effectively disables the proxy.

If you have a custom "widget" style app installed, and you upgrade through 2019.6, then the proxy is kept enabled for backwards compatibility. If you know your widgets don't use the API proxy, you can empty the whitelist to disable it; or if your API does use the proxy, you can whitelist the specific endpoints that are used to prevent the proxy from being used to call other arbitrary endpoints.

FAQ

Q: I have upgraded from a previous version, do I need to do anything?

No, not specifically. 

If have a custom widget installed, then the upgrade system will have re-enabled the old open proxy for backwards compatibility on the off-chance your custom widgets are using it. If you don't have any custom widgets installed, then the old open proxy will be disabled as per the default.

Q: I have a custom widget, but I know it does not use the proxy. What should I do?

The upgrade system will have re-enabled the proxy. But since you are not using it, it is recommended to empty the whitelist (set it to a blank value) to disable it.

Q: I have a custom widget and it is using the proxy. What should I do?

The upgrade system will have re-enabled the proxy, so your widget will continue to function as normal. However, it is recommended you modify the whitelist to whitelist the specific API(s) used by your widget.

Alternatively, if your APIs are CORS enabled, you can modify your widget code to call the API directly instead of using the proxy. If you do that, then you can disable the proxy (set the whitelist to a blank value).

Setting the legacy proxy whitelist

This is a hidden setting that can only be modified by the API. Here, we'll use cURL as an example to demonstrate calling the API to set the whitelist.

1. You need to create an API key from Admin > Apps > API Keys. You must enable the "use administrator endpoints" option.

2. Enter a list of URLs, one per line, on this URL encoder tool. Your URLs may end with an asterisk to represent a wildcard, or you may delimit a line with /slashes/ to represent a regular expression. Examples:

https://api.example.com/*
/^https?:\/\/api\.example\.com\/(some|other)/.*?$/
https://api.example.com/this/exact/api

Click the "Encode" button on the tool to encode the string in a way we can send to the API next.

3. Call the API like this:

curl -X POST -H "X-Deskpro-Api-Key: 123:xxx" \
    -d "value=xxx" \
    "http://your-deskpro-url/api/settings/values/agent.legacy_proxy_whitelist"

(Replace the "123:xxx" part with your API key, and the  "value=XXX" part with the encoded value you got in the previous step.)

You can verify the value by performing a GET request:

curl -H "X-Deskpro-Api-Key: 123:xxx" \
    "http://your-deskpro-url/api/settings/values/agent.legacy_proxy_whitelist"