This documentation is aimed at developers. It covers instructions to get Velocity template rendering to function correctly with the new Anti-XSS mechanism, as some Confluence 3.x plugins may have their content double encoded.
This mode will engage certain behaviours in Confluence intended to reduce the incidence of cross site scripting (XSS) vulnerabilities. At present this mode enables an automatic data encoding strategy designed to reduce XSS exploits arising from the incorrect encoding of data embedded in HTML templates. This mechanism does not encode HTML output that plugins generate outside of Velocity templates.
Many of the past XSS vulnerabilities in Confluence have arisen simply because data from untrusted sources have not been encoded correctly when mixed with other HTML in Velocity templates. Such encoding failures lead to possible HTML injection attacks that can range from breaking page rendering, to hijacking user sessions. These security vulnerabilities will always be easily introduced when template authors have to make a conscious decision to specifically encode untrusted data when rendered. Other disadvantages of this opt-in security include a proliferation of noise in templates related directly to encoding operations ( et al) and a general obscuration of where data are being written unsafely to the client. Confluence uses a new rendering mode where all data is HTML encoded by default unless steps are taken explicitly to avoid this behaviour in templates.
The table below explains how to apply XSS protection and how your plugin will behave.
Effect of protection
Anti-XSS protection for plugins.
HTML encoding of Velocity templates is enforced for plugins.
Confluence Admin setting 'Enforce Anti-XSS for plugins' in the 'Security Configuration' screen (default is on).
Plugin opts in. Plugin chooses to enforce Anti-XSS
Keeps Anti-XSS encoding of plugin template's output even if Confluence administrator turns off Anti-XSS protection for plugins.
Plugin opts out.
Useful when you encounter compatibility issues. Template output is not HTML encoded. If opting out, your plugin needs to be HTML encoding all the user-supplied data. It is recommended to update the plugin so that it is compatible with the new setting.
The table below shows how and when HTML encoding of templates is applied for plugins.
'Enforce Anti-XSS for plugins' setting
Plugin opts in. See Enabling XSS Protection in Plugins.
Plugin opts out. See Enabling XSS Protection in Plugins.
Plugin takes no action.
Key: Yes = HTML encoding is applied. No = No HTML encoding.
NOTE: When taking no action, your plugin may no longer work correctly because it encounters double HTML encoding of output. See the following paragraphs for ways of addressing this. It is recommended to always opt in.