Change device name for 2FA
17.2.5.4. Airlock 2FA change device name - REST flow example

Requirements

Component
Requirement
Comments
Airlock IAM
  • Airlock IAM 7.3 or newer.
  • An Airlock 2FA subscription is required.
For licensing:
Contact order@airlock.com.

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

  • 1.
    Go to:
    Loginapp >> Protected Self-Services
  • 2.
    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.
  • 3.
    Go to: Protected Self-Service Flows. In the list of flows add the following flows.
  • 4.
    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
  • 5.
    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":{
            
        }
    }
}  

Further information and links