CSP Configuration

Predictive DocV Web SDK CSP Configuration

When integrating the Predictive Document Verification (DocV) Web SDK, it is essential to properly configure your Content Security Policy (CSP) to ensure the security of your application. The CSP header controls which resources can be loaded and executed by the browser, preventing potential security vulnerabilities like cross-site scripting (XSS) attacks. The DocV Web SDK requires specific domains to be whitelisted for scripts, styles, and other resources to function properly.

This section provides a guide on configuring the CSP header to comply with the DocV Web SDK's requirements, along with an example configuration that you can tailor to your environment.

Required CSP directives

Below are the necessary CSP directives to allow the DocV Web SDK to function properly:

1. connect-src: Controls which locations can be connected to via script interfaces (for example, XMLHttpRequest, WebSocket).

   • Required values:

     • https://verify-v2.socure.com
     • https://stepup.socure.com

2. script-src: Restricts which scripts can be executed. Use dynamic nonce values to allow only specific inline scripts.

   • Required values:
     • 'nonce-${nonce}'

3. style-src: Restricts where styles can be loaded from. Similar to script-src, it supports the use of dynamic nonce values.

   • Required values:

     • https://verify-v2.socure.com
     • https://fonts.googleapis.com
     • 'nonce-${nonce}'

4. img-src: Limits where images can be loaded from, including blob: and data: URLs when necessary.

   • Required values:
     • blob: data:

5. font-src: Defines where fonts can be loaded from.

   • Required values:

     • https://fonts.gstatic.com
     • https://verify-v2.socure.com

Example CSP header

Below is an example of a CSP header configuration that satisfies the requirements for integrating the DocV Web SDk. This configuration includes whitelisting the necessary domains for scripts, styles, fonts, and other resources.

const cspHeader = `
    default-src 'self';
    connect-src 'self' https://verify-v2.socure.com https://stepup.socure.com;
    script-src 'self' 'nonce-${nonce}';
    style-src 'self' https://verify-v2.socure.com https://fonts.googleapis.com 'nonce-${nonce}';
    img-src 'self' blob: data:;
    font-src 'self' https://fonts.gstatic.com https://verify-v2.socure.com;
`;

Explanation of key parts

• script-src: This directive allows loading scripts from 'self' (your own domain) and requires a nonce to be dynamically generated and applied to the inline scripts to ensure they are trusted. For non-production environments, you may also allow 'unsafe-eval' for development purposes, though this should be avoided in production.
• style-src: This allows styles from 'self', Google Fonts, and the DocV Web SDK's domain. As with script-src, a nonce is used to allow inline styles in a secure way.
• img-src: This allows images from your own domain, as well as blob: and data: URIs, which may be necessary depending on how images are handled in your application.
• connect-src: This allows connections to your own domain and the necessary DocV Web SDK endpoints at https://verify-v2.socure.com and https://stepup.socure.com.

Handling nonce generation

It is crucial to ensure that the nonce values are dynamically generated for each request to prevent reuse and mitigate attacks. This can be handled server-side and passed to the frontend scripts. Below is an example of generating a nonce in Node.js:

const crypto = require('crypto');
const nonce = crypto.randomBytes(16).toString('base64');

You should inject this nonce value into your CSP header and into the relevant inline scripts and styles for proper CSP enforcement.

Passing the nonce to the <script> tag

When dynamically loading the DocV Web SDK using a nonce, it is essential to pass the nonce value to the <script> tag to ensure it complies with the CSP policy. Below are examples of how to do this in both Vanilla JavaScript and Next.js.

Vanilla JavaScript example

In a Vanilla JavaScript environment, you can use a standard <script> tag with the nonce attribute as shown below:

<script nonce="${nonce}" src="https://websdk.socure.com/bundle.js"></script>

Ensure that the nonce is dynamically generated and injected into the <script> tag from your server-side logic. This guarantees that only trusted scripts are executed in compliance with the CSP.

Next.js example

In Next.js, the <Script> component can be used to load the DocV Web SDK dynamically. The nonce attribute is passed to ensure CSP compliance, and you can use event handlers like onLoad and onError for additional script management.

import Script from 'next/script';

function MyComponent({ nonce }) {
  const handleScriptLoad = () => {
    console.log('Script loaded successfully.');
  };

  return (
    <Script
      src="https://websdk.socure.com/bundle.js"
      strategy="afterInteractive"
      nonce={nonce}
      onLoad={handleScriptLoad}
      onError={(e) => console.error("Script load error", e)}
    />
  );
}

Conclusion

Configuring the CSP correctly is essential for secure integration of the DocV Web SDK. Make sure to tailor the provided CSP header example to match your application’s specific needs while following best security practices.

For further information on CSP, refer to the MDN Web Docs on CSP.

If using Next.js, see Configuring: Content Security Policy.