Skip to content

Security

Infrastructure security

We recommend the following infrastructure security measures:

  • Disable the demo site with the FACEAPI_ENABLE_DEMO_WEB_APP="false" environment variable to avoid unnecessary worker utilization for serving site content and to reduce potential security risks caused by frontend vulnerabilities.
  • Do not expose the service unless necessary. Access to the backend should be provided only via private networking.
  • Use HTTPS where possible.
  • Use firewalls and limit incoming connections to applications using firewalls, security groups, and rules so that only verified and authorized consumers (VMs/services) can access them.
  • Place a load balancer in front of the service. This makes security configuration simpler and more flexible. Although it is possible to terminate SSL connections and configure security-specific headers in a FaceAPI container, the container should focus on processing requests. Transport-level security concerns should be handled by the load balancer.
  • Implement authorization, for example via nginx and a plugin.

HTTPS

Below is an example configuration for a Docker deployment, but it can be easily adapted to all supported platforms.

Run nginx as a front-end container to handle HTTPS and proxy requests to the backend FaceAPI container.

For reference, see the docker-compose.yml file and the nginx default.conf file. You can use default.conf as a basis for your nginx.conf file.

Basic authentication

To enable authentication for the Face SDK Web Service, use a reverse proxy. This section provides an example of a basic nginx configuration with Basic authentication.

Before you begin, ensure you have the following files placed in a single directory:

  • docker-compose.yml
  • nginx.conf — an nginx configuration file
  • .htpasswd — a file containing usernames and passwords
  • regula.license — a valid license file

1. Create the docker-compose.yml file with the following content:

version: "3.9"

services:
  faceapi:
    image: regulaforensics/face-api:latest
    volumes:
      - ./regula.license:/app/extBin/unix/regula.license
  nginx:
    image: nginx:alpine
    ports:
      - "8000:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./.htpasswd:/etc/nginx/.htpasswd
    depends_on:
      - faceapi

2. Configure the nginx.conf file to include Basic authentication:

events {
}
http {
  server {
    listen 80;

    location / {
       proxy_pass http://faceapi:41101;
       auth_basic "FaceAPI authentication";
       auth_basic_user_file /etc/nginx/.htpasswd;
    }
  }
}

3. Create the .htpasswd file by executing the command below:

printf "USER:$(openssl passwd -apr1 PASSWORD)\n" >> .htpasswd

Replace USER with the required username and PASSWORD with the required password. You can run the command multiple times to create multiple users.

4. Ensure that the regula.license file is valid and active.

5. Run the following command to start the Face SDK Web Service with authentication through the reverse proxy and nginx:

docker compose up -d

Your Face instance is now protected with Basic authentication through the reverse proxy. Access it through the configured reverse proxy URL, and you will be prompted to enter the username and password from the .htpasswd file.

Enabling mTLS

To enable mutual TLS (mTLS) for the Face SDK Web Service, configure nginx as a reverse proxy that terminates TLS, validates client certificates, and forwards requests to the FaceAPI container.

You will need the following files:

  • docker-compose.yml
  • nginx.conf — an nginx configuration file
  • ./certs — a directory with mTLS certificate files
  • regula.license — a valid license file

1. Create a docker-compose.yml file:

version: "3.9"

services:
  faceapi:
    image: regulaforensics/face-api:latest
    volumes:
      - ./regula.license:/app/extBin/unix/regula.license

  nginx:
    image: nginx:alpine
    ports:
      - "8443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs
    depends_on:
      - faceapi

2. Configure the nginx.conf file to enable mTLS:

events {}

http {
  server {
    listen 443 ssl;

    ssl_certificate /etc/nginx/certs/server.crt;
    ssl_certificate_key /etc/nginx/certs/server.key;

    ssl_client_certificate /etc/nginx/certs/ca.crt;
    ssl_verify_client on;

    location / {
       proxy_pass http://faceapi:41101;
    }
  }
}

If the Liveness feature is enabled, you may need to increase the client_max_body_size parameter in the nginx configuration to allow larger request bodies.

3. Run the following command to start the configuration:

docker compose up -d

4. To verify the setup, send a request:

Without a client certificate

curl -k https://localhost:8443/api/healthz

Expected response:

<html>
<head><title>400 No required SSL certificate was sent</title></head>
<body>
<center><h1>400 Bad Request</h1></center>
<center>No required SSL certificate was sent</center>
<hr><center>nginx/1.29.7</center>
</body>
</html>

With a client certificate

curl -k https://localhost:8443/api/healthz \
  --cert certs/client.crt \
  --key certs/client.key

Expected response:

{"app":"Regula Face Recognition Web API", ... "ctx":{"userIp":"172.23.0.3"}}

Option 2. FaceAPI via HTTPS

Note that mTLS is not configured on the Web Service side. If mutual TLS is required, it must be configured at the reverse proxy or load balancer level.

To run the FaceAPI service over HTTPS:

  1. Set 644 permissions on the certificate files so the server can read them.
  2. Mount the cert.crt and cert.key files into the container.
  3. Set the FACEAPI_CERT_FILE and FACEAPI_KEY_FILE environment variables.
  4. Map the container port to port 8443 on the host.
chmod 644 ~/cert.crt ~/cert.key

docker run -it -p 8443:41101 -v ~/regula.license:/app/extBin/unix/regula.license -v ~/cert.crt:/app/cert.crt -v ~/cert.key:/app/cert.key -e FACEAPI_CERT_FILE="/app/cert.crt" -e FACEAPI_KEY_FILE="/app/cert.key" regulaforensics/face-api