Requirements
Component | Requirement | Comments |
---|---|---|
Airlock IAM |
| For licensing: |
Component | Requirement | Comments |
---|---|---|
Airlock IAM |
| For licensing: |
This example shows how to configure and use the REST authentication flow for:
It shows both device selection and hardware token login.
All following procedures are exemplary and will vary according to your setup or needs.
Loginapp >> Applications and Authentication >> Default Application >> Authentication Flow
For simplicity, the configuration instructions and usage examples are given for the default application within the Loginapp REST API's Authentication Flows settings. Therefore, no application selection REST calls are shown.
First, the username and password are checked:
POST /rest/public/authentication/password/check/ { "username" : "jdoe", "password" : "password1" }
If the first authentication step succeeds, the second authentication step is initiated. Since the user has more than one device, the Airlock 2FA Step for Authentication asks to select the device in the response:
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2020-08-24T17:14:13.100+02:00" }, "data": { "type": "authentication.session", "id": "108266430294427818", "attributes": { "nextAuthStep": "AIRLOCK_2FA_DEVICE_CHOICE_REQUIRED" } } }
To get information about available devices, the following request can be used:
POST /rest/public/authentication/airlock-2fa/devices/retrieve/
In our example, it's response lists the user's smartphone and a hardware token:
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2020-08-24T09:54:34.742+02:00" }, "data": [ { "type": "authentication.airlock-2fa.device", "id": "86cb1f74-5f1d-43e3-8937-d41e0dbacabd", "attributes": { "displayName": "Joe's iPhone", "deviceType": "IOS" } }, { "type": "authentication.airlock-2fa.device", "id": "6652400b-598b-442f-b90e-990295a78d9c", "attributes": { "displayName": "GAQT12345678", "deviceType": "HWTOKEN" } } ] }
To select the hardware token, use its token id with the following request:
POST /rest/public/authentication/airlock-2fa/devices/6652400b-598b-442f-b90e-990295a78d9c/select/
Since a hardware token has been selected, the REST API asks for a QR code OTP code:
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2020-08-24T09:55:50.147+02:00" }, "data": { "type": "authentication.session", "id": "108266430294427818", "attributes": { "nextAuthStep": "AIRLOCK_2FA_QR_CODE_OTP_REQUIRED" } } }
In the next step, the REST client gets a QR code challenge from the REST API by sending the following request:
POST /rest/public/authentication/airlock-2fa/offline-qr-code/challenge/retrieve/
The response bears a QR code image (base-64 encoded PNG) that has to be scanned by the user using the hardware token (the base-64 image string has been truncated in the example response).
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2020-08-24T09:57:08.515+02:00" }, "data": { "type": "authentication.airlock-2fa.offline-qr-code.challenge", "id": "2727441580", "attributes": { "challengeImage": "iVBORw0KGgoAAAANSUhEUgAAAl..." } } }
The hardware token computes an OTP code from the QR code challenge and the user enters the OTP code in the browser or app. To check the OTP code using the REST API, use the following request:
POST /rest/public/authentication/airlock-2fa/offline-qr-code/otp/check/ { "otp" : "123456" }
If the code is correct, the authentication flow successfully ends with the response
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2020-08-24T10:08:25.196+02:00" }, "data": { "type": "authentication.session", "id": "108266430294427818", "attributes": {} } }