How macro security works

This tutorial explains with examples how macro security restrictions with page restrictions and macro parameters (Allow script execution and Allow same origin) can be used to implement granular control over the HTML content to be rendered.

To implement macro security, the following actions must be taken:

1. Provide required restrictions or note trusted resources (space/user/group) in the app’s Macro security configuration.

2. Provide similar restrictions to the page(s) with the HTML macro.

3. Set Allow script execution and/or Allow same origin macro parameters as required.

Trusted users/groups

First, you must identify a set of users and/or groups who can use a macro safely. Next, you must configure the app appropriately and ensure that each page using that macro has edit page restrictions matching those specified in the app configuration screen.

Consider an example where you have added the following restriction:

• Users: bob

• Group: confluence-administrators

With the example above:

• Members of the confluence-administrators group and bob user are trusted to use the macro.

• Any content in any space that uses the macro must have page restrictions that matches all or part of the app configuration. This means that page restrictions must be in place ensuring that only those trusted users and groups can add or edit the macro.

• When content is being rendered, the restricted macro ensures that the page restrictions are consistent with the app configuration. If not or if any other groups or users are referenced in the page restrictions, this "breaches" the configuration and the macro renders an error instead of the expected output.

• If the following page restrictions are consistent with the configuration, macro security only allows the macro to be rendered to the following:

  • A member of the confluence-administrators group

  • User bob 

Trusted spaces

An easier way to manage macro security is to indicate that all pages in a specific space are trusted. With this approach, page restrictions are not needed. Instead, the Confluence administrator and/or space administrator must provide the appropriate space-level permissions to ensure only trusted users and groups can edit content in that space.

Consider a scenario where you have added the following macro access:

• A space with space key DEMO

In the example above:

• Only DEMO space is trusted to use the macro.

• Any content that uses the macro must reside in the DEMO space since this matches the app's configuration.

• 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 macro, this "breaches" the configuration. The restricted macro displays an error instead of the expected output.

• If page restrictions are consistent with the app configuration, macro security allows the macro to be rendered to users permitted to view content in the specified space.

Combining trusted spaces with users and user groups

You can combine trusted users and groups and trusted spaces for maximum flexibility to control how macro usage is to be restricted. Using the example mentioned previously, all of the following are valid ways to specify a macro configuration entry in the app:

• Members of the confluence-administrators group are trusted to use the macro as long as matching edit page restrictions are in place on each page that uses the macro.

• User bob is trusted to use the macro as long as matching edit page restrictions are in place on each page using the macro.

• Content in the space with the DEMO space key can use the macro and members of the confluence-administrators group and the user bob are trusted.

Points to note

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

• For trusted users and groups: Content currently using a restricted macro must have edit page restrictions applied so that only trusted users and groups (as referenced in the configuration) can edit it. The edit page restrictions must match (by name) at least one of the trusted groups or user IDs and no other users or groups can be permitted to edit the page. You can, however, define an edit restriction for a user ID that is either a trusted user or a member of a trusted group.

Examples

In this section, let’s consider a few configurations and how macro security affects the content to be rendered.

For the purpose of these examples, let’s assume that the global Allow JavaScript parameter is disabled.

Allow script execution usage (Recommended)

To restrict script access or to allow only trusted users/groups to render content:

1. Ensure that Allow JavaScript in the app’s Global configuration (Settings > HTML Configuration) is off.

2. Open Macro security in HTML Configuration and select Add restriction.

3. Select HTML in Macro and Allow script access in Parameter. Click Add restriction to complete the macro security configuration.

   Open

   

   Note that in the image, a trusted user - Test Automation {Appfire} was added. This implies that only this user can use the HTML macro to render content and can execute scripts.

4. Go to the required page and add or edit an HTML macro.

5. Select Allow script execution in the macro editor and either, directly add the content to be rendered, or specify the location of the HTML content. Click Save once done.

6. Publish the page.

The combination of the macro security settings, the page restrictions and macro parameters allows the HTML content to be rendered.

Allow same origin usage (Recommended)

To allow the user to execute scripts to access cookies and Confluence APIs or to allow only trusted users/groups to render content:

1. Ensure that Allow JavaScript in the app’s Global configuration (Settings > HTML Configuration) is off.

2. Open Macro security in HTML Configuration and select Add restriction.

3. Select HTML in Macro and Allow same origin in Parameter. Click Add restriction to complete the macro security configuration. For reference, use the image in point 3 of the previous section.
   Note that you can add trusted space(s)/user(s)/group(s) at this point. You must ensure that the page restrictions match these settings.

4. Go to the required page and add page restrictions with the same trusted user/group as specified in the macro security configuration.

5. Add or edit an HTML macro.

6. Select Allow same origin in the macro editor and either directly add the content to be rendered, or specify the location of the HTML content. Click Save once done.

7. Publish the page.

Your content is rendered as expected and the scripts can access the Confluence APIs.

Troubleshoot possible warnings and errors

Let’s look at some scenarios where warnings are generated and content is not rendered.

Insufficient access permissions warning

This warning is displayed when the macro security configuration and page restrictions do not match. A simple example of this scenario is as follows:

1. Ensure that Allow JavaScript in the app’s Global configuration (Settings > HTML Configuration) is off.

2. For this example, let’s not add any restrictions in the Macro security tab.

3. Go to the required page. For this case, you may have different or no page restrictions.

4. Add or edit an HTML macro.

5. Select Allow script execution in the macro editor and either directly add the content to be rendered, or specify the location of the HTML content. Click Save once done.

6. Publish the page.

Once the page is published, the Insufficient access permissions warning is displayed. To resolve this situation, ensure that:

• The the global configuration Allow JavaScript parameter is enabled.

• The macro security settings and page restrictions match.

• The relevant macro parameters are selected.

Unexpected error or similar errors

Consider a scenario where you have configured the macro security appropriately and added the right page restrictions. But if the relevant macro parameter is not enabled as configured in macro security, an error is displayed. Depending on the referred HTML content, for example, a Tableau script generates an Unexpected error if something goes wrong.

In this case, ensure that the relevant macro parameter is enabled.