Skip to content

Service architecture#

LUNA PASS solution architecture diagram (Figure 1).

General scheme of LUNA PASS solution architecture
Figure 1. General scheme of LUNA PASS solution architecture

The architecture includes the following components (Table 1):

Table 1. Components of the LUNA PASS solution architecture

Component name

Description of interaction

LUNA PASS UI

LUNA PASS front-end component responsible for capturing video stream, sending video stream frames to LUNA PASS API and displaying processing results. An external system with similar functions can be used instead of LUNA PASS, provided that the LPProto protocol is used to connect to the Backend (see LPProto protocol for the principle of operation).

Front detector (Blazeface)

A detector built into the LUNA PASS UI responsible for detecting faces before sending the Frame to the LUNA PASS API.

Used to reduce the channel load between LUNA PASS UI and LUNA PASS API (to avoid forwarding frames without faces).

LUNA PASS API

LUNA PASS server component, which implements the logic of frame processing and decision making on image and Liveness checks, including with the help of plugins, built on AIOHTTP.

LUNA PASS VIDEO

LUNA PASS server component that implements the gluing of frames received within LUNA PASS API sessions into video.

LUNA SDK

VisionLabs development kit including libraries and neural networks for face detection, attribute estimation and Liveness estimation on the acquired image.

AggregateLiveness plugin

LUNA PASS API plugin that allows to calculate aggregated Liveness value over several frames.

ActiveLiveness plugin

LUNA PASS API plugin that allows you to confirm wether a person on several frames is “real” or a fraudster through user interaction: blinking, turning the head left and right along the Y axis, tilting the head up and down along the X axis.

VideoRedis plugin

LUNA PASS API plugin that allows you to store a sequence of frames (together with results of checks on them) for further gluing and creating video in LUNA PASS VIDEO. The plugin requires Redis to work.

Bestshot plugin

LUNA PASS API plugin that allows you to select as bestshot the frame with the best quality and Liveness score.

Luna3Descriptor QualityCheck plugin

LUNA PASS API plugin that allows you to send a request to LUNA PLATFORM 3 to retrieve the descriptor and check its quality.

The plugin allows you to check the quality of the descriptor before sending the Frame to LUNA PLATFORM 3 and filter it in case of low quality.

IMPORTANT: plugin works only with LUNA PLATFORM version 3.x.

NGINX

Optional component. HTTP server and reverse proxy server for load balancing.

IMPORTANT: is not included in the scope of delivery, must be installed and configured separately (see the Appendix).

LPProto

A transport layer information transfer protocol that defines the structure of transmitted Frames using WebSocket.

Frame – a fragment of protocol data. See LPProto Protocol section for the list of Frames.

LUNA PASS API forms a JWT packet with the bestshot, on successful passing of Liveness . The network communication scheme is shown in the figure (Figure 2).

Scheme of network interaction of LUNA PASS components
Figure 2. Scheme of network interaction of LUNA PASS components

LPProto Protocol#

LPProto is a transport layer protocol developed by VisionLabs to restrict information transmitted using WebSocket. The principle of operation is transmission of consecutive Frames with messages.

Frame – a fragment of protocol data, which must be specified strictly according to the template. The definition applies only to this section, in the rest of the document the frame is a part of the video stream. The first line of each Frame specifies its command within the protocol.

Connection settings that are transmitted as part of the CONNECT command:

  • heartbeat:1000
  • session-id:623e1bbc-24f9-4d84-907f-8000978ec2a1

Its session ID is passed in the session-id header when the connection is initialized.

LPProto protocol format#

A schematic representation of the protocol format is shown in the figure (Figure 3).

Protocol format
Figure 3. Protocol format

The message consists of three lines:

  • First line – message type or command (described in Table 2);
  • The second line – section with any number of headers;
  • The third line – message body, separated by an empty line.

Table 2. Supported message types

Command

Description

Example

CONNECT

Start request to establish a connection to the Backend.

Without an established connection, work is not possible.

Acceptable headings:

  • version – LPProto protocol version.

  • heartbeat – optional activation of background requests every N ms to keep WebSocket open (see HEARTBEAT).

Possible answers:

  • CONNECTED – successful connection;

  • ERROR – connection error.

CONNECT

