Key Concepts - 4.x

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 app 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.

Macro Security works with macros from Bob Swift Atlassian apps and user macros, as well as other macros whose providers have implemented Macro Security support. Please refer to the Macro Security Managed Macros page for a list of Bob Swift Atlassian apps that support Macro Security.

How does Macro Security work?

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

• Trusted Users and Groups
• Trusted Spaces
  

Trusted Users and Groups

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

  

In the example above,

• The configuration 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 restrictions that matches all or part of the SQL macro's configuration on the app configuration screen. 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 ensures that the "edit" page restrictions are consistent with what is configured in the app configuration screen. 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 renders an error instead of the expected output.
  
• Since any of the following "edit" page restrictions are consistent with the configuration, Macro Security only allows the SQL macro to be rendered to the following:
  • A user who is a member of the confluence-administrators group
  • Bob
   If "edit" page restrictions are inconsistent with the app configuration or users and/or groups have not been permitted to use, the SQL macro renders an error instead of the expected output.

Trusted Spaces

An easier way to manage who is trusted to use a macro safely is to configure the app 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. For example:

In the example above,

• The app configuration screen indicates that only content in the space having a space key = ds (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 apps configuration screen.
  
• When content is being rendered, the restricted macro ensures 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 renders with an error instead of the expected output.
  
• Since any of the following content is consistent with the configuration, Macro Security allows the SQL macro to be rendered to users permitted to view content in the Demonstration Space.
  

Trusted Users, Groups and Spaces

You can combine trusted users and groups AND trusted spaces for maximum flexibility in controlling how macro usage should be restricted. For example, any of the following are valid ways to specify a macro configuration entry in the app:

What must I do to start using Macro Security?

The app 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.

Please note the following:

• 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.
  
  

• 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 configuration 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, you can define an "edit" restriction for a userid that is either a trusted user or a member of a trusted group.