Content Security Policy Enhancements: A How-to Guide

What is Content Security Policy?

Content Security Policy (CSP) is essentially a set of instructions sent from a website to a user's browser. Its main use case is defending against cross-site scripting (XSS) by telling the browser what resources a webpage is allowed to load. "Resources" are assets like JavaScript, images, or styles. If something breaks the CSP rules, it is blocked from loading and will cause a “CSP violation.” These violations can be viewed in browser Developer Tools (DevTools).

CSP can be in “enforced” mode, where the browser obeys its instructions, and/or Report Only mode, where the browser does not obey but will still show the violations these instructions would have caused.

How does Content Security Policy in RapidIdentity work now?

RapidIdentity’s CSP configuration is under Configuration → General → Settings → Web Security. Rules have two components: a path regular expression and one or more values. The path specifies the page(s) the rules will be applied to, and the value contains the instructions that will be sent to the browser for the page(s).

If CSP instructions are not specified, then it does not provide protection; and the current CSP configuration is minimal and does not cover the XSS use case. However, a strong CSP could easily break customers’ login/logout page customizations and RESTPoints that serve HTML. Furthermore, it is easy to lock oneself out of RapidIdentity by misconfiguring CSP, which makes it difficult to test more secure rules.

How will Content Security Policy work after the enhancements?

The enhancements are, at this time of writing, beginning to facilitate more seamless implementation of secure CSP rules. Support for Report Only mode has been added, giving CSP rules a third component: a checkbox to toggle Report Only mode on and off for each rule (pictured below). The CSP for the login and logout pages has also been enhanced to address XSS. For existing tenants, the rules for these pages are in Report Only mode to avoid breaking existing customizations.

These enhancements provide ways to maintain customizations and test stronger CSP while avoiding breakages. Breakages are still possible, but the ability to switch between Report Only and enforced makes avoiding and fixing them a much smoother experience with comparatively little to no downtime for regular users of the pages being configured.

Recommendations and Pitfalls to Avoid

Refer to this document particularly if you are transitioning CSP rules from Report Only to enforced, as well as when performing tasks involving CSP with respect to login/logout customizations and RESTPoints.

• With the enhancements, the basic workflow is:

  • Begin with a CSP rule (existing or new) in Report Only mode

  • Look for any violations in DevTools and through interacting with the UI

  • Remedy the violations

  • Switch the CSP rule to enforced mode when none are left

• RapidIdentity goes over the rules from top to bottom, applying them based on order. To determine which rule(s) will be applied to a given page, do the following:

  • Start at the top and work your way down, reading only the rules with Report Only unchecked. The first rule with a matching path will be used for that page’s enforced CSP.

  • Start at the top and work your way down, reading only the rules with Report Only checked. The first rule with a matching path will be used for that page’s Report Only CSP.

  • To then verify what CSP was sent when visiting a page, filter by document/“Doc” or “HTML” in the Network tab of DevTools and look for Content-Security-Policy and Content-Security-Policy-Report-Only headers. Below is an example of what this can look like in Chrome.

• If configuring CSP related to login, double check that logging in still works after switching it to enforced mode. Do not log out of your existing session in case it doesn’t.

  • For example, a misconfigured path regex can cause breakage. If the login page path was changed to /idp.*, it will affect more than just the login page and could prevent logging in as a whole from working.

  • For similar reasons, be careful with CSP for paths that the Web Security configuration UI itself falls under. Report Only rules for paths like this are safe to use, but enforced ones can lead to lockout.

• For each rule, only specify one entry under “Values.” More than one value will lead to confusing behavior.

• Some CSP violations may require interaction with the UI to see them. Do not account for only the violations provided when the page is initially loaded.

  • Example: a rule containing form-action ‘none’; would break the login page but this only becomes apparent after trying to submit the login form. The resulting violation is shown below; it only appeared after trying to log in.

• Note that an enforced rule and a Report Only rule can be applied to the same webpage at the same time.

  • This allows testing out a new, stronger rule in Report Only mode while preserving the protections provided by the page’s original enforced CSP rule.

• Per OWASP recommendations, frame-ancestors ‘none’; needs to be in the CSP for all API responses. If a specific RESTPoint has a valid use case requiring a value other than ‘none’, configure a rule accordingly for only that RESTPoint.

• For a deeper understanding of CSP in RapidIdentity:

  • Review the following Recommended Readings:

    • OWASP CSP Cheat Sheet

    • Content-Security-Policy Quick Reference Guide

    • MDN CSP Overview

    • Deploying CSP in Single Page Applications

  • See the following tutorial on how to interpret and fix common CSP violations caused by Web Template customizations.