Description

As with any security implementation, you should develop a plan for what needs to be controlled and who needs to have access. Access can be given to individual userids or groups. In many cases, confluence-administrators is likely one such group to whom you provide access. Also, review Macro Security Managed Macros to understand what elements can be controlled.

Use Cases

There are two use cases:

Steps for Use Case #1

1. Install the Macro Security for Confluence add-on.
2. Do not enable security from the add-on's configuration page.
3. Create and edit a macro-security.properties file that allows only the access you have planned.
   
   • Go to a convenient location in Confluence and add the file as an attachment. Using an attachment is convenient as it is automatically versioned by Confluence for future reference and change control.
   • The file can be named differently if needed.
   • See Example Configurations to review some sample configuration files you may wish to use as a starting point.
   • See Key Concepts to learn how the the properties file Use Restrictions and Parameter Restrictions work.
4. Go to the add-ons configuration page and:
   
   1. Provide the name of the properties file you added as an attachment to a Confluence page, using the syntax of space:page^filename and then click Load to load that properties file.
   2. Select the Enable checkbox and then click Save to enable security.
5. Install one of the add-ons that you've configured to be restricted in the properties file.
6. Create a test page to verify that if the proper page restrictions are not added, then the page shows the appropriate error on display.
7. Repeat steps 6-7 for each add-on that needs to be installed.

Steps for Use Case #2

Care must be taken to avoid errors on pages that no longer conform to the security requirements.

1. Install the Macro Security for Confluence add-on.
2. Do not enable security from the add-on's configuration page. 
3. Create and edit a macro-security.properties file that allows all access for the macros you use – in essence, not implementing any restrictions. 
   
   • Go to a convenient location in Confluence and add the file as an attachment. Using an attachment is convenient as it is automatically versioned by Confluence for future reference and change control.
   • The file can be named differently if needed.
   • See Example Configurations to review some sample configuration files you may wish to use as a starting point.
   • See Key Concepts to learn how the the properties file Use Restrictions and Parameter Restrictions work.
4. Go to the add-ons configuration page and:
   1. Provide the name of the properties file you added as an attachment to a Confluence page, using the syntax of space:page^filename and then click Load to load that properties file.
   2. Select the Enable checkbox and then click Save to enable security.
5. Using some of your existing pages that use macros that implement Macro Security, verify they continue to work as before.
6. Identify one of the macros you want to restrict.
7. Find pages that use that macro.
8. Apply "edit" page restrictions to those pages to only allow groups that are supposed to have access to the macro.
9. Edit the macro-security.properties file to restrict that specific macro, save your changes, and upload it to the Confluence page to which you previously attached it.
10. Re-load the properties file from the add-on's configuration page to make the configuration active.
11. Verify pages continue to work as before.
12. Create a test page to verify that if the proper page restrictions are not added, then the page shows the appropriate error on display.
13. Repeat steps 7-13 for each macro you want to restrict.

Trusted Spaces Approach

A new option is available that may apply in some Use Cases. See Macro Security for Trusted Spaces for more details.

Configuration Tips

• Set less specific values first, then more specific.
• Use generics to set parameter values if necessary. Example: sql.datasource.* = confluence-administrators.
• Use *ANY to not restrict a specific setting. Example: run = *ANY.
  
• Set a value for every macro that can be controlled (for instance, a value of *ANY). Lack of a value normally means it is not authorized.

• If a page containing a restricted macro will be viewed or updated by a user using remote REST APIs, including an account used for automation purposes, that Macro Security configuration must give that user authorization to use that restricted macro.

   

Communicating your configuration to users

It is a best practice to create a page for your Confluence user community that documents how you've configured Macro Security. This guides them as to the "edit" page restrictions they must add to any page that will be using a restricted macro, and what spaces you've configured to use Macro Security for Trusted Spaces.