Skip to content

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.

shell
sfiler-admin.sh -s http://[url]/sfiler/server/ list-domains
shell
sfiler-admin.exe -s http://[url]/sfiler/server/ list-domains

The command output will look similar to this:

text
--------------------------
| 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.

shell
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
shell
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:

text
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.

bash
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:

csv
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

shell
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
shell
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:

  1. Migrate users from the source domain to the internal domain.
  2. 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:

shell
@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.