User guide

The HTML Macro for Confluence app allows you to incorporate snippets of HTML into your page. These can include HTML, JavaScript, and CSS, which runs inside the macro itself but does not affect the rest of the page.

1 Quick start 2 Security considerations 2.1 Sanitize HTML option 2.2 X-Frame-Options Response Header 3 Development Considerations 4 Related articles 5 Additional references

1 Quick start 2 Security considerations 2.1 Sanitize HTML option 2.2 X-Frame-Options Response Header 3 Development Considerations 4 Related articles 5 Additional references

Quick start

Insert the HTML Macro into your page and click Insert.
Deselect the Sanitize checkbox to insert JavaScript. See the Security Considerations section for more information. The macro is rendered in one or two levels of iframes. Therefore, you cannot interact with the DOM of the parent and must be familiar with the same-origin policy if you are using advanced client-side code.
Specify the height for your macro or you can leave it blank.
Add your HTML to the box that's now inserted on your page.
Review the macro or use the Preview window in the macro editor.

Security considerations

Sanitize HTML option

When using the Sanitize option in the app’s configuration page and the Sanitize box in the macro is checked, only safe HTML is allowed (i.e., no JavaScript is allowed). This option will load slightly faster.

Deselecting the Sanitize option allows JavaScript in the body of the HTML Macro. However, in this case, a second or double iframe is used from a different domain. This sandboxing insulates the content from the parent Confluence page, which prevents interaction with the parent page DOM and increases safety. Any Cloud app that does not operate in this sandboxed manner is not be inherently safe as JavaScript could make REST calls back to Confluence as the present user. This is prevented from occurring with the sandbox double iframe and a different domain to add more security.

Sandboxing helps mitigate the most dangerous aspects of JavaScript running in your macro but you need to be aware that unchecking Sanitize adds risk. Despite the insulation of the extra iframe, this enables certain classes of stored XSS attacks (for example, phishing for credentials in a fake login panel), so, you need to trust your site users to use the macro responsibly.

When Sanitize is deselected, the macro can execute JavaScript, and AJAX requests can be made from your code in the HTML macro body. The sandbox iframe does not add any CORS-related headers. However, AJAX requests to services you do not control may contain CORS response headers that prevent you from using them within the sandbox iframe.

The JavaScript is limited as to what it can do because we “sandbox” the unsanitized macro in an extra iframe. It cannot spoof the target user to obtain their Confluence access token or make changes to any content outside the sandboxed macro. There are still some potential attacks. It would be impossible to list all of these, but examples would be a user adding a pop-up or phishing for user information. Because of how Javascript works, there is no way to prevent these attacks by a malicious user already in the system. Therefore, unsanitized mode should only be enabled when users are trusted not to exploit it. If you are concerned about protecting your instance from these attacks you can limit the users that can access/edit the page to Admins or other trusted groups.

X-Frame-Options Response Header

If you try to include an iframe in an HTML macro, it will not work if the server for the source (src) of the iframe sets the X-Frame-Options response header to DENY or SAMEORIGIN (https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options). The browser console may display: "Refused to display 'https://www.mysite.com' in a frame because it set 'X-Frame-Options' to 'SAMEORIGIN."

The X-Frame-Options header value of SAMEORIGIN only allows content to be embedded in an iframe if the content is from the same origin as the page containing the iframe. The DENY value will disallow it from any origin.

When a server returns the X-Frame-Options response header, the server has explicitly set a content security policy that limits its content rendering in an iframe, which the browser is honoring. It is a browser security issue that Appfire cannot control or bypass.

If you control the remote domain that is serving the source of the iframe, you can disable this setting on that server or you could build a proxy for that domain that strips the header. Many sites do not want to show up in iframes for Intellectual Property (IP) or security reasons.

Development Considerations

When developing JavaScript or other code to add to this app, please note that it is running in an iframe inside the macro AND an iframe on the Confluence page. The innermost iframe is served from our app domain and not from Atlassian. For instance, if you create an HTML form and submit it, you will likely get a response from our domain indicating that it is "Not authenticated."