abstract class %CSP.WhitelistUtils

Whitelist facility to selectively restrict web access to [ZenMethod] calls. The whitelist in question is namespace specific. This allows system administrators to configure the visibility of system level calls based upon from whence the call originated.

The whitelist is checked when a callback first attempts to call either an instance or class method that has previously been compiled with a [ZenMethod] tag. This check is only done when the request comes in from the client, purely internal invocations of the methods are not restricted.

If whitelisting is enabled for the namespace, for a given method to be called, it must be enabled in the whitelist. Methods that are explicitly disabled or simply not listed in the whitelist are rejected and an exception is thrown

How to Set-up and Enable Whitelisting:

The call
Do ##class(%CSP.WhitelistUtils).%InitializeWhitelist()
will scan the current namespace for all defined or inherited [ZenMethod] functions. Each function discovered will be added to the whitelist and enabled by default (this is done for backwards compatibility). If a previous whitelist has been defined, this call will reinitialize it. The newly minted whitelist will not yet be active (and if whitelisting was previsously active, it will be turned off until the new list has been approved. Note: Depending on the size and complexity of the class dictionary in the current namespace, this method may take several seconds to complete

The default initial list may be edited using the following two routines:

Do ##class(%CSP.WhitelistUtils).%EnableMethod(myClass,myMethod)
Do ##class(%CSP.WhitelistUtils).%DisableMethod(myClass,myMethod)

The first adds or edits a given entry, approving it for general access. The second explicitly bars web applications from calling the method in question.

To approve the current whitelist for use and start enforcing the new policy, call:
Do ##class(%CSP.WhitelistUtils).%ActivateWhitelist()

To temporarily disable whitelisting without reconfiguring the whitelist itself, call:
Do ##class(%CSP.WhitelistUtils).%DeactivateWhitelist()

To see if whitelisting is active for the namespace, call:
Write ##class(%CSP.WhitelistUtils).%IsWhitelistEnabled()

To query the individual entries of the whitelist, call:
Write ##class(%CSP.WhitelistUtils).%IsMethodEnabled(myClass,myMethod)

Attempts to create, edit or change the activity status of the whitelist require Admin_Secure:USE privilege. Queries to inspect the whitelist or its status are not so restricted.


Parameters Properties Methods Queries Indices ForeignKeys Triggers


%ActivateWhitelist %DeactivateWhitelist %DisableMethod %EnableMethod
%InitializeWhitelist %IsMethodEnabled %IsWhitelistEnabled


classmethod %ActivateWhitelist() as %Status
Turn on the use of the whitelist for the current namespace. When activated, all web callbacks to zenMethods will be tested against the whitelist. Any method that is either missing or set to false (0) will be disallowed. Methods set to true (1) in the whitelist will be allowed to execute according to normal role and privilege restrictions.
classmethod %DeactivateWhitelist() as %Status
Turn off (but do not otherwise alter) the use of the whitelist for the current namespace. When deactivated, all web callbacks to zenMethods will be permitted according to normal role and privilege restrictions.
classmethod %DisableMethod(pClass As %String, pMethod As %String) as %Status
Tag a given member of the whitelist as false (meaning do not execute). The entry remains in the whitelist.
classmethod %EnableMethod(pClass As %String, pMethod As %String) as %Status
Tag a given member of the whitelist as true (meaning ok to execute). When the whitelist is active, a method must both appear in the whitelist and be set to true in order for the method to be called from a web access point.
classmethod %InitializeWhitelist() as %Status
This method identifies (and tags as approved) all methods tagged as ZenMethod callbacks in the current namespace. This data is used to build the initial whitelist. This list may then be edited (using the methods found here) as needed. This call does NOT activate the use of the whitelist. That is done by a separate call (%ActivateWhitelist) once the whitelist has been configured to the site administrators' satisfaction.
If a previous version of the whitelist was in place, this call will overwrite its settings in favor of a fresh scan and will mark the list as inactive pending approval.
classmethod %IsMethodEnabled(pClass As %String, pMethod As %String) as %Boolean
Test to see if the given method call should be allowed under the current whitelist policy
classmethod %IsWhitelistEnabled() as %Boolean
Test to see if whitelist checking is enabled for this namespace
Copyright © 1997-2020 InterSystems Corporation, Cambridge, MA