FIDO token migration - REST flow example

This example shows how to configure and use the REST authentication flow to register a FIDO Authenticator during the login process. The main use case is token migration, i.e. migrating from another second factor to Airlock FIDO as the authentication method by the end-user.

0. The flow shown in this example is as follows:
1. Strong user authentication (not with FIDO as 2nd factor).
2. Ask the end-user to migrate to FIDO.
3. FIDO registration step (includes setting a display name for the registered FIDO Authenticator).

• Understand how to configure and use token migration in the Loginapp REST API.
• Understand how to register a FIDO Authenticator during authentication in the Loginapp REST API.

All following procedures are exemplary and will vary according to your setup or needs.

Note that the token migration flow can be tailored by configuration: it offers various options to force users to migrate, to let users skip migration, and to grant users a migration grace period. Please refer to the plugin's documentation in the Config Editor for further information.

In the following example, the user is both allowed to skip and reject migration.

• An end-user account exists in IAM and end-users can be authenticated (e.g. username, password, and a 2nd factor).

• FIDO is set as the authentication method to migrate to for the end-user.

• The end-user has a supported FIDO authenticator.

• The FIDO authenticator complies with the settings in the FIDO configuration.

• The end-users browser or mobile app supports FIDO.

1. Go to:

Loginapp >> Authentication Flows >> Default Application >> Authentication Flow

2. Add the plugin Username Password Authentication Step as the first step.
3. Add the plugin mTAN Authentication Step as the second step (the example below uses mTAN as 2nd factor).
4. Add the plugin Migration Selection Step as the third step and configure it as follows.
5. To the list of Available Options, add the plugin Default Migration Selection Option and configure it with the FIDO Registration Step.


Make sure, that the end-user has been authenticated in a strong way before migrating to FIDO. To do so make sure that the FIDO Registration Step ensures this by requiring a corresponding tag in the list of Pre Condition Tags (e.g. require the mTAN verified tag).

6. The REST authentication API is now ready to use.

• User account exists in IAM and has a first factor (e.g. username and password).

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 end-user is authenticated with username, password, and mTAN/SMS. The REST call sequence is as in the mTAN example given on Usage examples of REST authentication API.

In this case, instead of the final response of the mTAN example, the REST API asks the user to migrate by returning the following response:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:09:49.190+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "486984513816256656",
        "attributes": {
            "nextAuthStep": "MIGRATION_SELECTION_REQUIRED"
        }
    }
}

The REST client can retrieve the possible migration options using the following request:

POST /rest/public/authentication/migration/options/retrieve/

In our example, there is only one option – migration to FIDO. The response of the above request also informs about migration modalities such as skippable, rejectable, due-date, etc.:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:11:21.235+02:00",
        "migrationInfo": {
            "rejectPossible": true,
            "skipPossible": true
        }
    },
    "data": [
        {
            "type": "authentication.migration.option",
            "id": "FIDO",
            "attributes": {}
        }
    ]
}

Through the last response, IAM also informs the client how token migration is configured and if skipping or rejecting the migration is permitted or not. In our example, IAM allows skipping and rejecting the migration and the client could present these options to the end-user. Depending on the user's decision the client uses one of the following calls to the REST API:

In this example, we continue with the migration. To initiate it, the client sends the select request as follows:

POST /rest/public/authentication/migration/options/FIDO/select/

The response informs the client on how to proceed with the migration. It is the first response of the FIDO Registration Step.

HTTP/1.1 200 OK

{
   "meta":{
      "type":"jsonapi.metadata.document",
      "timestamp":"2021-02-10T08:09:52.506+01:00"
   },
   "data":{
      "type":"authentication.session",
      "id":"333961605658637333",
      "attributes":{
         "nextAuthStep":"FIDO_REGISTRATION_CHALLENGE_RETRIEVAL_REQUIRED"
      }
   }
}

To register a FIDO Authenticator, a challenge must be fetched. At the same time, a display name for the Authenticator to be registered must be set:

POST /rest/public/authentication/fido/registration/challenge/retrieve
 
{"displayName":"my FIDO security key"} 

The response contains the challenge as well as information about acceptable FIDO Authenticators. This information is processed by the FIDO client (browser or app). The FIDO client then typically asks the end-user to choose and/or connect the FIDO Authenticator and to give permission to use it for registration:

HTTP/1.1 200 OK

{
   "meta":{
      "type":"jsonapi.metadata.document",
      "timestamp":"2021-02-10T09:31:45.545+01:00"
   },
   "data":{
      "type":"authentication.fido.registration.challenge",
      "id":"577393204",
      "attributes":{
         "publicKeyCredentialCreationOptions":{
            "rp":{
               "name":"localhost",
               "id":"localhost"
            },
            "user":{
               "name":"-",
               "id":"zBcyYsonWQgxZ9NbeZz9n_N0G6Pu5DaF_D3E",
               "displayName":"my FIDO security key"
            },
            "challenge":"rTaPCmCTqseBcAP82…zkQ",
            "pubKeyCredParams":[
               {
                  "type":"public-key",
                  "alg":-7
               },
               {
                  "type":"public-key",
                  "alg":-8
               }
            ],
            "timeout":60000,
            "authenticatorSelection":{
               "requireResidentKey":false,
               "userVerification":"preferred"
            },
            "attestation":"direct"
         }
      }
   }
}

If a suitable FIDO Authenticator has been connected to the FIDO client and the challenge has been signed, a response as in the following example is sent back to the Loginapp REST API:

POST /rest/public/authentication/fido/registration/attestation-response/check

 
{"publicKeyCredential":{"id":"qWJGh6SV0seHa1pFNcES….EAw","response":{"attestationObject":"o2NmbXRoZmlkby11….7TU","clientDataJSON":"{\"challenge\":\"rTaPCmCTqseBcAP82UTWlDJ6g4Sx_IUBcmO-xjskzkQ\",\"clientExtensions\":{},\"hashAlgorithm\":\"SHA-256\",\"origin\":\"https://localhost:8443\",\"type\":\"webauthn.create\"}"},"type":"public-key"}}
  

After successful registration activation, the response is:

HTTP/1.1 200 OK

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2020-08-24T10:23:18.441+02:00"
    },
    "data": {
        "type": "authentication.session",
        "id": "486984513816256656",
        "attributes": {}
    }
}

• Use case: FIDO token migration self-service
• FIDO configuration overview