Overview
Content Security Policy (CSP) is a widely supported Web security standard intended to prevent certain types of injection-based attacks by giving developers control over the resources loaded by their applications. Use this guide to understand how to deploy UserGuiding on a site that uses a CSP.
TL;DR;
Below is the full list of CSP rules if you want to use all features of UserGuiding:
script-src: 'nonce-{SERVER-GENERATED-NONCE}'
connect-src: https://static.userguiding.com https://ug-client-img.s3.amazonaws.com https://api.userguiding.com https://nps.userguiding.com https://user.userguiding.com https://metrics.userguiding.com https://ls.userguiding.com
img-src: https://static.userguiding.com https://ug-client-img.s3.amazonaws.com
style-src: 'unsafe-inline'
Below you can find explanations and related UserGuiding features for each of the rules above;
Enabling the UserGuiding snippet
To use UserGuiding on a page with a Content Security Policy, the CSP must allow for the execution of the UserGuiding snippet, which is an inline JavaScript snippet that injects the container script. The recommended way to do this is with a nonce, which should be an unguessable, random value that the server generates individually for each response. Supply the nonce value in the Content-Security-Policy script-src directive:
script-src 'nonce-{SERVER-GENERATED-NONCE}'
Then use the nonce-aware version of the inline UserGuiding snippet, setting the nonce attribute on the inline script element to this same value:
<script nonce="{SERVER-GENERATED-NONCE}">
(function(g,u,i,d,e,s){g[e]=g[e]||[];var f=u.getElementsByTagName(i)[0];var k=u.createElement(i);k.async=true;k.src='https://static.userguiding.com/media/user-guiding-'+s+'-embedded.js';f.parentNode.insertBefore(k,f);if(g[d])return;var ug=g[d]={q:[]};ug.c=function(n){return function(){ug.q.push([n,arguments])};};var m=['previewGuide','finishPreview','track','identify','triggerNps','hideChecklist','launchChecklist'];for(var j=0;j<m.length;j+=1){ug[m[j]]=ug.c(m[j]);}})(window,document,'script','userGuiding','userGuidingLayer','701241238ID');
</script>
UserGuiding will then propagate the nonce to any scripts that it adds to the page.
If the recommended nonce approach is not feasible, it is possible to enable the UserGuiding inline script by adding the 'unsafe-inline' directive to the CSP's script-src section.
script-src https://static.userguiding.com 'unsafe-inline'
Enabling the use of UserGuiding UI components
We are using styled-components as our UI rendering library. Unfortunately, SC currently does not support client-side nonce and there should be unsafe-inline CSP rule provided in style-src directive.
style-src 'unsafe-inline'
Enabling the container status and analytics service
To make use of the UserGuiding analytics service on a page with a Content Security Policy, the CSP must allow for the connections to the following UserGuiding web servers. Supply the following value in the Content-Security-Policy connect-src directive:
connect-src: https://api.userguiding.com https://metrics.userguiding.com
Learn more about analytics service
Learn more about container status
Enabling the use of images in onboarding material
To use UserGuiding on a page with a Content Security Policy, the CSP must allow for the execution of the UserGuiding snippet, which is an inline JavaScript snippet that injects the container script. Supply the following values in the Content-Security-Policy img-src and connect-src directives:
img-src: https://static.userguiding.com ug-client-img.s3.amazonaws.com
connect-src: https://static.userguiding.com ug-client-img.s3.amazonaws.com
Enabling the use of NPS surveys
To use the PS survey product of UserGuiding, the CSP must allow for the connection to UserGuiding's PS back-end. This application acts as a rule engine and stores users' interactions with PS surveys. Supply the following values in the Content-Security-Policy connect-src directive:
connect-src: https://nps.userguiding.com
Learn more about PS surveys
Enabling the use of user identification service
To use the user identification service of UserGuiding, the CSP must allow for the connection to UserGuiding's persisted user storage back-end. This application acts as a rule engine and stores users' interactions with guides, hotspots, and checklists. Supply the following values in the Content-Security-Policy connect-src directive:
connect-src: https://user.userguiding.com
Learn more about user identification