This page describes how Confluence Add-on developers can easily add code so that its macros implement Macro Security.
Adding the Code
The following code should be placed so that it is executed before each macro within the add-on returns rendered data. In general, it will be placed at the start of the macro logic. If there are any parameter restrictions that the macro will implement, the code for them should be placed just after any parameter handling logic. This snippet is unlikely to require changes to support new versions of Confluence.
In the code below, the name of the add-on's macro is "restricted", which has one parameter ("myRestrictedParameterName") for which a Parameter Restriction is supported. You would substitute the name of your macro and its parameter, of course.
import com.atlassian.renderer.v2.SubRenderer;
...
String securityMessage = subRenderer.render("{macro-security:restricted}", pageContext, RenderMode.suppress(RenderMode.F_FIRST_PARA));
...
if (!securityMessage.equals("")) { // Macro Security is reporting an error due to a Use Restriction
throw MacroExecutionException(securityMessage);
}
...
if (!parameterValue.equals("")) {
securityMessage = subRenderer.render("{macro-security:restricted|parameter=myRestrictedParameterName}",
pageContext, RenderMode.suppress(RenderMode.F_FIRST_PARA));
if (!securityMessage.equals("")) { // Macro Security is reporting an error due to a Parameter Restriction
throw MacroExecutionException(securityMessage);
}
}
| Line | Description |
|---|---|
| 1 | This package must be imported. |
| 3 | This invokes the Macro Security macro, passing it "restricted" as the name of the macro. It returns either a null string or an error string into the variable securityMessage. |
| 5-6 | If an error was returned by Macro Security, it is thrown here and you would skip additional processing (thus preventing the macro from rendering its usual output). |
| 9-16 | These lines are used to validate each parameter for which a Parameter Restriction is needed. As noted above, these would be placed just after any parameter handling logic. If a value was specified for the parameter, it invokes the Macro Security macro, passing it "restricted" as the name of the macro and "myRestrictedParameterName" as the name of the parameter. If an error was returned by Macro Security, it is thrown here and you would skip additional processing (thus preventing the macro from rendering its usual output). |
How your customers use Macro Security with your add-on
To use your add-on's new Macro Security capability, your customer's Confluence Administrators must:
- Install your add-on
- Install the Macro Security add-on
- Configure and enable Macro Security, including adding a Use Restriction entry and (optionally) any number of Parameter Restriction entries for your add-on's macros.
- Ensure the appropriate restrictions are in place, as described in Understanding How Macro Security Works:
- If using Trusted Users and Groups, the appropriate "edit" page restriction(s) are in place on content using your restricted macros.
- If using Trusted Spaces, the appropriate space-level permissions are in place to ensure that only trusted users and groups can edit content in the space.
