The RestrictedWikiPlugin is part of the NeWikiPlugin package. It is an abstract class (not an actual plugin) that adds the ability to restrict usage of WikiPlugins that extend this class, enabling, disabling or permitting 'open-wiki', asserted and/or authenticated use. This is done via configuration in the JSPWiki properties file, where to restrict the use of a specific plugin the property name consists of the prefix "restrict-" plus the fully-qualified package name of the plugin. The property value is one of the following (in the order of increasing restriction):

• "enabled" : If the value is 'enabled', the plugin is always enabled. This is recommended for plugins that have no security implications
• "open-wiki" : If the value is 'open-wiki', the plugin is enabled if the 'open-wiki' flag is true, regardless of a user's authentication state. See OpenWikiPlugin
• "asserted" : If the value is 'asserted', the plugin is enabled if the user is asserted
• "authenticated" : If the value is 'authenticated', the plugin is enabled if the user is authenticated
• "authenticated+open-wiki" : If the value is 'authenticated+open-wiki', the plugin is enabled if the user is authenticated AND the 'open-wiki' flag is true. This is more restrictive than either 'authenticated' OR 'open-wiki'
• "disabled" : If the value is 'disabled', the plugin is always disabled

Because the default behaviour when unconfigured is 'disabled', if you wish to permit unlimited use of a restricted plugin you must include it in the JSPWiki configuration with a setting of 'enabled'.

Usage#

All subclasses should call checkRestrictions(WikiContext) at the beginning of a try loop. If the check indicates that the restrictions on the plugin have not been met it will throw a RestrictedPluginException whose HTML error message can be returned to the user (i.e., as HTML markup on the wiki page). You should include a catch() for the try that calls the exception's RestrictedPluginException.getHTML() method, returning that as the result. E.g.,

   try {
       checkRestrictions(context);
       ...
   } catch ( RestrictedPluginException rpe ) {
       return rpe.getHTML();
   } catch ( Exception e ) {
       return ...;
   }

Failures due to plugin restrictions are considered as warnings, not errors, and therefore use the 'banner_warning' Banner Style.

Initialisation#

When any installed RestrictedWikiPlugin calls the superclass method WikiPlugin.execute(WikiContext, Map) for a first time, this grabs the WikiEngine from the WikiContext via the plugin's WikiPlugin.execute(WikiContext, Map) method, iterates through the properties whose name begins with "restrict-", and caches the map. No modification of this map can occur after it has been created (this may also be considered a security feature, as a disabled plugin cannot subsequently be enabled by changing the wiki's property set).

Example:#

With a property file containing:

restrict-org.apache.wiki.plugin.RestrictedEnabledTestPlugin=enabled
restrict-org.apache.wiki.plugin.RestrictedOpenWikiTestPlugin=open-wiki
restrict-org.apache.wiki.plugin.RestrictedAssertedTestPlugin=asserted
restrict-org.apache.wiki.plugin.RestrictedAuthenticatedTestPlugin=authenticated
restrict-org.apache.wiki.plugin.RestrictedAuthenticatedOpenWikiTestPlugin=authenticated+open-wiki
restrict-org.apache.wiki.plugin.RestrictedDisabledTestPlugin=disabled

and 'open-wiki' set as:

JSPWiki : RestrictedWikiPlugin - Plugin insertion failed: Could not find plugin OpenWikiJSPWiki : RestrictedWikiPlugin - Plugin insertion failed: Could not find plugin OpenWiki

the set of test plugins produces varying results depending on the aforementioned configuration and the authentication state of the user:

! RestrictedEnabledTestPlugin
[{RestrictedEnabledTestPlugin}]
----
! RestrictedOpenWikiTestPlugin
[{RestrictedOpenWikiTestPlugin}]
----
! RestrictedAssertedTestPlugin
[{RestrictedAssertedTestPlugin}]
----
! RestrictedAuthenticatedTestPlugin
[{RestrictedAuthenticatedTestPlugin}]
----
!  RestrictedAuthenticatedOpenWikiTestPlugin
[{RestrictedAuthenticatedOpenWikiTestPlugin}]
----
! RestrictedDisabledTestPlugin
[{RestrictedDisabledTestPlugin}]
----

(these are disabled on this wiki since the plugins have not been installed)