How to migrate domain users
This section describes how to migrate domain users between two domains. The article explains how to move users from domain "A" (internal domain) to domain "B" (SAML domain).
Prerequisites
- An internal domain is configured in S-Filer Portal.
- Have the "sfiler-admin-cli" utility available.
- Have administrator account credentials.
The procedure
There are different approaches to proceed with domain user migration. The procedure described here relies on using the "sfiler-admin-cli" utility. The same result could have been achieved using SQL queries on the database or using the REST API.
Step 1: Create the SAML domain
The first step is to create the SAML domain in S-Filer Portal. To do this, go to the administrative console, click on "Server", and then click on the "Add a new authentication mechanism" button.
IMPORTANT
It is important not to implement SAML domain adoption until the migration is complete. This would complicate user migration.
Step 2: Identify source and destination domains
The best approach to ensure this is to use the "sfiler-admin-cli" utility to list available domains. The "list-domains" command returns the list of available domains.
sfiler-admin.sh -s http://[url]/sfiler/server/ list-domains
sfiler-admin.exe -s http://[url]/sfiler/server/ list-domains
The command output will look similar to this:
--------------------------
| ID | Name |
--------------------------
| 1 | Business Partners |
| 3 | LDAP |
| 4 | OpenID |
| 6 | SAML |
--------------------------
In this example, the "internal" domain is identified by "1" and the "SAML" domain by "6". Make a note of the domain “IDs”, as they will be used in the following commands.
Step 3: Extract users to be migrated
Again, the "sfiler-admin-cli" utility is the best approach to get the list of users to migrate. The commands "list-users" and "list-admins" return the list of users from the source domain.
sfiler-admin.sh -l [admin account] -p [password] -s http://[url]/sfiler/server/ list-users
sfiler-admin.sh -l [admin account] -p [password] -s http://[url]/sfiler/server/ list-admins
sfiler-admin.exe -l [admin account] -p [password] -s http://[url]/sfiler/server/ list-users
sfiler-admin.exe -l [admin account] -p [password] -s http://[url]/sfiler/server/ list-admins
The command output will look similar to this:
List of users
-------------------------------------------------------------------------------------------------------------
| ID | Name | Full Name | Email | Language | Notification | ServiceAccount |
-------------------------------------------------------------------------------------------------------------
| 10 | mjones | Mike Jones | mjones@test.sfiler.com | en | false | true |
| 16 | sflowers | Sonia Flowers | sflowers@test.sfiler.com | en | true | false |
| 9 | sroy | Sebastien Roy | sroy@test.sfiler.com | fr | true | true |
-------------------------------------------------------------------------------------------------------------
Step 4: Execute the migration commands
The migration can be performed by repeatedly calling the "migrate-user" command with the appropriate parameters.
sfiler-admin.exe -l [admin account] -p [password] -s http://[url]/sfiler/server/ --modify-user -d 1 -n mjones -e mjones@test.sfiler.com -rename mjones_2 -domain 6
sfiler-admin.exe -l [admin account] -p [password] -s http://[url]/sfiler/server/ --modify-user -d 1 -n sflowers -e sflowers@test.sfiler.com -rename sflowers_2 -domain 6
sfiler-admin.exe -l [admin account] -p [password] -s http://[url]/sfiler/server/ --modify-user -d 1 -n sroy -e sroy@test.sfiler.com -rename sroy_2 -domain 6
Step 5: Automating the migration for a large number of users
Step 5.1: Build a CSV file with users to migrate
The CSV file structure is as follows:
id,name,email,actual_domain,target_name,target_domain
10,mjones,mjones@test.sfiler.com,1,mjones_2,6
16,sflowers,sflowers@test.sfiler.com,1,sflowers_2,6
9,sroy,sroy@test.sfiler.com,1,sroy_2,6
INFO
The "target_name" column must correspond to how users are found in the target domain. Please consult the documentation of the domain type for the desired domain to determine what the target_name should be.
Step 5.1: Migration script
sfiler-admin.sh -l [admin account] -p [password] -s http://[url]/sfiler/server/ --modify-user -d 1 -n mjones -e mjones@test.sfiler.com -rename mjones_2 -domain 6
sfiler-admin.sh -l [admin account] -p [password] -s http://[url]/sfiler/server/ --modify-user -d 1 -n sflowers -e sflowers@test.sfiler.com -rename sflowers_2 -domain 6
sfiler-admin.sh -l [admin account] -p [password] -s http://[url]/sfiler/server/ --modify-user -d 1 -n sroy -e sroy@test.sfiler.com -rename sroy_2 -domain 6
sfiler-admin.exe -l [admin account] -p [password] -s http://[url]/sfiler/server/ --modify-user -d 1 -n mjones -e mjones@test.sfiler.com -rename mjones_2 -domain 6
sfiler-admin.exe -l [admin account] -p [password] -s http://[url]/sfiler/server/ --modify-user -d 1 -n sflowers -e sflowers@test.sfiler.com -rename sflowers_2 -domain 6
sfiler-admin.exe -l [admin account] -p [password] -s http://[url]/sfiler/server/ --modify-user -d 1 -n sroy -e sroy@test.sfiler.com -rename sroy_2 -domain 6
However, it is possible that the users to be migrated are not in the "internal" domain (usually domain "1") and that it is necessary to assign them a new user name. In this case, you need to carry out the two-step procedure:
- Migrate users from the source domain to the internal domain.
- Migrate users from the internal domain to the target domain, specifying the new user name.
This procedure is necessary because it is not possible to change the name of a user in a domain other than the internal domain.
However, it's likely that the number of users to migrate will be significant. It is therefore recommended to automate the migration using a script. Here's an example script for Windows:
@echo off
setlocal EnableDelayedExpansion
if "%~1"=="" (
echo Usage: migrate-users.bat [csv_file]
echo CSV file must have the format: id,name,email,actual_domain,target_name,target_domain
exit /b 1
)
:: Skip the header line and process each line of the CSV
for /f "skip=1 tokens=1-6 delims=," %%a in (%~1) do (
echo Migrating user: %%b / %%c from domain %%d to domain %%e
sfiler-admin.exe -l sfiler-master -p Passw0rd -s "http://localhost:8080/sfiler/server/" modify-user -d %%d -n %%b -e %%c -rename %%e -domain 1
sfiler-admin.exe -l sfiler-master -p Passw0rd -s "http://localhost:8080/sfiler/server/" modify-user -d 1 -n %%e -e %%c -domain %%f
if !errorlevel! neq 0 (
echo Error migrating user %%b
) else (
echo Successfully migrated user %%b to %%f
)
)
echo Migration complete
Step 6: Verify the migration
The migration is complete when users have been migrated to the SAML domain. It is recommended to verify that users have been migrated by logging into the web console with an administrator role.
Step 7: Implementing domain adoption
To simplify the authentication process, it is recommended to implement SAML domain adoption. To do this, go to the administrative console and set up the necessary configuration for the SAML domain. You can find the documentation to perform this operation in the section on Configuring the adoption source.