Confluence security consists of global permissions, space permissions and page restrictions that are used to control who can view, edit or delete content. The Macro Security add-on builds upon Confluence's security to support restrictions on macros as well. Macros can be included within Confluence content (pages, blog posts and comments), with any given piece of content using restricted macros, unrestricted macros, or a combination of each.

The Macro Security for Confluence add-on works with macros from Bob Swift Atlassian add-ons and user macros, as well as other macros whose providers have implemented Macro Security support. Please refer to the Macro Security managed macro page for a list of Bob Swift Atlassian add-ons that support Macro Security.

How does it work?

Macro Security works by Confluence administrators defining how they want to restrict the usage of macros that have implemented Macro Security support. This is done through a properties file, which supports 2 types of configuration possibilities:

1. Trusted Users and Groups
2. Trusted Spaces
   

Trusted Users and Groups

If you have identified a set of users and/or groups that are trusted to use a macro safely, then you configure the properties file appropriately and then ensure that each page using that macro has "edit" page restrictions that match what was specified in the properties file.

In the example above,

• The properties file indicates that members of the group "confluence-administrators" and the user "bob" are trusted to use the SQL macro.
• Any content in any space that uses the SQL macro must have an "edit" page restriction that matches all or part of the SQL macro's configuration in the properties file. This means that "edit" page restrictions must be in place, thereby ensuring that only those trusted users and groups can add or edit the SQL macro.
  
• When content is being rendered, the restricted macro will ensure that the "edit" page restrictions are consistent with what is configured in the properties file. If not, or if any other groups or users are referenced in the "edit" page restrictions, then this "breaches" the Macro Security configuration and so the SQL macro will render an error instead of the expected output.
  
• Since any of the following "edit" page restrictions are consistent with the properties file, Macro Security will allow the SQL macro to be rendered:
  • confluence-administrators
  • bob
  • confluence administrators AND bob
  • a user who is a member of confluence-administrators
   
• Each of the following "edit" page restrictions are inconsistent with the properties file, so the SQL macro will render an error instead of the expected output:
  • <no "edit" page restrictions
  • confluence-users
  • joe (who is not a member of confluence-administrators)
  • confluence-administrators AND confluence-users
  • confluence-administrators AND joe
    
  • bob AND joe
  • confluence-administrators AND bob AND joe
  • confluence-administrators AND bob AND confluence-users
    
    If content using a SQL macro also contains an unrestricted macro, the unrestricted macro will render even if (due to the conditions) the restricted macro renders with an error.
    

Trusted Spaces

An easier way to manage who is trusted to use a macro safely is to configure the properties file to indicate any page in a specified space is trusted. With this approach, no "edit" page restrictions are needed. Instead, the Confluence Administrator and/or Space Administrator is responsible for ensuring that the appropriate space-level permissions are in place to ensure only trusted users and groups can edit content in that space. This means that only trusted users and groups should have the following space-level permissions: add page, add blog, and add comments.

In the example above,

• The properties file indicates that only content in the space having a space key = DEMO (the Demonstration space) is trusted to use the SQL macro.
• Any content that uses the SQL macro must reside in the Demonstration space since this matches the SQL macro's configuration in the properties file.
  
• When content is being rendered, the restricted macro will ensure that the content is in the "trusted" space. (It does not validate space-level permissions (or page restrictions), as that is the responsibility of the Confluence Administrator and/or Space Administrator.) If content in any other space uses the SQL macro, then this "breaches" the Macro Security configuration and so the restricted macro will render with an error instead of the expected output.
  
• Since any of the following content is consistent with the properties file, Macro Security will allow the SQL macro to be rendered:
  • content in the Demonstration space
    
   
• Each of the following are inconsistent with the properties file, so the SQL macro will render an error instead of the expected output:
  • content in the Company News space (space key = NEWS)
    content in any other space besides the Demonstration space (space key = DEMO)
    
    If content using a SQL macro also contains an unrestricted macro, the unrestricted macro will render even if (due to the conditions) the restricted macro will not render.

What must I do to start using Macro Security?

A properties file must be configured by a Confluence Administrator to define which supported macros should have restricted use and who (or what spaces) should still be allowed to create content with a restricted macro.

The properties file can be loaded from any file location on the server that is hosting Confluence, or as an attachment on a Confluence page. If the latter approach is used, the page with the attached properties file should be editable only by a Confluence Administrator.

Before the properties file should be put into effect by loading it and enabling Macro Security via an admin screen, other actions must be taken:

1. When using Trusted Spaces, each space must have space-level permissions applied so that only trusted users and groups can add pages, blogs or comments. Since "edit" page restrictions are not needed, this provides the easiest way to control who can use a restricted macro.
   
   

2. When using Trusted Users and Groups, content that presently uses a restricted macro should have "edit" page restrictions applied so that only trusted users and groups (as referenced in the properties file for that macro) can edit it. The "edit" page restrictions must match (by name) at least one of the trusted groups or userids, and no other users or groups can be permitted to edit the page. Note, however, that you can define an "edit" restriction for a userid if that userid is either a trusted user or is a member of a trusted group.

Once the above actions are done, the Confluence Administrator can go to the add-on's configuration screen to load the properties file and enable Macro Security.