Using Reftagger with a Content Security Policy


Introduction

Content Security Policy (CSP) is a standard providing defense against certain types of injection-based attacks. It specifies where a Web application is allowed to load resources from. This guide provides different approaches for using Reftagger alongside a CSP.


Option 1: Use a nonce

By default, Reftagger will inject a <style> element containing CSS styles into the page it runs on. This presents some challenges with a CSP enabled. One solution is to use a nonce. The nonce should be an unguessable, random value generated by the server and should be unique to each request.

Set the nonce value on the inline script element containing the Reftagger initialization code:

<!-- Page content here -->

<script nonce="{SERVER-GENERATED-NONCE}">
	var refTagger = {
		settings: {
			// ... Reftagger settings here ...
		}
	};
	// ... Reftagger initialization code here ...
</script>

Make sure you have the latest initialization code that supports the nonce attribute.

Supply the nonce from the server in the CSP:

script-src 'nonce-{SERVER-GENERATED-NONCE}' api.reftagger.com reftagger.bibliacdn.com; style-src 'nonce-{SERVER-GENERATED-NONCE}'; img-src api.reftagger.com;

Reftagger will propagate the nonce to the inline style element it generates.


Option 2: Use the external Reftagger stylesheet

An alternative approach is to use Reftagger’s disableInlineCss setting. When set, Reftagger will not inject a <style> element into the page. Instead, the page must reference the external Reftagger stylesheet.

Place the Reftagger initialization code in a JavaScript file and set disableInlineCss to true:

// RefTaggerInit.js

var refTagger = {
	settings: {
		disableInlineCss: true,
		// ... Other Reftagger settings here ...
	}
};
// ... Reftagger initialization code here ...

Load the script at the end of the page’s <body>:

<body>
	<!-- Page content here -->

	<script type="text/javascript" src="RefTaggerInit.js"></script>
</body>

In the page’s <head>, reference the Reftagger stylesheet:

<head>
	<link rel="stylesheet" type="text/css" href="https://api.reftagger.com/v2/RefTagger.css">
</head>

Finally, update your CSP with the following directives:

script-src 'self' api.reftagger.com reftagger.bibliacdn.com; style-src api.reftagger.com; img-src api.reftagger.com;

NOTE: When using disableInlineCss, the customStyle setting is disabled. Custom styles can still be achieved by manually creating CSS rules that overwrite the default Reftagger styles. For example:

<head>
	<link rel="stylesheet" type="text/css" href="https://api.reftagger.com/v2/RefTagger.css">
	<!-- Create a new stylesheet that overrides the desired Reftagger styles -->
	<link rel="stylesheet" type="text/css" href="RefTaggerCustomStyle.css">
</head>

Option 3: Use unsafe-inline

The last approach is to specify 'unsafe-inline' in the style-src directive of the CSP. This option should only be used if the previous approaches are not feasible and the security implications are understood.

Place the Reftagger initialization code in a JavaScript file:

// RefTaggerInit.js

var refTagger = {
	settings: {
		// ... Reftagger settings here ...
	}
};
// ... Reftagger initialization code here ...

Load the script at the end of the page’s <body>:

<body>
	<!-- Page content here -->

	<script type="text/javascript" src="RefTaggerInit.js"></script>
</body>

Finally, update your CSP with the following directives:

script-src 'self' api.reftagger.com reftagger.bibliacdn.com; style-src 'unsafe-inline'; img-src api.reftagger.com;