Additional configuration

Configuration guides for implementations in special environments.

Preloading Selphi and SelphID resources

The package @facephi/sdk-web-wc exports the utilities generateSelphiBrowserCache and generateSelphIDBrowserCache to download the resources of the Selphi and SelphID engines in the browser before that <facephi-sdk-provider> is mounted in the DOM.

If called in advance, they can reduce the perceived loading time when the user starts the biometric flow, since the widget assets will already be available in the browser cache.

They must be called before after integrating the SDK Provider into the page. If the provider is already in the DOM, this step provides no benefit.

import {
  generateSelphiBrowserCache,
  generateSelphIDBrowserCache,
} from '@facephi/sdk-web-wc';

// Download resources before mounting the SDK Provider
await generateSelphiBrowserCache(process.env.FACEPHI_SDK_APIKEY);
await generateSelphIDBrowserCache(process.env.FACEPHI_SDK_APIKEY);

Parameters:

• apiKey (string): ApiKey with license for the corresponding widget.

• engineLocation (string, optional): Custom path for the engine resources.

For more details, see the documentation for each utility in generateSelphiBrowserCache and generateSelphIDBrowserCache.

---

Content Security Policy (CSP)

If your application uses strict CSP headers, you must explicitly allow the origins that the SDK Web and the biometric widgets need (scripts, workers, media and APIs).

Apply these directives on the server of your application. Facephi servers already operate with CORS; there is no need to replicate these headers on them.

Recommended policy:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'unsafe-eval' 'unsafe-inline' blob: https://widget-components.facephi.pro;
  media-src 'self' blob:;
  worker-src 'self' blob:;
  connect-src 'self' https://widget-components.facephi.pro https://sdk-web.facephi.pro https://sdk-web-services.facephi.pro https://api.identity-platform.io https://license.identity-platform.io;

Directive	What it enables
default-src 'self'	Same-origin resources only by default
script-src	Own scripts, SDK initialization, blob: and resources from widget-components.facephi.pro
media-src	Camera/microphone capture and playback (blob:)
worker-src	Web Workers generated in memory by the SDK (blob:)
connect-src	Biometric APIs, licenses, and Identity Platform

If it appears "Refused to create a worker from 'blob:…'", add blob: to worker-src (or child-src in older browsers).

Additional headers (configure on the same server or proxy):

Header	Value
Permissions-Policy	camera=self, microphone=self
Referrer-Policy	strict-origin-when-cross-origin
X-Content-Type-Options	nosniff
Cross-Origin-Embedder-Policy	require-corp
Cross-Origin-Opener-Policy	same-origin
Cross-Origin-Resource-Policy	same-origin

Validate the configuration in staging before production. If you only need to enable the SDK CDN:

script-src 'self' https://sdk-web.facephi.pro;
connect-src 'self' https://sdk-web.facephi.pro;

---

Integration in native applications via WebView

• You can use the SDK within a native application through a WebView using the website integration of your Facephi SDK provider. We recommend customizing the User-Agent of your WebView by adding a custom token instead of completely replacing the UA.

User-Agent examples

• ❌ Incorrect example:

  Code

  sdkwebview

• ✅ Correct example (Android):

  Code

  Mozilla/5.0 (Linux; Android 13; Pixel 7) AppleWebKit/537.36 (KHTML, como Gecko) Chrome/115.0.0.0 Mobile Safari/537.36 sdkwebview

• ✅ Correct example (iOS):

  Code

  Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 como Mac OS X) AppleWebKit/605.1.15 (KHTML, como Gecko) Mobile/15E148 sdkwebview

Notes

• The base User-Agent can reflect the minimum compatible device/OS; the last token must be sdkwebview.

• For iOS applications developed with Swift and Storyboards, enable inline playback in WKWebView (Inline Playback / allowsInlineMediaPlayback = true).

---

Proxy Configuration Guide

This guide provides ready-to-use examples for a forward proxy. The example will be done with Nginx, but it can be done with the technology of your choice.

Route Table

Endpoint	Protocol	URL
/licensing	https	https://license.identity-platform.io
/tracking	https	https://idv-ing-proxy.eu.idv-suite.com
/qr	wss	https://sdk-web-services.facephi.pro
/identification	wss	https://video-identification.eu.idv-suite.com
/resources	https	https://widget-components.facephi.pro/
/auth	https	https://idv-ing-proxy.eu.idv-suite.com

The proxy must remove the base path and forward the request to the destination endpoint, preserving the remaining URL path.

Facephi will be responsible for providing the necessary URLs in each case.

License Service

This licensing service requires the HTTP engine to act as a forward proxy to an external HTTPS backend, setting the correct SNI for the destination server and forwarding the original request headers while replacing the Host header with the destination server's hostname. It will be the integrator's responsibility to issue the CORS policies.

location /licensing {
    proxy_pass https://license.identity-platform.io/;  
    proxy_ssl_server_name on;
    proxy_pass_request_headers on;
    proxy_set_header Host license.identity-platform.io;

    # Hide backend CORS headers to avoid duplicates
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Methods;
    proxy_hide_header Access-Control-Allow-Headers;
    proxy_hide_header Access-Control-Allow-Credentials;

    # CORS controlled only from Nginx
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
    add_header 'Access-Control-Allow-Headers' '*' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;

    # Handling OPTIONS preflight
    if ($request_method = OPTIONS) {
        return 204;
    }
}

---

Tracking Service (Tracking)

This tracking service requires the HTTP engine to act as a forward proxy to an external HTTPS backend, setting the correct SNI for the destination server and forwarding the original request headers while replacing the Host header with the destination server's hostname. It will be the integrator's responsibility to issue the CORS policies.

