%CSP.WhitelistUtils
abstract class %CSP.WhitelistUtils [ Final ]
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 callDo ##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.
Method Inventory
- %ActivateWhitelist()
- %DeactivateWhitelist()
- %DisableMethod()
- %EnableMethod()
- %InitializeWhitelist()
- %IsMethodEnabled()
- %IsWhitelistEnabled()
Methods
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.
Tag a given member of the whitelist as false (meaning do not execute).
The entry remains in the whitelist.
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.
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.
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