Most widgets access resources on the DTP server, but some widgets display information from other servers. Modern browsers, however, do not allow widgets to make requests to external servers because doing so may affect security.

You can enable widgets to display information from external resources by whitelisting hosts on the [INSTALL DIR]/conf/ExternalApiWhitelist.xml file. This allows widgets to make requests to a DTP service that retrieves the external resource and returns the content to the widget.

The whitelist affects the following widgets:

For these widgets to work, the hosts that the widgets access must be included in the whitelist file:

1. Open the [INSTALL DIR]/conf/ExternalApiWhitelist.xml file in an editor. and add an entry for each host referenced in the widgets according to the following schema:
    

   <external-api-whitelist>
   <host>host1.companyname.com</host>
   <host>host2.companyname.com</host>
   </external-api-whitelist>

2. Save the file. You do not need to restart DTP services.

Entries in the file are host names, not full URLs. The resource URLs can use any port number, can use either HTTP or HTTPS, and can use any path. You will not need to manually specify the path after a host name and port for most widgets. For example, all of the following URLs would be allowed if you added the host alpha.companyname.com to the whitelist:

http://alpha.companyname.com/a

https://alpha.companyname.com/b

http://alpha.companyname.com:8080/x?y=z

https://alpha.companyname.com:9091/path/to/something?param=22

The URL http://alpha/path?x=y would not be allowed in this example, even if the DTP server resolves alpha and alpha.companyname.com to the same IP address. To access a resource by referring to the host simply as "alpha", you would need to add <host>alpha</host> to the whitelist file.

Policy Center Whitelisting

The Gate Summary widget that facilitates integration with Policy Center also accesses external resources and is indirectly affected by whitelisting. To use this widget, you do not need to add the host name for the Policy Center server to ExternalApiWhitelist.xml. Instead, DTP will allow the host specified for Policy Center in the [install dir]/conf/PolicyCenterConfig.xml file (see Connecting to Policy Center).

Upgrading to DTP 5.2.3

Prior to version 5.2.3, DTP placed no restrictions on which servers were allowed when getting external resources, but whitelisting will be enforced after upgrading to DTP 5.2.3.

To minimize disruption to your use of existing widgets, the ExternalApiWhitelist.xml file will automatically be populated with the host names used by existing widgets during the 5.2.3 upgrade process. After upgrading, you should review the ExternalApiWhitelist.xml file and delete any unnecessary entries.

DTP will not auto-populate the whitelist or synchronize the whitelist with widget configurations after the initial upgrade process finishes, so you should make sure to modify the whitelist as necessary.