location /tracking/ {
    proxy_pass https://api.identity-platform.io/;
    proxy_ssl_server_name on;
    proxy_pass_request_headers on;
    proxy_set_header Host api.identity-platform.io;

    # Hide backend CORS headers (avoid duplicates)
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Methods;
    proxy_hide_header Access-Control-Allow-Headers;
    proxy_hide_header Access-Control-Allow-Credentials;

    # CORS: Adjust the origin according to your frontend
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
    add_header 'Access-Control-Allow-Headers' '*' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;

    # Preflight (OPTIONS)
    if ($request_method = OPTIONS) {
        return 204;
    }
}

---

QR Service

This QR service requires the HTTP engine to act as a forward proxy to an external WebSocket backend, setting the correct SNI for the destination server and forwarding the essential proxy headers while replacing the Host header with the destination server's hostname. The engine must be configured to support HTTP/1.1 protocol upgrades, preserving the Upgrade and Connection headers to enable WebSocket connectivity. CORS policy must be defined by the integrator according to their security requirements, and the proxy must expose specific response headers such as Content-Length and Content-Range to allow client-side access to this information.

location /qr {
    proxy_pass https://sdk-web-services.facephi.pro/;
    
    # Specific WebSocket configuration
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    
    # Standard headers
    proxy_set_header Host ws.example.com;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # CORS for WebSockets (optional)
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
    add_header 'Access-Control-Allow-Headers' '*' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;
}

WebSocket requirements:

• proxy_http_version 1.1 is mandatory

• The headers Upgrade and Connection are necessary for the handshake

---

Video Recording Service

This video recording service requires the HTTP engine to act as a reverse proxy to an external WebSocket backend for real-time video identification. The engine must be configured to support HTTP/1.1 protocol upgrades, preserving the Upgrade and Connection headers to enable WebSocket connectivity. Extended timeouts are configured to keep persistent connections alive during video sessions. The CORS policy must be defined by the integrator according to their security requirements.

location /identification {
    proxy_pass https://video-identification.eu.idv-suite.com;
    proxy_ssl_server_name on;

    # Specific WebSocket configuration
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";

    # Standard headers
    proxy_set_header Host FACEPHI_INTERNAL_URL;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # WebSocket timeout (keep the connection alive)
    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;

    # CORS for WebSockets
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
    add_header 'Access-Control-Allow-Headers' '*' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range' always;
    
    # Handling OPTIONS preflight
    if ($request_method = OPTIONS) {
        return 204;
    }
}

WebSocket requirements:

• proxy_http_version 1.1 is mandatory

• The headers Upgrade and Connection are necessary for the handshake

---

Resources Service

This resources service requires the HTTP engine to act as a reverse proxy to an external HTTPS backend, setting the correct SNI for the destination server and forwarding the original request headers, replacing the Host header with the destination server's hostname. It will be the integrator's responsibility to define the CORS policies.

location /resources/ {
    proxy_pass https://widget-components.facephi.pro/;
    proxy_ssl_server_name on;
    proxy_pass_request_headers on;
    proxy_set_header Host widget-components.facephi.pro/;

    # Hide backend CORS headers (avoid duplicates)
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Methods;
    proxy_hide_header Access-Control-Allow-Headers;
    proxy_hide_header Access-Control-Allow-Credentials;
    
    # CORS: adjust the origin according to your frontend
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
    add_header 'Access-Control-Allow-Headers' '*' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;

    # Preflight (OPTIONS)
    if ($request_method = OPTIONS) {
        return 204;
    }
}

---

API Authentication Service

This authentication service requires the HTTP engine to act as a reverse proxy to an external HTTPS backend, setting the correct SNI for the destination server and forwarding the original request headers, replacing the Host header with the destination server's hostname. It will be the integrator's responsibility to define the CORS policies.

location /auth/ {
    proxy_pass https://idv-ing-proxy.eu.idv-suite.com;
    proxy_ssl_server_name on;
    proxy_pass_request_headers on;
    proxy_set_header Host idv-ing-proxy.eu.idv-suite.com;

    # Hide backend CORS headers to avoid duplicates
    proxy_hide_header Access-Control-Allow-Origin;
    proxy_hide_header Access-Control-Allow-Methods;
    proxy_hide_header Access-Control-Allow-Headers;
    proxy_hide_header Access-Control-Allow-Credentials;

    # CORS controlled only from Nginx
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
    add_header 'Access-Control-Allow-Headers' '*' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;

    # Handling OPTIONS preflight
    if ($request_method = OPTIONS) {
        return 204;
    }
}

---

Configuration Notes

🔀 Behavior of proxy_pass

The trailing slash (trailing slash) is important:

# WITH trailing slash: rewrites the path
location /api {
    proxy_pass https://backend.com/;
    # /api/users -> https://backend.com/users
}

# WITHOUT trailing slash: preserves the full path
location /api {
    proxy_pass https://backend.com;
    # /api/users -> https://backend.com/api/users
}

🌐 CORS

• Adjustment Access-Control-Allow-Origin to your specific domain.

• You can use * in development, but NEVER in production with credentials.

• proxy_hide_header prevents conflicts when the backend already sends CORS headers.

📝 Common Headers

• proxy_set_header Host $host; # Requested domain

• proxy_set_header X-Real-IP $remote_addr; # Client IP

• proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # IP chain

• proxy_set_header X-Forwarded-Proto $scheme; # http or https

---

Useful commands

Validate the configuration nginx -t

Reload the configuration (without downtime) nginx -s reload

View the error logs tail -f /var/log/nginx/error.log

View the access logs tail -f /var/log/nginx/access.log

Restart Nginx systemctl restart nginx # or service nginx restart

---

Next steps

• Configure the Components and modules according to your needs.

• Explore the Integration examples.

• Review the specific sections of each module such as Selphi, SelphID or Video Recording.