QR Code Login

Introduction

QR Code Login is a proprietary authentication mechanism in IBM Security Verify which allows a user to authenticate to an application by scanning a QR Code using a pre-registered authenticator (for example the IBM Verify mobile app).

QR Code Login can be used as a first factor authentication mechanism because it doesn't need to know who the user is in order to generate the authentication challenge.

Registered Authenticator

In order to use the QR Code Login authentication method, a user must have previously registered an authenticator app (such as the IBM Verify mobile app) against their account. During registration, an OAuth grant flow is performed which allows the authenticator app to authenticate as the user and validate QR Code login transactions on their behalf. The authenticator app is given a Refresh Token which gives it long-lived authority to perform this task.

Application Initiates Authentication

When an application initiates QR Code login, IBM Security Verify generates a new QR Code transaction and returns the following JSON response:

{
    "id": "8ff25527-8083-4cd4-8bcc-775400b7ac9c",
    "type": "qr",
    "created": "2021-01-15T15:01:07.924Z",
    "updated": "2021-01-15T15:01:07.924Z",
    "expiry": "2021-01-15T15:03:07.924Z",
    "state": "PENDING",
    "location": "https://tenant.verify.ibm.com/v2.0/factors/qr/8ff25527-8083-4cd4-8bcc-775400b7ac9c",
    "profileId": "f4bc8b91-8061-49bf-9c69-46ffcb0b3d7b",
    "serviceName": "IBM Verify",
    "tenant": "tenant.verify.ibm.com",
    "lsi": "eopiqrozdvggcuu7p7c5i6cgfzxr5r",
    "dsi": "sbwdqgx86e7uyf8tnbgi9t4ltgokwh",
    "qrCode": "iVBORw0KGgoAAAANSUh....YII="
}

The application must display a QR Code containing the following attributes (from above) so it can be scanned by the registered authenticator:

• location
• lsi (local session index)
• seviceName
• expiry

To make life easier for the application, the qrCode attribute contains a ready-to-use base64-encoded QR Code image with this data.

Application polls for completion

Once the application has displayed the QR Code, it must poll at regular intervals (every 3-5 seconds for example) to determine if the QR Code transaction has been associated with a user. It makes a call to the Verify REST API where it identifies the transaction and passes in the dsi (device session identifier) from the initiation response.

The response from IBM Security Verify has the following format:

{
    "id": "8ff25527-8083-4cd4-8bcc-775400b7ac9c",
    "type": "qr",
    "created": "2021-01-15T15:01:07.924Z",
    "updated": "2021-01-15T15:01:07.924Z",
    "expiry": "2021-01-15T15:03:07.924Z",
    "state": "PENDING",
    "location": "https://tenant.verify.ibm.com/v2.0/factors/qr/8ff25527-8083-4cd4-8bcc-775400b7ac9c",
    "profileId": "f4bc8b91-8061-49bf-9c69-46ffcb0b3d7b",
    "serviceName": "IBM Verify",
    "tenant": "tenant.verify.ibm.com"
}

In this case, the session has not yet been validated and so the transaction is in PENDING state.

📘

Polling in a web application

When working with a web application, it is usual to control the polling described here using client-side JavaScript in the login page. The browser polls the application back-end and this triggers a poll to IBM Security Verify.

Authenticator Validates Session

Once the registered authenticator has scanned the QR Code presented by the application, it connects to IBM Security Verify (using location) and validate the session (identified by lsi) on behalf of the user that registered it.

The registered authenticator authenticates to IBM Security Verify by presenting an OAuth Access Token. This Access Token is obtained by using the Refresh Token flow.

When IBM Security Verify receives the session validation request it has the following information:

• Session Index
• User associated with the presented Access Token

IBM Security Verify associates the user with the QR Code transaction and marks the transaction complete.

Application poll returns success

The next time the application polls for completion, after the transaction has been marked complete, the response will have the following format:

{
    "id": "8ff25527-8083-4cd4-8bcc-775400b7ac9c",
    "userId": "642000EPOU",
    "type": "qr",
    "created": "2021-01-15T15:01:07.924Z",
    "updated": "2021-01-15T15:01:57.145Z",
    "expiry": "2021-01-15T15:03:07.924Z",
    "state": "SUCCESS",
    "updatedBy": "642000EPOU",
    "location": "https://tenant.verify.ibm.com/v2.0/factors/qr/8ff25527-8083-4cd4-8bcc-775400b7ac9c",
    "profileId": "f4bc8b91-8061-49bf-9c69-46ffcb0b3d7b",
    "serviceName": "IBM Verify",
    "tenant": "tenant.verify.ibm.com"
}

In this response, status is SUCCESS and the authenticated user ID is returned. Note that this is the internal Cloud Directory ID of the user. A call to the SCIM interface is required to read user data associated with this user.

💎

Jon Harry, IBM Security