Technical Tip: Migrating users and FortiTokens to another FortiGate/FortiAuthenticator

[matanaskovic]

Description

This article describes the procedure to migrate Hardware and Mobile FortiTokens to a new FortiGate or FortiAuthenticator.

FortiToken Mobile licenses can be migrated in the following scenarios:

• RMA replacement of a failed FortiGate or FortiAuthenticator.
• Migrating FortiToken Mobile license to FortiToken Cloud.

Hardware tokens can be migrated in the following cases:

• RMA replacement of a failed FortiGate or FortiAuthenticator.
• Transferring Token to a different FortiGate.
• Migrating two-factor authentication from FortiGate to FortiAuthenticator.

Scope

FortiAuthenticator, FortiToken, FortiGate.

Solution

Note: For FortiToken Mobile licenses shipped on or after August 4 2025, FortiToken Mobile license transfer is only permitted in cases of RMA for a failed device. See the article Technical Tip: FortiToken Mobile no longer supports License Transfer between different devices. FortiToken Mobile licenses shipped before August 4 2025 do not have this restriction and may be transferred to FortiGate or FortiAuthenticator devices that are not RMA replacements.

For FortiToken Mobile licenses purchased after this change, if a device hosting a FortiToken Mobile license will be replaced for reasons other than hardware fault, either a new FortiToken mobile license must be purchased and applied to the new device, or FortiToken Mobile license must be transferred to a FortiToken Cloud subscription before the migration, following the procedure in the FortiToken Cloud Admin Guide.

By design, FortiTokens (except the hardware FortiToken-211 and FortiToken-300 series) are always linked to the serial number of the unit on which they are activated.
If tokens must be moved to another unit, the Token license (Mobile Tokens) or Token seed (Hardware Tokens) should be transferred and manually added to the new unit. For FortiToken Mobile licenses shipped on or after August 4 2025, license transfer is only permitted for units that were RMA'd.

This involves deleting all tokens on the old unit and recreating the tokens on the new unit, and assigning all tokens to users again.

Note: If a migration involves moving from a VM to another VM (FortiGate VM to FortiGate VM, or FortiAuthenticator VM to FortiAuthenticator VM), and the VM serial number stays the same, the below is NOT required: the configuration simply needs to be migrated in full. The steps below are necessary when the device's serial number changes.

If FortiToken Mobile licenses need to be moved in case of RMA, this is done via a ticket to Fortinet Customer Service; the ticket should include the original and new device's serial numbers, along with the FortiToken license serial number.

If hardware FortiTokens are moved, this can be done by Technical Support through a ticket as well; the ticket needs to include the FortiToken serial numbers in question.

FTK-211 series tokens differ a bit - the seed files are not in Fortinet's possession, but instead stored on a CD that is shipped along with the hardware tokens. Moving the tokens to a new unit requires the CD with seed files.

Note:

FortiGate and FortiAuthenticator devices come with two free trial mobile tokens. These tokens cannot be moved; it is distinguishable in that the associated license number follows the pattern FTMTRIALxxxxxxxxxx.

Process Summary:

1. Determine if the license is eligible for transfer.
2. If eligible, transfer the license/token in Fortinet systems via a support ticket. If not eligible, purchase a new license for use in later steps or consider migration to FortiToken Cloud.
3. Delete the tokens on the old unit.
4. Migrate any user accounts from the old unit to the new unit as appropriate.
5. Activate the tokens on the new unit (add the hardware tokens/supply the mobile token license activation code).
6. Assign tokens to users again (for mobile tokens, they need to be activated in the app again).

FortiGate

Preparation: User Migration.

FortiTokens are usually assigned to local users on FortiGate (with passwords stored locally or on LDAP).

If the migration should also include user accounts, then there are three options:

• If the new model to be migrated to is the same model and firmware version as the old FortiGate (an RMA replacement for example), a configuration backup can be taken from the old unit and simply restored on the new unit. This will recreate all user accounts from the old FortiGate on the new one.
• If the new FortiGate to be migrated to is a different model/firmware version and the full configuration should be migrated, the FortiConverter service may be used: there are one-time uses and subscriptions available for this. More information can be requested from the Fortinet Sales department.
• If only the user accounts should be migrated, they can be extracted from the old FortiGate configuration file as follows:

1. Open the configuration file in a text editor.
2. Copy the whole 'config user local' part.
3. Paste this into a new file.
4. Remove the lines containing 'two-factor' and 'fortitoken' from every user entry.
5. Connect to the new device via CLI.
6. Paste the modified 'config user local' lines: they should be interpreted as proper CLI commands and recreate the local users (including passwords).

Alternatively, to import only the user list, the whole 'config user local' part can be extracted. In a text editor, remove the lines containing 'two-factor' and 'fortitoken' and import them via the CLI.

The usual local user with an assigned token is in the following format:

config user local
    edit "syntest"
        set type password
        set two-factor fortitoken
        set fortitoken "FTKMOB*******"
        set email-to "test@domain.com"
        set sms-phone "+123456789"
        set passwd-time 2019-05-25 22:13:28
        set passwd ENC *******
    next

Note:

The lines with 'two-factor and 'fortitoken' need to be stripped because FortiTokens cannot simply be migrated as part of the FortiGate configuration, due to the license/seeds being bound to the old serial number and needing to be associated with the new serial number first.

Example: Bulk removes two-factor and FortiToken from users with Notepad++.

