Deploying Liveness Check Proxy

This chapter explains how to deploy Liveness Check Proxy.

Right now, the only standalone war is supported running from console using the java -jar command. The deployed application is accessible on http://localhost:8080/liveness-check-proxy/.

Setting Up REST Service Authentication

Access to REST services that provide sensitive information is limited to users with elevated privileges. You can choose between Basic HTTP and OpenID Connect authentication, each requiring specific configurations as described below. By default, basic HTTP authentication scheme is used. To change this preference, set the liveness-check-proxy.security.auth.authType configuration property.

Basic HTTP

To use Basic HTTP authentication a user with admin role must exist. To create a new user with the admin role, execute the following SQL insert statements directly in the database:

INSERT INTO lcp_user (username, password, enabled) VALUES ('<username>', '<encoded_password>', true);
INSERT INTO lcp_authority (username, authority) VALUES ('<username>', 'ROLE_ADMIN');

The password must be encoded using either the SHA-256 or bcrypt hash algorithm. You should prepend the hashed password with the appropriate prefix {SHA-256} for SHA-256 or {bcrypt} for bcrypt. For example:

BCRYPT_PASSWORD="{bcrypt}$(htpasswd -bnBC 12 "" '<password>' | tr -d ':')"
SHA256_PASSWORD="{SHA-256}$(echo -n '<password>' | openssl dgst -sha256 | cut -d' ' -f2)"

If the prefix is omitted, the used algorithm is determined by the liveness-check-proxy.security.auth.basicHttp.defaultPasswordEncoder property. For additional configuration options related to Basic HTTP authentication, refer to the configuration properties section.

OAuth2.x

To set up the OAuth2 authentication, specify which authorization server to use using the spring.security.oauth2.resource-server.jwt.issuer-uri configuration property.

Each request that requires privileged access must include JWT-encoded bearer token in the authorization header. The passed token must include roles claim, containing a list of roles for which is the user authorized. Specifically, there must be ADMIN role in the list for successful authorization.

You can configure the name of the roles claim name using liveness-check-proxy.security.auth.oauth2.rolesClaimName. For additional configuration options, refer to the configuration properties section.

Supported Java Runtime Versions

The following Java runtime versions are supported:

• Java 17 (LTS release)
• Java 21 (LTS release)

The Liveness Check Proxy may run on other Java versions, however we do not perform extensive testing with non-LTS releases.

Integration with User Data Store

In order to use the Liveness Check Proxy (LCP) together with User Data Store (UDS) as a user details provider, data stored in the UDS must adhere to a predefined structure to be effectively located and accessed by the LCP. Please consult the UDS RESTful API documentation, particularly the Document API and Photo API documentation.

The UDS is designed to accommodate a variety of use cases across different projects, therefore is structured around generic structure called document. The LCP specifically requires the presence of a document of type photo for each user to be verified. If a user in your UDS instance has multiple documents of type photo, you should assign one of them a distinct document attributes to ensure deterministic selection of that particular document by LCP. Authentic portraits of users must be then appropriately linked to the document, with the photo categorized as photo of type person to be recognized by the LCP.

For efficiency, it is possible to create a new document and upload a photo in a single REST API call. An example of a body of a request to the POST /admin/documents to create a new document and upload a photo is provided below:

{
  "requestObject": {
    "userId": "<user id>",
    "documentType": "photo",
    "dataType": "image_base64",
    "documentData": "{}",
    "attributes": {
       "tag": "liveness-check"
    },
    "photos": [
      {
        "photoType": "person",
        "photoData": "<base64 encoded image>"
      }
    ]
  }
}

The userId and photoData parameters should be replaced with their actual values. Parameter attributes is optional, but should be used to distinguish documents. All other parameters must reflect the example. So that the Liveness Check Proxy can effectively access photos uploaded in a similar way as in the example above, the configuration properties of the LCP must include the following settings to specify the expected document attribute:

liveness-check-proxy.user-details.provider.user-data-store.documentAttributes.tag=liveness-check

Uploaded photos can be updated via PUT /admin/photos endpoint.