Introduction

Setting up a Content Security Policy (CSP) is crucial for securing your Immich instance. CSP protects against various types of attacks such as Cross-Site Scripting (XSS) by controlling which resources can be loaded or executed by your site. However, Immich requires some inline scripts to function properly, and blocking these might prevent the app from loading.

This guide will walk you through configuring a secure CSP while ensuring that Immich loads without errors.

Note: This assumes you already have your site setup and accessible via NPM with SSL certs etc functioning.

Step-by-Step Guide

1. Access NGINX Proxy Manager

• Log in to your NGINX Proxy Manager (NPM) interface.
• Select the domain you are using to host Immich (e.g., https://immich.yourdomain.com).

2. Add Custom NGINX Configuration

• Go to the Custom Domains tab for your Immich proxy host.
• If you haven't already, define a "/" location pointing to the same host and port you have on the "Details" tab.
• Select the gear/cog next to the location field.
• Here, you will add the CSP configuration.

3. Define the Security Headers

Copy and paste the following configuration to include all the necessary security headers for Immich (replacing "immich.yourdomain.com" with your immich server domain:

# Enforce HTTPS and prevent downgrade attacks
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

# Protect against cross-site scripting and clickjacking attacks
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;

# Prevent referrer leakage to third parties
add_header Referrer-Policy "no-referrer-when-downgrade" always;

# Control access to browser features
add_header Permissions-Policy "geolocation=(), microphone=(), camera=()" always;

# Content Security Policy (CSP) to prevent XSS and data injection attacks
add_header Content-Security-Policy "default-src 'self'; script-src 'self' https://immich.yourdomain.com https://static.immich.cloud https://tiles.immich.cloud 'sha256-h5wSYKWbmHcoYTdkHNNguMswVNCphpvwW+uxooXhF/Y=' 'sha256-MK9u9tTzYnMIn9JSYcvLuwDDlo6Oevw1wdQBWB8TGys='; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' https://immich.yourdomain.com https://tiles.immich.cloud https://static.immich.cloud; frame-ancestors 'self'; worker-src 'self' blob:;" always;

# Upcoming Headers Configuration
add_header Cross-Origin-Embedder-Policy "require-corp" always;
add_header Cross-Origin-Opener-Policy "same-origin" always;
add_header Cross-Origin-Resource-Policy "same-origin" always;

Explanation of Headers:

• Strict-Transport-Security: Forces browsers to use HTTPS and prevents protocol downgrades.
• X-Frame-Options: Prevents clickjacking by only allowing your site to be framed by the same origin.
• X-Content-Type-Options: Prevents MIME type sniffing.
• Referrer-Policy: Controls how much referrer information is sent to third-party sites.
• Permissions-Policy: Controls access to specific browser features like geolocation and camera.
• Content-Security-Policy: This defines what resources are allowed. It permits scripts and resources from the same origin ('self') and inline scripts by their SHA-256 hashes.
• Cross-Origin-Embedder-Policy: Blocks embedding of cross-origin resources unless explicitly marked safe, reducing cross-origin data leak risks.
• Cross-Origin-Opener-Policy: Ensures only same-origin documents can share browsing contexts, mitigating cross-origin attack risks.
• Cross-Origin-Resource-Policy: Restricts access to resources to same-origin documents only, preventing unauthorized cross-origin access.

4. Identify Additional Script Hashes (If Needed)

• After applying the CSP, load your Immich instance.

• Open your browser’s Developer Tools (F12 or right-click > Inspect) and go to the Console tab.

• If there are CSP violations, they will show up in the console with a message like this:

  Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self' https://immich.yourdomain.com". Either the 'unsafe-inline' keyword, a hash ('sha256-<hash>'), or a nonce ('nonce-...') is required to enable inline execution.
  

• Copy the hash provided (e.g., 'sha256-<hash>').

• Add the new hash to the script-src directive in your CSP. For example:

  script-src 'self' https://immich.yourdomain.com 'sha256-h5wSYKWbmHcoYTdkHNNguMswVNCphpvwW+uxooXhF/Y=' 'sha256-MK9u9tTzYnMIn9JSYcvLuwDDlo6Oevw1wdQBWB8TGys=' 'sha256-<your-new-hash>';

• Repeat this process for all required hashes.

5. Test Your Site

• After updating the CSP, reload Immich and ensure everything works.
• Recheck the Console tab in the Developer Tools for any errors.
• You can also test your headers using an online tool like SecurityHeaders.com or CSP Evaluator.

6. Save Your Configuration

• Once you’ve confirmed Immich is working and the security headers are properly applied, save the configuration in NGINX Proxy Manager.

Troubleshooting

• Blocked Inline Scripts: If you encounter blocked inline scripts, the error messages in the Console will provide the SHA-256 hash you need to add to the script-src directive.

• Blocked External Resources: If external resources like fonts, images, or APIs are blocked, adjust your CSP to explicitly allow those domains. For example, to allow loading fonts from a CDN:

  font-src 'self' https://cdn.fonts.com;

Conclusion

By configuring these security headers, you protect your Immich instance from various web vulnerabilities such as XSS, clickjacking, and more. Keep refining your CSP by reviewing the Console for violations and adding new hashes as necessary.

Remember to test your CSP regularly and maintain a balance between security and functionality.

This should now give you a working immich server, with an A+ report card on https://securityheaders.com/