Web SDK - QR code authentication

The QR code authentication sample code provides a page using TrustBuilder QR code authentication method. This document provides information to help you use the sample code.

Download the QR code authentication sample code

• The sample code consists of:

  • a sample html page including JS scripts

  • assets folder with CSS and sample logo

  • an external JavaScript library ‘qrcodejs.js' for making QR Codes

Prerequisites

• In the Administration console:

  • configure a connector and an associated secure site.

  • in the Service Parameters tab, enable the QR code authentication (“Allow QR scan authentication method” parameter). The “Scan a QR code” option will appear in the home of TrustBuilder Authenticator app (from version 6.31).

Workflow

Script elements

Calling libraries

The QR code authentication sample code uses two JavaScript libraries:

• a TrustBuilder library 'qrcode-lib.js' containing the QR code authentication functions.

  CODE

  <script src="https://ult-inwebo.com/neon/3.17.0/qrcode-lib.js" type="text/javascript"></script>

• an external UI library to display a QR code, based on a payload:

  JS

  <script src="./lib/third-party/qrcodejs.js" type="text/javascript"></script>

Authorization URL

You should specify the Authorization URL defined at connector and secure site configuration.

• The secureSiteAuthorizationUrl should match the Authentication page parameter set in the secure site.

  CODE

   var secureSiteAuthorizationUrl = `${rootUrl}/authentication-page-xxxx`

generateQRCode function

The generateQRCode function requests TrustBuilder to generate a QR code for authentication. Actually thegenerateQRCode function generates a session ID. The QR Code is built from this session.

• Input parameters:

  • login (string) → the user’s login

  • serviceId (string) → the service ID

• Returns:

  • on success → a session ID used to build the QR code payload

  • on error → an error

    • Missing fields

    • Network error

retrieveQRCodeOTP function

The retrieveQRCodeOTP function requests TrustBuilder to check the QR code authentication result of a specific session.

• Input parameters:

  • sessionId (string) → session ID of the authentication session

  • login (string) → the user’s login

  • serviceId (string) → the service ID

• Returns:

  • on success → an OTP on success

  • on error → an error

    • NOK:REFUSED ==> user refused authentication

    • NOK:TIMEOUT ==> user did not authenticate in time (1 minute)

    • NOK:SN ==> syntax error in input parameters

    • NOK:srv unknown ==> serviceId is wrong

    • NOK ==> sessionId does not exist or has expired

Sample code

1. In the sample.html, set secureSiteAuthorizationUrl to match the Authentication page parameter defined in the secure site.

   

   CODE

    var rootUrl = 'https://ult-inwebo.com';
    var secureSiteAuthorizationUrl = `${rootUrl}/authentication-page-qrcode`

2. Run the sample code.

   

3. Test the “Generate QR code”: enter the user login and the service ID.

4. Click on Generate. This operation displays a session ID and the associated QR code.

5. Test the “Get OTP for authorized QR code”: the sessionId, login & service are automatically copied over, when the previous call succeeds. Click on Retrieve. This operation waits for the QR code authentication result.

6. In TrustBuilder Authenticator app, click on “Scan a QR code”.

7. Scan the QR code.

8. In the sample page, on success, it should display the OTP.