Appearance

Guidance for Content Security Policies (CSPs) ​

INFO

New to CSPs? Skip to CSP Basics for an introduction.

If you are using Privy in a web client environment, we recommend setting a strict Content Security Policy (CSP) as a defense-in-depth strategy to mitigate XSS, clickjacking, and cross-site leak vulnerabilities.

Quick start ​

TIP

Remember to add your own domain to the relevant directives (e.g., add your domain to connect-src, script-src, etc.)

Base CSP configuration ​

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://challenges.cloudflare.com;
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: blob:;
  font-src 'self';
  object-src 'none';
  base-uri 'self';
  form-action 'self';
  frame-ancestors 'none';
  child-src https://auth.privy.io https://verify.walletconnect.com https://verify.walletconnect.org;
  frame-src https://auth.privy.io https://verify.walletconnect.com https://verify.walletconnect.org https://challenges.cloudflare.com;
  connect-src 'self' https://auth.privy.io wss://relay.walletconnect.com wss://relay.walletconnect.org wss://www.walletlink.org https://*.rpc.privy.systems;
  worker-src 'self';
  manifest-src 'self'

CSP recommendations ​

CSP directives for @privy-io/react-auth ​

As part of enforcing a CSP, you will need to allow certain trusted resources that your site needs to load as part of normal operation:

INFO

If you have a base domain enabled, you must also add your domain-specific Privy instance, e.g. https://privy.your-base-domain.com.

Required domains ​

Optional features ​

If your app uses Telegram login or linking, add:

If your app uses Privy's funding kit, add:

If your app is on Solana, please add the Solana cluster endpoints if an override is not provided:

Best practices ​

  1. Start strict: Begin with restrictive policies, and loosen only as needed. Document all exceptions.
  2. Test regularly: Test your CSP after dependency updates and validate during deployments. Check compatibility across different browsers.
  3. Monitor: Track violation reports and monitor performance impact. Watch for bypass attempts.
  4. Document changes and procedures: Record all CSP changes and document allowed sources. Document testing procedures for your app.

Testing and deployment ​

TIP

We highly recommend testing your CSP thoroughly before deploying and enforcing in production.

Test your CSP in a staging environment ​

Run through your standard user flows in a staging environment with CSP enforcement. This may mean connecting to browser extension wallets / mobile app wallets, transacting, logging out, etc.

It is possible that directives need to be updated after Privy SDK upgrades. Whenever upgrading the Privy SDK, always test your CSP again before deploying the update to production.

Other software you use, such as MetaMask, may document their own guidance on CSP usage.

Using Report-Only mode ​

Most browsers support a Content-Security-Policy-Report-Only header, which sends violation reports without actually enforcing policies. This allows the developer to judge whether a modification to their CSP will impact their site’s expected functionality.

If your policy is strict, you will see many reported violations due to extensions trying to inject scripts into the browser. This is completely normal. It's best to filter these out to avoid the noise.

Deployment ​

We recommend that you first deploy your CSP in report-only mode with the header Content-Security-Policy-Report-Only. Once it has been validated in production, you can migrate to Content-Security-Policy, which will enforce directive violations.

Going forward, you can deploy with both Content-Security-Policy-Report-Only and Content-Security-Policy headers set simultaneously. This will allow you to test on the report only header and A/B test against your existing policy.

Monitoring ​

We recommend that you configure the report-uri to see violation/enforcement reports and set up a monitoring dashboard so you can review reports.

CSP basics ​

A Content Security Policy (CSP) is a set of rules that tell the browser what sources of content are valid. CSPs help prevent the browser from executing malicious scripts. They can be used to increase the security of any website.

To enable a CSP, you need to configure your web server or backend application to return the Content-Security-Policy HTTP header. In that header, you specify a policy. A policy is described using a set of policy directives, each of which tells the browser what to do with respect to a given resource type.

Example: img-src directive ​

For example, the img-src directive tells the browser sources of images are valid. If you set this CSP header:

Content-Security-Policy: img-src https://my-website.com/

Then any <img> from other sites will be blocked:

<img src="https://bad-website.com/image.jpg"/>   {/* Error! This won't load! */}

Important directives ​

Policy directives tell the browser what to do for a given resource type.

  • Keep script-src as locked down as possible to prevent malicious code execution
  • Set frame-ancestors to none unless you expect your website to be embedded
  • Keep connect-src as locked down as possible to prevent unauthorized data exfiltration
  • Use child-src and frame-src to control iframe loading and execution
  • Consider worker-src if using web workers
  • Implement default-src as a fallback for unlisted directives

Read the following guides to learn more: ​