Use case: FIDO token migration self-service

This article describes the token migration self-service that can be used to move end-users from using an arbitrary second factor to using FIDO.

The described process allows end-users to register a FIDO authenticator during the login process.

To register FIDO authenticators after the login process, i.e. for already authenticated end-users, see Use case: FIDO registration self-service instead.

Note that FIDO credentials can be managed by administrators in the IAM Adminapp, but they can only be registered by the end-user in a self-service.


    • Understand how token migration works in general.
    • Understand how token migration to FIDO works.
    • Learn details about prerequisites and limitations.

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

Initial thoughts

Token migration is an end-user self-service and part of the authentication process. It requires an established authentication method prior to the token migration. The established (old) token is used to authenticate the user, then the end-user is asked to enroll the (new) token of a different type.

Users are marked for migration using the Adminapp or the Adminapp REST API.

Token migration is configurable as optional or mandatory. In addition, a grace period can be set which allows the end-user to freely postpone his migration within the defined period.

With these features, end-users can easily be migrated to a new second factor without activation letters and administrative effort.

If FIDO is used as the second factor in strong authentication, it is required to authenticate the end-user in a strong way before token migration.

While it is possible to enroll FIDO Authenticators just based on username and password, the security risks of such a setup must be considered thoroughly.

In all cases, Airlock IAM acts as FIDO relying party.


  • 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.
  • To support FIDO passwordless authentication (now or in the future), make sure to require keys to be resident during the registration.
  • The FIDO authenticator has been registered with the end-users account.

Token migration

The following flow chart shows how token migration to FIDO works:


The end-user is authenticated with existing credentials and usually an established second factor. This may be another FIDO authenticator or a different second factor.


The end-user is asked to migrate to FIDO. Depending on the configuration, migration is optional or mandatory to the user.


The end-user has to choose a display name for the registered FIDO authenticator. The display name later helps the user (or the helpdesk) to identify the authenticator. This is especially important if a user registers multiple authenticators.


IAM sends a FIDO registration challenge to the FIDO client (browser or mobile app).

Together with the challenge, constraints restricting the set of allowed FIDO authenticators are send to the FIDO client. The constraints depend on the FIDO settings in the configuration. They include:

  • Signature algorithm constraints.
  • List of excluded FIDO authenticators (e.g. already registered ones).
  • User verification preferences.
  • Type of authenticator (platform or cross-platform)
  • Whether FIDO passwordless must be supported
  • FIDO attestation preferences

The browser interacts with the user and the FIDO authenticator to retrieve the response to the challenge, and it sends the response back to Airlock IAM.

If multiple suitable FIDO authenticators are available to the FIDO client, a selection dialog is presented to the end-user.


Airlock IAM verifies the response to the challenge and checks whether all FIDO authenticator constraints are met. Details of the verification depend on the FIDO configuration settings in Airlock IAM.

If the verification succeeds, the FIDO credential is stored in the IAM user database and a confirmation is sent to the caller.

Screen Flow Example

The following screenshot series shows an exemplary token migration flow in the Loginapp UI for a roaming FIDO Authenticator.

Browser dialog details depend on the browser make and version.

  1. Dialog in which the end-user is asked to migrate to FIDO (during login process):
  2. FIDO-token-migration-step1-start-migration
  3. Dialog to enter the display name of the FIDO authenticator to be registered:
  4. FIDO-token-mgiration-step2-enter-displayname
  5. Dialog requesting the end-user to insert and interact with the FIDO authenticator:
  6. FIDO-token-migration-step3-device-seclection
  7. Confirmation dialog asking the end-user, whether the selected FIDO authenticator may be used for registration:
  8. FIDO-token-mgiration-step3-browser-allow
  9. The registration of the FIDO credential is completed after this step.


The following limitations apply in FIDO token migration:

  • FIDO is only supported by the Loginapp UI and the Loginapp REST API.
  • FIDO authenticators must support resident keys for (later) passwordless authentication. This can be enforced during FIDO registration (token migration and self-service) and enabled in the FIDO settings in the IAM configuration.
  • Not all FIDO Attestation statement formats are supported by Airlock IAM. Please review the set of supported formats in the documentation of the FIDO attestation verifying plugin in the FIDO settings.