Description
This article describes the necessary procedure to migrate FortiTokens (hardware and mobile) to a new FortiGate or FortiAuthenticator.
Possible scenarios for user and Token migrations include the following examples:
- Switching to a different FortiGate.
- RMA replacement of a failed unit.
- Migrating two factors authentication from FortiGate to FortiAuthenticator.
Solution
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.
In any situation where tokens are moved to another unit, the Token license (Mobile Tokens) or Token seed (Hardware Tokens) needs to be transferred and manually added to the new unit.
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, this is done via a ticket to Fortinet Customer Service; the ticket should include the old and new device's serial numbers, along with the FortiToken license serial number itself.
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. To move the tokens to a new unit requires the CD with seed files.
Note:
FortiGates and FortiAuthenticators come with two free trial mobile tokens. These tokens cannot be moved; it is distinguishable in that the associated license looks something like FTMTRIALxxxxxxxxxx.
FortiGate.
Preparation: User Migration.
FortiTokens are usually assigned to local users on FortiGate (with password 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's configuration file as follows:
- Open the configuration file in a text editor.
- Copy the whole 'config user local' part.
- Paste this into a new file.
- Remove the lines containing 'two-factor' and 'fortitoken' from every user entry.
- Connect to the new device via CLI
- 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 remove two-factor and fortitoken from users with Notepad++:
- On FortiGate CLI, use this command to list all local users.
config user local
show
<use space until the full table displays>
end
- Once every local user listed on CLI console, download the console file.
- Open the text file in Notepad++. Use Ctrl+F to open “find and replace” window.
- Unset two-factor:
In the 'Find what:' field enter: set two-factor fortitoken
And select the 'Replace All' button.
In the 'Replace' tab on the 'Replace with:' field enter: unset two-factor - Remove fortitokens.
In the 'Find what:' field enter: set fortitoken '\w+'
In the 'Replace' tab on the 'Replace with:' field leave blank.And select the 'Replace All' button.
- Save this file and upload it to FortiGate via script.
On FortiOS GUI, on 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:
- Delete all Tokens from the old unit. In the GUI, go to User&Device -> FortiTokens, select 'all Mobile Tokens', and select the 'Delete' button.
- 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'.
- 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:
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:
- Delete FortiTokens from the old unit. In the GUI: Go to Authentication -> User Management -> FortiTokens, select all tokens, and select 'Delete'.
- 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':
- Import the users: Users can be imported from a csv file or from 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 (it can be converted by Technical Support to match a new FortiAuthenticator model, though it will be the same firmware version), 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.
- 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 for remote users, this can be done via Remote User Sync Rules (users get imported from LDAP automatically and assigned an available token). As with FortiGate migration above, (re)assigned mobile tokens will need to be activated in the FortiToken mobile app again.
The entire process boils down to roughly these steps:
- Migrate the license/token in Fortinet systems (this is done via a support ticket).
- Delete the tokens on the old unit.
- Migrate any user accounts from the old unit to the new unit as appropriate.
- Activate the tokens on the new unit (add the hardware tokens/supply the mobile token license activation code).
- Assign tokens to users again (for mobile tokens, they need to be activated in the 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: FortiGate FortiToken configuration and troubleshooting resource list
