Introduction

LoQ (PC Login QR) is a feature to identify and authenticate a user on a web-site just with QR-code on login page.
User does not have to provide his login, password or any type of one-time passwords.

User's scenario is just to scan a QR-code with his mobile app and to confirm login operation.

At the same time user will be identified with their identifier in the mobile app, authentication will be processed with digital signature process using PC transaction confirmation feature.

How it works you can see at PC Demo page.

Idenitification and Authentication workflow

There are at least 8 components, which participate in user's identification and authentication process with LoQ feature.

As a result, web-application back-end will receive from LoQ components PC User ID and PC Transaction ID of identified and authenticated user.
After this web-application can match PC User ID with user's record in their database and proceed with user’s authorization.

Prerequisites

1. LoQ feature must be activated and installed in a customer’s infrastructure (or cloud-based installation can be used)
2. Web-application must be linked with PC (web-application users must use PC for transaction confirmations)

Workflow

The workflow is shown on the Figure 1 (it's recommended to enlarge the Figure).

Workflow Participants

Workflow steps (by the schema)

1. When WebApp back-end receives a request for login page (a new user opens a web session), it calls LoQ Internal for a LoQ JS and specifies need parameters: PC system_id, login message, url to make a callback when user will be identified and authenticated and url to redirect the Web Browser into authorized zone.
   LoQ JS will contain all of the needed information to interact with LoQ External, draw the QR-code for login and check if a user was already authenticated.
   
   • WebApp back-end should realize callback endpoint with callback_url to receive data about identified and authenticated PC User and PC Transaction ID. Based on this information WebApp back-end should authorize a user.
   • WebApp back-end should realize redirect endpoint with redirect_url. To this address web browser will be redirected by LoQ JS after user authentication. Before that callback will be sent to callback_url.
     
2. WebApp back-end embeds LoQ JS into login page and sends it to user’s Web browser.
3. From this step, LoQ JS starts to interact with LoQ External, draws and renews QR-code for login and checks if a user was authenticated.
4. On each request from LoQ JS LoQ External checks session data, renews QR-code if needed and sends redirection in case of user was authenticated.
5. After QR-code was shown in the Web browser Mobile App can scan this QR-code to start identification and authentication process.
6. QR-code value (decoded value) should be provided to PC Mobile SDK, after this authentication process can be started:
   • call PCLogin.importFromJSON(…)
   • determine if one of registered PC Users can be used for login (users are registered in the same PC System)
   • request Login Transaction to authenticate a user
7. Based on the request from PC Mobile SDK with user’s identifier LoQ External makes a request to LoQ Internal for create PC Transaction with PC Server. This transaction must be signed to authenticate a user.
8. PC Transaction ID will be provided via LoQ Internal and LoQ External to PC Mobile SDK.
9. After this PC Mobile SDK requests transaction data and provides them to Mobile App to show to a user.
10. If a user agrees to login, Mobile App with PC Mobile SDK signs the transaction.
11. After PC Transaction was signed and verified, PC Server sends callback to LoQ Internal.
12. LoQ Internal sends callback to WebApp back-end with PC User ID and PC Transaction ID in the current session.
13. WebApp back-end should mark by internal rules that
    • in the session with specified session id
    • user with specified pc user id
    • authenticated by signing transaction with specified pc transaction id
14. On the next request from LoQ JS LoQ External will answer that Web browser should be redirected to redirect_url with session id parameter.
15. LoQ JS redirects browser to WebApp back-end’s redirect_url, WebApp back-end receives from Web browser session id.
16. WebApp back-end checks which user was identified and authenticated in the session with specified session id (step 13).
17. If a user was found, then WebApp back-end authorizes web session to access to authorized zone.
18. Optionally, WebApp back-end can retrieve all of the information about transaction confirmation (digital signature value, mobile device data, transaction details and so on) from PC Server with specified transaction id.

Integration and API

Get LoQ JS

Get LoQ JS

endpoint: {{loq-internal-url}}/system/loginUser
method: POST
content-type: application/json

Request

{
    "systemId" : "{{pc-system-id}}",
    "callback" : "{{callback-url}}",
    "redirect" : "{{redirect-url}}",
    "sessionTimeout" : 6000,
    "qrTimeout" : 600,
    "size" : 300,
    "text": "Please, confirm your login to the best web site",
    "textRenderType": "raw"
}

This request is to generate JS-script with all of the params to work on the web browser side.

Response will return JS-script that should be embedded into login-page in <script></script> html-tag.

Login-page content

Example JS-code to launch LoQ

// if LoQ JS was embedded successfully
if (typeof getQr === "function") { 
    getQr();
}

Default LoQ JS tries to find pc_lo_qr object with type img in HTML DOM structure and to insert into src property value of recieved QR-code.
To launch the interaction process between LoQ JS and LoQ External login-page must execute function with default name getQr (see example).

LoQ JS can be tuned or replaced if needed during LoQ installation process. In this case, functions' or objects' names can be different.

Callback receiver requirements

Callback content

endpoint: {{callback_url}}
method: POST
content-type: application/json

{ 
   "pc_callback":{ 
      "loqr_callback":{ 
         "sessionId":"25552734-a388-4f30-8517-2b67598f2f75",
         "pcUserId":"c1d656e9-481b-4244-ade1-f36ec10eff25",
         "transactionId":"bf6c447a-0f82-4bd3-a49f-0c460bea4fcc"
      },
      "type":"loqr_callback",
      "result":{ 
         "error_message":"Success",
         "error_code":0
      },
      "version":3
   }
}

After a user will be identified and authenticated LoQ Internal will send callback to WebApp back-end to callback_url, specified in Get LoQ JS request.

Redirect receiver requirements

Default script to make a redirect

// clear QR-code value
document.getElementById('pc_lo_qr').src = "";

// create html-form
var redirectForm = document.createElement('form');
document.body.append(redirectForm);
redirectForm.setAttribute('action', response.redirect.url);
redirectForm.setAttribute('method', 'post');
redirectForm.setAttribute('hidden', 'true');

// add input with name sessionId
var sessionId = document.createElement('input');
sessionId.setAttribute('name', 'sessionId');
sessionId.setAttribute('id', 'sessionId');
sessionId.setAttribute('type', 'hidden');

// set sessionId value to recevied from LoQ External value
sessionId.setAttribute('value', response.redirect.sessionId);

redirectForm.append(sessionId);

// submit the form to redirect
redirectForm.submit();

After a LoQ JS will receive information about user was authenticated, it will redirect Web browser to redirect_url specified in Get LoQ JS request.

Default LoQ redirection method is js-script that embeds html-form into HTML DOM model and submits them.
Before this script clears QR-code value.

So, if you are using default redirection method, redirect receiver on WebApp back-end side should process request with application/x-www-form-urlencoded content-type.

JS-script to proceed the redirection can be tuned or replaced if needed during LoQ installation process.

Mobile App Requirements

Mobile App should realize LoQ process as shown on the schema.

Login process from mobile app point of view are managed with PCLogin class.

The sample algorithm of logging in with QR-code is the following:

1. Scan QR code and extract json containing all required data
2. Call importFromJson(String, GetLoginDataCallback) to construct PCLogin object. Constructed object will be returned as parameter of success() method.
3. Call suggestUsers() on constructed object to get keys which can be used to log in
4. After choosing a key call requestLoginTransaction(PCUser, GetLoginTransactionCallback) with a selected PCUser from one of returned by suggestUsers()
5. After PCLogin.GetLoginTransactionCallback.success(PCTransaction) is invoked, you may show transaction data in the app. Note, that the PCTransaction.getTransactionText() can either return null or text of transaction. Do not try to sign this transaction manually, instead call either confirm(PCGeneralCallback) to finish logging in or decline(PCGeneralCallback) to cancel login operation.

You can find more detailed information in PC Mobile SDK.

In the same time reference PC Mobile Application can be used.

Infrastructure integration

Components interaction

LoQ contains of two parts: LoQ External and LoQ internal.

Roles of this parts you can find in the workflow description.

Login workflow participants interaction diagram you can find on Figure 2.

Server component supply options

LoQ server components are supplied as Java application (jar-file) and instruments to run as service (linux- or windows-based).

LoQ uses Redis cache server to store data about active sessions. Redis should be installed to be accessible from LoQ Internal and LoQ External components.

Typical machine components

A typical machine (or a container) consists of the following installed components:

All the LoQ components are launched automatically with the operating system. No manual settings for start/shutdown is required.

If neither a physical nor virtual servers are supplied, the OS preparation is carried out by the customer. Preparation includes:

• Installation of the operating system;
• Proper configuration of DNS records;
• Installation of the Java Runtime Environment;
• Preparing TLS certificates (if necessary).

The following alternative components can be used:

Resiliency and scaling

Resiliency and scaling options are equals to PC Server components.