Requirements
Component | Requirement | Comments |
|---|---|---|
Airlock IAM |
| For licensing: |
Intended solution environment
The following example illustrates how the Airlock 2FA token management self-services are configured and used over the REST API.
It covers the following use-cases:
- The user views Airlock 2FA app tokens.
- The user changes the display name of a token.
Goal
- Understand how the Airlock 2FA self-services work in general.
- Understand how the Airlock 2FA self-services are configured.
- Learn how to use the Loginapp REST API with respect to the Airlock 2FA self-services using an example.
All following procedures are exemplary and will vary according to your setup or needs.
Prerequisites
- The Loginapp REST API is configured and ready to use.
- At least one Login REST authentication flow is configured.
- The user has been authenticated using a REST authentication flow.
- The user has the access rights to use the self-services.
Configuration
- Go to:
Loginapp >> Protected Self-Services - Set the plugin Airlock 2FA Device List in property Airlock 2FA Device List. This will enable the REST API to retrieve the user's Airlock 2FA app devices.
- Go to: Protected Self-Service Flows. In the list of flows add the following flows.
- Add a flow plugin Self-Service Flow with flow ID device-rename and the following two steps: Airlock 2FA Device Edit Initiation Step followed by Apply Changes Step. The latter must list a handler of type Airlock 2FA Apply Device Edit Change so IAM knows how to persist the changes. As
- Add a flow plugin Self-Service Flow with device ID device-delete and the following two steps: Airlock 2FA Device Delete Initiation Step followed by Apply Changes Step. The latter must list a handler of type Airlock 2FA Apply Device Deletion Change so IAM knows how to persist the changes.
The flow for device activation is not shown in the example and hence not required in the configuration. To enable the device activation self-service, add a Self-Service Flow plugin containing the Airlock 2FA Activation Step.
Step 1 - Get Airlock 2FA devices
The following request gets the list of devices with the device IDs:
POST /rest/protected/self-service/airlock-2fa/app-devices
Assuming the user has two app devices, it returns the following response:
HTTP/1.1 200 OK
{
"meta":{
"type":"jsonapi.metadata.document",
"timestamp":"2020-09-02T10:16:22.804+02:00"
},
"data":[
{
"type":"my.token.airlock-2fa.app-device",
"id":"dbe2ee06-aaae-4957-ab3d-67ee87cc0503",
"attributes":{
"displayName":"jdoe Office Phone",
"capabilities":[
"ONE_TOUCH",
"TOTP",
"QR_CODE"
],
"type":"IOS",
"appVersion":"1.0.0",
"appVersionSupported":true
}
}
{
"type":"my.token.airlock-2fa.app-device",
"id":"a34debd4-40e3-4559-a5f4-ac13b42c1fc3",
"attributes":{
"displayName":"John's iPhone",
"capabilities":[
"ONE_TOUCH",
"TOTP",
"QR_CODE"
],
"type":"IOS",
"appVersion":"1.0.0",
"appVersionSupported":true
}
}
]
}
Step 2: Select change device name flow
The next few calls change the device name. To do this, several calls are necessary. This is because of the great flexibility, the protected self-service flow feature offers.
Before starting a flow, it is generally a good idea to end possibly ongoing other flows of the same type to avoid getting a UNEXPECTED_CALL response. To do so, we use the following request in our example.
DELETE /rest/protected/self-service/flow
To start the protected self-service flow with flow ID device-rename, use:
POST /rest/protected/self-service/flows/device-rename/select
The response tells the REST client, that an Airlock 2FA device must be selected to continue:
HTTP/1.1 200 OK
{
"meta":{
"type":"jsonapi.metadata.document",
"timestamp":"2020-09-02T10:23:35.525+02:00"
},
"data":{
"type":"self-service.session",
"id":"537172350813223689",
"attributes":{
"nextStep":"AIRLOCK_2FA_DEVICE_CHOICE_REQUIRED"
}
}
}
Step 3: Select the Airlock 2FA device
In our example, we select the first device (jdoe Office Phone) using the request:
POST /rest/protected/self-service/airlock-2fa/devices/dbe2ee06-aaae-4957-ab3d-67ee87cc0503/select
The response indicates that changing the device name is possible:
HTTP/1.1 200 OK
{
"meta":{
"type":"jsonapi.metadata.document",
"timestamp":"2020-09-02T10:23:35.626+02:00"
},
"data":{
"type":"self-service.session",
"id":"537172350813223689",
"attributes":{
"nextStep":"AIRLOCK_2FA_DEVICE_EDIT_POSSIBLE"
}
}
}
Step 4: Get the current device name
If interested in the current device name of the selected device, it can be retrieved using the following request:
POST /rest/protected/self-service/airlock-2fa/device-edit/data/retrieve
HTTP/1.1 200 OK
{
"meta":{
"type":"jsonapi.metadata.document",
"timestamp":"2020-09-02T10:29:32.288+02:00"
},
"data":{
"type":"self-service.airlock-2fa.device.data",
"id":"dbe2ee06-aaae-4957-ab3d-67ee87cc0503",
"attributes":{
"displayName":"jdoe Office Phone"
}
}
}
Step 5: Set a new device name
To finally change the new device name, two more requests are necessary. First set the new device name by sending the following request:
POST /rest/protected/self-service/airlock-2fa/device-edit/data
{displayName: "My office cell phone"} The response indicates that further device edit calls would be possible.
HTTP/1.1 200 OK
{
"meta":{
"type":"jsonapi.metadata.document",
"timestamp":"2020-09-02T10:32:44.613+02:00"
},
"data":{
"type":"self-service.session",
"id":"537172350813223689",
"attributes":{
"nextStep":"AIRLOCK_2FA_DEVICE_EDIT_POSSIBLE"
}
}
}
Step 6: Persist changes
To persist the change, use the following continue request:
POST /rest/protected/self-service/airlock-2fa/device-edit/continue
The following response tells the client that the flow has successfully completed:
HTTP/1.1 200 OK
{
"meta":{
"type":"jsonapi.metadata.document",
"timestamp":"2020-09-02T10:32:44.827+02:00"
},
"data":{
"type":"self-service.session",
"id":"537172350813223689",
"attributes":{
}
}
}