Oz Liveness Web Adapter

System requirements

Any OS, supported by Docker, with Docker installed.
CPU: 4x cores
RAM: 8Gb
Disk: 40Gb

Additional requirements

nginx locally installed. Recommended configuration below.
Oz API and Oz Bio installed in your network cluster.
Domain name associated with current IP address.
SSL certificate associated with domain name.
Accessible external 443 port for HTTPS access.
All preparation and configuration steps will be performed under root user.

Step by step installation

Login to Docker Hub

Obtain your personal docker hub token to login to private repository.

                
  docker login -u ozcustomer -p your_token_here docker.io

Download and run latest image

                
  docker pull ozforensics/oz-webliveness

Prepare configuration files and directories

Directories

Create root directory for data somewhere in your system. Here and further we will assume default directory is /opt/oz.

                
  mkdir -p /opt/oz/web_adapter/session_data
  chown -R 33:33 /opt/oz/web_adapter/session_data

Warning! Please, pay attention to session_data directory, which could be infinitely grow, by 20-50Mb per analyze request. Optionally, you could change volume destination with different docker startup command:

Files

Create file /opt/oz/web_adapter/index.html with contents below. This is sample page with plugin usage, you may change content at production environment.

  
  <!DOCTYPE html>
    <html>
    <head>
        <title>Oz Liveness WEB Example</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <link rel="stylesheet" href="/plugin/ozliveness.css" />
        <script src="/plugin_liveness.php?lang=en"></script>
    </head>

    <body>
        <div>
            <h1>Example website</h1>
            <button id="example_button">Example button</button>
        </div>

        <script>
            document.getElementById('example_button').addEventListener('click', function()
            {
                OzLiveness.open({
                    lang: 'en',
                    action: ['photo_id_front', 'photo_id_back', 'video_selfie_zoom_in'],
                    on_complete: function(result)
                    {
                        console.log(result);
                    }
                });
            });
        </script>
    </body>
    </html>

Notes. You may change content of that file to simple redirector with text below. Never remove that file, because default version will be used from container. Also, if you want to replace this file with another, you will need to restart your container.


<html>
  <head>
      <meta http-equiv="refresh" content="1;URL={your domain}" />
 </head> 
</html>

Create file /opt/oz/web_adapter/app_config.json with sample settings below. Please, follow documentation.

                
  {
      "api_url": "https://api.oz-services.ru/api/",
      "api_token": "",
      "api_use_token": "client",
      "lang_allow": [ "ru", "en" ],
      "lang_default": "en",
      "video_actions_list":
      [
          "video_selfie_left",
          "video_selfie_right",
          "video_selfie_down",
          "video_selfie_high",
          "video_selfie_zoom_in",
          "video_selfie_zoom_out",
          "video_selfie_scan",
          "video_selfie_smile",
          "video_selfie_eyes",
          "video_selfie_blank"
      ],
      "photo_actions_list":
      [
          "photo_id_front",
          "photo_id_back",
          "photo_doc_custom"
      ],
      "actions_default_importance": false,
      "actions_default":
      {
          "video_count": 1,
          "photo_front": true,
          "photo_back": true
      },
      "analyses":
      {
          "quality": true,
          "biometry": true,
          "documents": true
      },
      "extract_best_shot": false,
      "delete_old_sessions": true,
      "delete_old_sessions_offset_minutes": 120,
      "result_mode": "status",
      "result_codes":
      {
      	"0-1": "Unable to save session configuration.",
      	"0-2": "Unable to load session configuration.",
      	"0-3": "Session configuration not found.",
      	"0-4": "Session id not found.",
      	"0-5": "Session remote user is not valid.",
      	"0-6": "Session is out of date.",
          "0-7": "API token not found.",

          "1-1": "Found no images for processing.",
      	  "1-2": "Found no valid data for processing.",
          "1-3": "Unable to create temp folder for uploaded images.",
          "1-4": "Image uploaded for processing must be a jpeg.",
      	  "1-5": "Unable to decode images for making video.",
          "1-6": "Unable to create video from images.",
          "1-7": "Analyse folder create curl error.",
          "1-8": "Analyse folder create internal error.",
          "1-9": "Unable to start video curl analyse.",
          "1-10": "Unable to start video internal analyse.",
          "1-11": "Init api request error - corrupted session configuration.",
          "1-12": "Quality analyse has not been started.",
          "1-13": "Analyse folder creation did not return a folder id.",
          "1-14": "Analyse is not started.",
          "1-15": "Media files not transmited to API.",
          "1-16": "Media files transmited with errors.",
          "1-17": "Not found any analyse to start.",
          "1-18": "Default actions not found.",
          "1-19": "Requested not valid action.",
          "1-20": "Requested not all actions.",

          "2-1": "Video analyse not started.",
          "2-2": "Video analyse error.",
          "2-3": "Video analyse folder id not found.",
          "2-4": "Video analyse id not found.",
          "2-5": "Analyse check curl error.",
          "2-6": "Analyse check internal error.",
          "2-7": "Analyse check returned an empty answer.",
          "2-8": "Analyse check did not found requested analyse result."
      }
  }

Run container

                
  docker run -d --name oz-webliveness --restart unless-stopped \
  -v /opt/oz/web_adapter/app_config.json:/var/www/html/core/app_config.json \
  -v /opt/oz/web_adapter/index.html:/var/www/html/index.html \
  -v /opt/oz/web_adapter/session_data:/var/www/html/core/session_data \
  -p 80:80 -d ozforensics/oz-webliveness

Additional instructions

Nginx host’s configuration example

Put next block in section server of your nginx.conf file.

                
  server {
    ....
    location / {
        client_max_body_size 100M;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Request-URI $request;
        proxy_set_header X-Original-Request $request_uri;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://localhost:80;
    }
  }

Test Web Adapter and Web Plugin

Prepare machine with Oz API installed and API login credentials. You need account with CLIENT_ADMIN role.
Set api_url parameter to “https://oz-api-domain-name/api/””.
Obtain temporary token with script below and set it to api_token parameter.
Set api_use_token to “config” value.
Restart container: docker restart oz-webliveness.
Open in your Internet browser address: https://your-server-name/index.html. Please, notice, that regarded to web browsers policy you can use web camera in your browser by HTTPS connection only.

Obtain temporary token script by your API credentials:

                
  curl -X POST \
    https://oz-api-domain-name/api/authorize/auth \
    -d '{
    "credentials": {
      "email": "demo@ozforensics.com",
      "password": "123456"
    }
  }'

Normally, you will get JSON answer with access_token value.

Notes. It is recommended to add separate user with attribute SERVICE_ACCOUNT and role CLIENT_ADMIN with Oz Web Console and then authorize for token.