Migrating Accounts, Permissions, and Home Directories
The first ticket after a cutover is nearly always about an account. "Login failed." "Permission denied on the rename; the upload worked." Or the one that empties the room: "we can see a folder called harlow, and we are not Harlow." Every other layer, done well, is invisible. An account done badly is a partner on the phone at two in the morning. The account list looks like the easiest thing to move. It has the most translation in it.
A transfer account is the bundle of username, authentication method, home directory, rights, and limits that a partner or a job logs in as. This article moves that bundle end to end. It covers what exports and what does not, why password hashes cannot follow you, and the three strategies that replace them. It covers translating one permission model into another and keeping the partner's view of "/" identical. It also covers the isolation test you run as every account before cutover. It is part of our Platform Migration Mechanics series. It builds on the layer map in what actually moves in a platform swap. The mechanics are the same whichever product you are leaving or arriving at. Partner notice belongs to partner coordination; this article stays on the server side of the line.
What an Account Really Contains
A transfer account is not a username and a password. On most platforms it is a bundle of a dozen fields, and each has to land somewhere on the new side.
- Username — must survive letter for letter, including case; partner scripts you will never see have it embedded.
- Authentication method — password, public key, or both. "Both" comes in two flavors: either works, or both are required. Preserve the flavor, or key-only partner jobs will start prompting for a password nobody has.
- State — enabled, disabled, expiring. Disabled accounts still exist for a reason; find out why before leaving them behind.
- Home directory and permissions — the physical path, how it looks from the partner's side, and what the account may do in each folder.
- Protocols — SFTP only, FTPS only, any. A partner limited to SFTP today should not gain plain FTP on the new platform by default.
- Limits and restrictions — concurrent sessions, bandwidth caps, quotas, allowed source addresses.
- Metadata — owner, partner contact, ticket reference, the flow it belongs to.
How much of this the old platform will hand you varies enormously. Some products export the list as XML, JSON, or CSV. Some export a configuration file that includes the password hashes (a secret to handle carefully, and useless for login). Some have no export at all. The fields are read off screens one account at a time, which is exactly as much fun as it sounds. Whatever the mechanism, the export says only what the old platform was configured to do. The activity logs say what actually happened: who logged in during the last ninety days, from where, over which protocol. An account with no login in a year is a candidate for retirement rather than migration. The article on finding stale and orphaned accounts makes that case. The verdict belongs in the migration inventory.
The account migration worksheet
Build one row per account from the export and the logs together. The worksheet is what you build the new platform from and check it against afterward.
ACCOUNT WORKSHEET -- sftp-old.example.com -> sftp-new.example.com
username owner/partner auth last login proto home rights (neutral) secret plan status verified
-------- -------------- ---------- ----------- ----- ------------------- ---------------------------------- ------------ -------- --------
bayside Bayside ops password Mar 09 02:11 SFTP /partners/bayside inbox: list,write,rename,delete temp pw OOB created __
outbox: list,read
harlow Harlow Logist. key (2) Mar 09 23:40 SFTP /partners/harlow inbox: list,write,rename keys carried created __
outbox: list,read
kestrel Kestrel Bank key+pw req Mar 08 17:05 FTPS /partners/kestrel drop: write only (no list) both: keys + created __
outbox: list,read temp pw OOB
erp-svc internal ERP password Mar 09 04:15 SFTP /internal/erp all folders: list,read,write,delete directory mapped __
old-vend (unknown) password none in 1yr FTP /partners/old-vend inbox: list,write RETIRE n/a n/a
Two columns carry the article. Rights (neutral) says what the account can do in platform-free words and feeds the permission translation. Secret plan records which password strategy applies. Nothing goes in verified until the isolation test has run as that account.
Why Password Hashes Cannot Follow You
The old platform never stored your partners' passwords. It stored a hash of each one: the output of a one-way function, mixed with a random salt. The password cannot be recovered from that hash. At login it hashes what the partner typed the same way and compares. That is how every responsible platform works, and it is why the secret cannot move. The new platform would have to run the identical function with identical salt handling and storage encoding. Platforms choose those independently. Even two products using the same algorithm wrap it differently, and no import path exists.
Two temptations follow, and both should be refused. The first is to recover passwords by attacking your own hashes: slow, unreliable, and an attack on secrets your partners may reuse elsewhere. The second is to ask partners to "tell us your current password so we can set it up". That trains them to hand credentials to whoever asks. (Someone else will ask eventually, and they will not be migrating anything.) A new secret must be made properly, to the standard in our password policy for transfer accounts.
Three Strategies for the Secret
Every password account on the worksheet gets one of three plans. Most migrations use two at once, one for internal accounts and another for partners.
| Strategy | How it works | Partner effort | Best for |
|---|---|---|---|
| Coordinated reset | The partner sets their own new password through a self-service mechanism (an HTTPS portal, a reset link) during their test window | One action, at a time they choose; you never know the secret | Platforms with a web portal; partners with a human operator |
| Temporary password, out of band | You generate a strong random password per account and deliver it through the channel already trusted for that partner; it expires if unused and is changed at first login where the platform can enforce that | Update the credential in their job before cutover | Unattended partner automation; SFTP- and FTPS-only accounts with no portal |
| Directory-integrated authentication | The server holds no secret; it passes each login to a directory (Windows, Active Directory, LDAP) for verification, so the existing directory password keeps working | None for accounts that already exist in the directory | Internal users, service accounts, and partners you are willing to hold directory identities for |
One detail decides between the first two: the transfer protocols have no password-change operation. SFTP and FTP give a client no standard way to set a new password. So "forced change at first login" is only possible when the platform offers a web portal or another channel for it. For a partner who only ever connects with an unattended SFTP job, a temporary password quietly becomes the permanent password. Plan for that: make it as strong as a permanent one and record the delivery. The channel matters more than the password. Use the one established during onboarding, as in partner credentials and security, never a fresh email to whoever replied last. The article on credential issuance and first login has the delivery mechanics.
The third strategy is the structural fix. A server that authenticates against a directory stores nothing a future migration needs to carry. The next platform is pointed at the same directory and every account keeps its secret. A Windows target such as Sysax Multi Server authenticates accounts against Windows and Active Directory. Equivalent LDAP integration exists across platforms. The tradeoff is where partner identities live. Internal users and service accounts already have them; for those it is pure gain. Partners do not, and creating directory accounts for external organizations is a policy decision. It involves their own organizational unit, a group that grants only transfer access, and log-on restricted to the transfer server. Many estates run directory authentication for everything internal and local accounts with out-of-band temporary passwords for partners. That is a perfectly good answer. The article on authentication methods compared has the wider view.
Remember: you cannot migrate a secret you do not know, and by design you do not know it. Every password account needs a deliberate secret event: a self-service reset, an out-of-band temporary password, or a move to directory authentication. The worksheet records which. A blank secret plan is an account that will fail on cutover night.
Key-Based Accounts Move Easily
Accounts that authenticate with SSH public keys are the pleasant exception. A partner's authorized key is public by design: one line of text (key type, encoded key data, optional comment). It lets the server recognize the partner's private key without seeing it. It works on any SSH server that supports the key type, so it copies.
- Export each account's authorized keys from the old platform. Depending on the product, these are in a per-user file, a field in the account record, or a paste box in the admin interface.
- Record each key's fingerprint (
ssh-keygen -lf keyfile) beside its username on the worksheet. The fingerprint is how you confirm the right key landed on the right account. - Import into the new platform in whatever form it wants, then list the fingerprints there and compare.
- Check key-type support before cutover. A key type the new platform refuses fails with an unhelpful "authentication failed." A partner needs weeks, not hours, to send a replacement.
Two things do not copy. Per-key restrictions (limiting a key to certain source addresses or commands) may have no equivalent on the new platform. They should become per-account IP allow lists where possible. And "key and password" keeps that requirement only if the new platform can express it; check rather than assume. The host-key decision that affects every key-based partner is in migrating keys and certificates. Day-to-day handling is in distributing authorized keys.
Meridian Parts found out what "check rather than assume" costs. On the old platform their account accepted a key or a password. On the new one the administrator ticked both boxes, which there meant both required. Meridian's nightly job presented its key, was asked for a password it had never owned, and failed. Its retry logic tried again every fifteen minutes all weekend, with great persistence and no success. Monday's ticket said "login failed", which was true and not helpful. The fix was one click. Finding it took a morning.
Translating the Permission Model
Permissions are the layer most likely to look identical and behave differently. Platforms enforce them in one of three ways; first identify which way each of yours uses.
- Operating-system enforcement. The service impersonates the account and lets the file system decide — NTFS access control lists on Windows, owner/group/other bits on Unix-like systems.
- Server-level virtual permissions. The service runs as one identity and applies its own per-account, per-folder flags: list, read, write, delete, rename. The file system never sees the partner.
- Hybrid. Virtual folders map physical paths into the partner's view, with server-level flags layered on top of whatever the file system allows.
Moving between two of these is where the neutral vocabulary earns its keep. Write each account's rights as the worksheet does (list, read, write, overwrite, append, delete, rename, mkdir, rmdir). Then translate each word, because each hides a trap.
| Neutral right | What partners use it for | Translation gotcha |
|---|---|---|
| Rename | The upload-as-.tmp-then-rename convention that keeps downstream jobs from reading partial files |
A separate flag on virtual-permission platforms; requires delete-plus-create (typically "Modify") under OS enforcement. Miss it and every partner upload "succeeds" then fails at the last step |
| Overwrite vs create-only | Re-sending a corrected file under the same name | Some platforms treat re-upload as overwrite, others refuse it; a partner's retry logic was written for one behavior |
| Append | Resuming an interrupted large upload | Bundled with write on one platform and a distinct flag on another; without it, every resume attempt fails and large uploads restart from zero |
| Write without list | A drop box: partners can deposit but not see what others deposited | Not every platform can separate the two; if the new one cannot, per-partner subfolders replace the shared drop box |
| Delete | Clearing an outbox after download; removing a bad upload | Delete-a-file and delete-a-folder are one right on some platforms and two on others; folder deletion is usually the one to withhold |
| Mkdir and inheritance | Partners creating dated subfolders | Under OS enforcement, a new folder inherits its parent's rules; under virtual permissions it may inherit nothing until an administrator adds a rule |
The background is in permission models explained and umask and inheritance gotchas. The migration rule is narrower: translate rights per account from the neutral column, never by finding a "similar profile" on the new platform. Never grant a broader right to make a translation easier. A migration is when least privilege is most tempting to abandon and matters most, as least privilege in practice argues. "Full control, just for the migration" has a way of outliving the migration.
Home Directories: What the Partner Sees as "/"
Every partner account is jailed, confined to its home directory so that, from the partner's side, that directory is the root of the world. The physical location can change freely (/srv/sftp/bayside on the old server, D:\transfers\partners\bayside on the new) but the view must not. A script that uploads to /inbox/manifest.csv must still find /inbox at the root, not /bayside/inbox. Platforms with per-account home directories and permissions, as Sysax Multi Server configures on the account itself, make the view a setting. Platforms that jail at the OS level make it a matter of where the jail root points. Either way, verify it by logging in as the partner and typing pwd. I have skipped that step once. Every partner landed one level too high, with a fine view of each other's folder names.
Three view-level differences bite when the operating system changes underneath.
- Case sensitivity. A Unix-like file system treats
Report.csvandreport.csvas two files; Windows treats them as one. Moving to case-insensitive, two files differing only in case collide during the copy. Moving the other way, a partner script that typedREPORT.CSVfor a file namedreport.csvstops working. It silently relied on the old platform's forgiveness. - Shared folders. Two partners sharing one folder were served on the old platform by a symbolic link, a junction, a virtual folder, or a mount. The new platform needs its own equivalent, inside each partner's jail without breaking it. A link that escapes the jail is an isolation hole, not a feature.
- Path length and characters. Long or punctuation-heavy names legal on one file system may exceed limits or hit reserved characters on another. Check a listing of the old tree against safe characters across platforms.
Verifying Isolation on the New Platform
The last step turns "configured" into "verified", and it is run as every account, not a sample. The isolation test asks one question from inside the partner's jail: can this account see or touch anything it should not? Script it with the standard command-line SFTP client in batch mode. The client stops at the first failing command unless that command is prefixed with a hyphen. The probes supposed to fail get the hyphen; the transcript shows whether they did.
# isolation.batch -- run once per account (sftp ignores full-line comments): # sftp -b isolation.batch bayside@sftp-new.example.com > bayside.txt 2>&1 # expect: / pwd # expect: only inbox/ and outbox/ listed ls -la / # expect: still at / afterwards (the next pwd proves it) -cd .. pwd # expect: FAILS -- no such path from inside the jail -ls /partners/harlow -ls ../harlow -get /partners/harlow/outbox/x.txt # expect: FAILS -- no write at the root or above it -put probe.txt /probe.txt -put probe.txt ../probe.txt # expect: succeeds (write right), then succeeds (rename right) put probe.txt inbox/probe.txt rename inbox/probe.txt inbox/probe.done # expect: FAILS -- outbox is read-only for the partner -put probe.txt outbox/probe.txt # expect: succeeds only if delete was granted -rm inbox/probe.done quit
Read the transcript against the expectations, then file it. Every line that should have failed and did is evidence of isolation. Every line that should have succeeded and did is evidence the rights translated. A jail-escape probe that succeeded stops the migration for that account until it is fixed. A partner who can list another partner's folder is a breach waiting for a curious operator. FTPS accounts get the same probes through a scripted FTP client, the HTTPS portal a manual pass. The transcripts join the evidence pack in migration validation and rollback. Keep the batch file after cutover. It is the regression test for every future permission change (see regression testing transfer jobs).
Gotcha: the two probes most often skipped are the rename and the write-to-outbox. Rename failures do not appear until the first real partner upload, because test uploads rarely follow the temp-name convention. A writable outbox looks harmless until a partner's script overwrites the file you were delivering to them.
Wrapping Up: Names Stay, Secrets Restart, Rights Translate
The account layer moves in three motions. Names and settings are re-entered from the worksheet. Secrets restart, because hashes never travel. That means a self-service reset, an out-of-band temporary password that may become permanent, or directory authentication. Key-based accounts carry over as public data. Rights translate through a neutral vocabulary, one account at a time. Nothing is marked verified until the isolation test has run as that account. Do it this way and the first ticket after cutover will be about something else. That is the most an account layer can hope for.
The identity side of the same accounts continues in migrating SSH keys and TLS certificates. It covers the host key every partner has pinned and the certificates behind FTPS and HTTPS. The folders they land in, and the live files inside, are in migrating folder structures and in-flight files. On the night, each account's first real login is a line in the cutover runbook.
Frequently Asked Questions
The old server's export file contains the password hashes. Can't the new server just use them?
Can partners change a temporary password themselves over SFTP?
Does directory authentication mean partners need accounts in our Active Directory?
What is the most common permission mistake after a migration?
From the Sysax team: we build secure file transfer software for Windows. Sysax Multi Server is an FTP, FTPS, SFTP, and HTTPS server. Sysax FTP Automation handles scheduled, scripted transfers. Free trials are on the download page.