version:1.0

heartbeat:1000

CONNECTED

Response from Backend about successful connection to Frontend over WebSocket.

Acceptable headings:

  • session-id – Session UUID, the unique value of the connection;

  • version – LPProto protocol version.

CONNECTED

session-id:623e1bbc-24f9-4d84-907f-8000978ec2a1

version: 1.0

FRAME

A request from Frontend containing information about the image (a Frame of the video stream in the format specified in the content-type header).

Acceptable headings:

  • content-type – type of transmitted image

  • One line indent

  • Frame body – base64 image.

Possible answers:

STATS – image/face failed the test;

SUCCESS – the test was successful;

ERROR – error within a Frame check request.

Frontend restriction: the next FRAME cannot be sent until a response is received, this is necessary to synchronize data sending (including when using multiple Frontend instances) and minimizeerrors.

FRAME

content-type:image/x-jpeg-base64

/9j/4AAQSkZJRgABAQABAA…

STATS

Backend response after unsuccessful image estimation, containing the error codes detected (see /jslib/docs/lpErrors.js.html for a list of errors).

If a face was found in the image, the BBox information is returned.

Acceptable headings:

  • content-type – the type of message being transmitted;

  • details – Frame estimates, including BBox position, if any. The set of estimates depends on server implementation, there are no restrictions within the protocol.

  • errors – error list after image estimation (see /jslib/docs/lpErrors.js.html for error codes).

  • isOk - A boolean value that indicates whether the FRAME request was successfully executed.

STATS

content-type:application/json

{isOk: false, errors: [12], details: {,…}}

details: {,…}

details: {,…}

errors: [12]

isOk: false

SUCCESS

Backend response after successfully validating the image, selecting the bestshot and evaluating the face.

Acceptable headings:

  • content-type – the type of message being transmitted;

  • One line indent.

  • Frame body – information about image estimation in JWT format

After receiving this Frame WebSocket is closed. For further work it is necessary to reconnect.

SUCCESS

content-type:application/jwt

eyJ0eXAiOiJKV…

ERROR

Backend response when an internal error occurs: - Incorrect installation;

  • Communication break;

  • Incorrect license;

  • Other system errors.

Acceptable headings:

  • error – error code.

The following system errors exist in this version:

  • 1002 – internal server error

ERROR error: 1002

HEARTBEAT

Optional recurring background request from Backend to keep WebSocket open. See CONNECT for how to enable it.

Sends an empty Frame every N ms.

HEARTBEAT

JWT package#

JSON Web Token (JWT) – A JSON object that allows signed text information to be transmitted. JWT uses Base64 encoding.

JThe WT consists of 3 parts, separated by header.payload.signature dots:

1․ Title: Header

Description: JWT Type Information.

Example of decoded Base64:

The following attributes are always used during LUNA PASS operation: {"typ":"JWT","alg":"HS256"}

2․ Title: Payload

Description: A message body containing information on the recognized attributes.

See /jslib/docs/LunaPass.js.html for a detailed description.

Example decoded Base64:

python { "details": { "ags":0.9812286496162415, "quality": { "blur":0.9293031692504883, "isBlurred":false, "light":0.6043056845664978, "isHighlighted":false, "darkness":0.8230781555175781, "isDark":false, "illumination":0.18545985221862793, "isIlluminated":false, "specularity":0.5418229103088379, "isSpecular":false }, "faceFramePosition": { "faceRect": { "x":229, "y":138, "width":207, "height":281 }, "frameRect":{"x":0,"y":0,"width":640,"height":480}, "margins":[138,204,61,229]}, "headPose":{ "yaw":-3.0735106468200684, "roll":1.396299958229065,"pitch":0.3325376510620117}, "mouth":{"opened":0.29780369997024536, "smile":0.0018320679664611816, "occluded":0.016269110143184662}, "eyeglasses":"GlassesEstimation.NoGlasses", "liveness":{"score":0.8843579292297363, "qualityScore":1.0}}, "errors":[], "isOk":true, "bestshot":"<Face image in Base64>", "iat":1680679123, "jti":"a9be95d6-6653-4279-bac1-a2a01618a158"}

3․ Title: Signature

Description: Unique message signature.

Example decoded Base64: -