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.

bash

sfiler-admin.exe -l [admin account] -p [password] -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.

bash

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: 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 match the "subject" in the target domain. If it does not exist, the authentication will fail. In a lot of cases, the "subject" matches the user email. But that's not always the case.

Step 5: Execute the migration command

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

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:

bash

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