1. On FortiGate CLI, use this command to list all local users.

config user local
show
<use space until the full table displays>
end

2. Once every local user is listed on the CLI console, download the console file.
3. Open the text file in Notepad++. Use Ctrl+F to open the 'find and replace' window.
4. Unset two-factor:

   In the 'Find what:' field enter: set two-factor fortitoken.
   In the 'Replace' tab on the 'Replace with:' field enter: unset two-factor.

   Select the 'Replace All' button.
5. Remove FortiTokens.

   In the 'Find what:' field enter: set fortitoken '\w+'.
   In the 'Replace' tab on the 'Replace with:' field leave blank.

   Select the 'Replace All' button.

6. Save this file and upload it to FortiGate via script.

On FortiOS GUI, in the top right corner, select the admin user Configuration -> Script -> Run Script -> Upload saved file and select OK.

It might show an error, but the local users will still be applied without the two-factor/FortiToken settings.

This association with the new serial number may fail if the token serial numbers already exist in the new configuration.

Users from FortiAuthenticator cannot be migrated to FortiGate directly: FortiAuthenticator users can only be exported in CSV format, which FortiGate cannot parse. In that case, users will need to be created manually on FortiGate in some manner.

FortiToken Migration.

After the FortiToken licenses have been transferred to the new unit and hardware FortiTokens have been reset (meaning the seeds are marked as available again and can be downloaded by the new FortiGate), the FortiTokens need to be imported into the FortiGate:

1. Delete all Tokens from the old unit: Technical Tip: Deleting FortiTokens from Firewall in bulk

2. Register the EFTM (FortiToken Mobile) license on the new FortiGate to create all related tokens on the new unit. The license needs to be manually added to the FortiGate, after which FortiGuard checks in the background if the added FortiToken license is valid for the FortiGate in question.
   

• Locate the 20-digit code on the redemption certificate for the license: EFTMXXXXXXXX.
• Go to User & Device -> FortiTokens and select 'Create New'.
• Select 'Mobile Token' and enter the 20-digit certificate code in the Activation Code box.
• Select 'OK'.

Registration via FortiGate CLI:

execute fortitoken-mobile import <20-digit activation code>

3. Assign available FortiTokens to the local user accounts as appropriate.

Note:

If mobile tokens are migrated, they will also need to be activated again after (re-)assignment to a user.

FortiAuthenticator.
On the FortiAuthenticator, local users and imported remote users may be associated with FortiTokens. In case of a migration from FortiGate to FortiAuthenticator, it is possible to import users directly from a FortiGate configuration file; FortiAuthenticator creates local user entries for those imported users. After the FortiToken licenses have been transferred to the new FortiAuthenticator and hardware FortiTokens have been reset, Tokens need to be imported into the FortiAuthenticator:

1. Delete FortiTokens from the old unit. In the GUI: Go to Authentication -> User Management -> FortiTokens, select all tokens, and select 'Delete'.

2. Import FortiTokens into the new unit. In case of a migration from FortiGate to FortiAuthenticator, hardware FortiTokens can be imported (with or without their associated users) from a FortiGate configuration file: In the GUI: Go to Authentication -> User Management -> FortiTokens and select 'Import'.

 

When performing a migration from FortiAuthenticator to FortiAuthenticator or for mobile tokens in general, the tokens can be added by selecting 'Create New':

3. Import the users: Users can be imported from a CSV file or the FortiGate config file, or be migrated in whole as part of a FortiAuthenticator configuration.
   

If using a CSV file, it should be in the following format with one record per line: user name (30 characters max), first name (30 characters max), last name (30 characters max), email address (75 characters max), mobile number (25 characters max), password (optional, 128 characters max).

If the optional password is left out of the import file, the user is emailed temporary login credentials and requested to configure a new password.
Note that, even if an optional field is empty, it still must be defined with a comma. In the GUI: Go to Authentication -> User Management -> Local Users and select' Import'.

If a FortiAuthenticator configuration is migrated in full, there can be issues if the tokens that should be migrated remain through the conversion process:

• The tokens would exist in the configuration.
• The new unit is not technically aware that the licenses/tokens are associated with its (new) serial number.
• The new FortiAuthenticator needs to contact the FortiGuard servers to activate licenses and hardware tokens, but it will only do so when those tokens are imported/created from scratch, not for existing ones.
• Activating the license again on the new FortiAuthenticator is required: this should usually not trigger any errors, but if there are some during the license activation, it may be necessary to delete all tokens associated with the license, and THEN activate the license again.

4. Assign and provision Tokens to each user who needs to use two-factor authentication.

This can be done manually by editing each user, or via remote users, this can be done via Remote User Sync Rules (users get imported from LDAP automatically and assigned an available token). As with the FortiGate migration above, (re)assigned mobile tokens will need to be activated in the FortiToken mobile app again.

Related articles:

Technical Tip: Error status on FortiGate Hardtoken

Technical Tip: Hard Token error 'token already activated, and seed won't be returned'

Technical Tip: FortiToken basic troubleshooting

Troubleshooting Tip: How to fix a Licensed Mobile Token with an Error / Locked / Provision Timed Out...

Technical Tip: FortiToken Cloud's basic troubleshooting debugging from FortiGate and FortiAuthentica...

Troubleshooting Tip: FortiGate FortiToken configuration and troubleshooting resource list

Technical Tip: FortiToken Mobile does not support License Transfer