17. Moving Accounts from an Old System

Scenario: the company is replacing its old authentication system with rradius. The old system might be an old RADIUS server, an LDAP directory, mail server accounts, or some home-grown database. It holds a few thousand accounts, all with hashed passwords, and nobody knows the plain text.

  • Nobody should have to reset their password. Bring the old system’s hashes over as they are, and users keep logging in with their existing passwords.
  • The old hashes are mostly weak (MD5, SHA-1). Once moved, a password change stores a new format, and the old formats gradually disappear.
  • The old system’s account names vary in case and some carry a domain; they need to be made consistent.

If the old LDAP directory is staying, there is no need to move anything: let rradius ask the directory directly (chapter 5). This chapter is about putting accounts into rradius’s own tables.

Example directory: rradius-server/examples/scenarios/migrate-users/

FileContents
rradius.tomlThe sql handler, name normalisation, [accounts]
migrations/1_schema.sqlusers (with an extra origin column recording the source), user_reply, accounting
migrations/2_imported_users.sqlEight demo accounts, each in a different old format

How it works

The user_query of the sql handler returns the password column. The start of the password column says what it is, with {format}:

{SSHA}ZvqZAfdyjd1PQiq8rurmdodN8ihkZW1vc2FsdA==
{crypt}$1$demosalt$EhA8qeu4qSun8gh9DajmS1
{nthash}9d232eea31049319fc8ab84300855a34

At login, rradius uses the algorithm named by the prefix to compute the password the user typed once, and compares it with the stored value. So one table can mix any formats, one per account.

Steps

cd rradius-server
./target/release/rradius-server --config examples/scenarios/migrate-users/rradius.toml

For local testing, change the address of nas to 127.0.0.1. The demo accounts’ passwords are all “account-password”:

S=nas-shared-secret-change-me
radtest ldap1 ldap1-password 127.0.0.1 0 $S     # {SSHA}
radtest shell1 shell1-password 127.0.0.1 0 $S   # MD5-crypt under {crypt}
radtest mail1 mail1-password 127.0.0.1 0 $S     # {NS-MTA-MD5}
radtest 'EXAMPLE\LDAP1@example.com' ldap1-password 127.0.0.1 0 $S   # the name is first normalised to ldap1

All of them get an Access-Accept.

Which format old data maps to

What it looks like in the old systemStore asDemo account
LDAP userPassword already of the form {SSHA}..., {SSHA512}..., {SHA}..., {MD5}..., {SMD5}...Copied as isldap1, ldap2
OpenLDAP’s {PBKDF2-SHA256}rounds$salt$hash (also -SHA1, -SHA512)Copied as isldap3
{X-PBKDF2}HMACSHA2+256:rounds:salt:hashCopied as isldap4
The second field of /etc/shadow ($1$..., $5$..., $6$..., $2b$...)Prefixed with {crypt}shell1
LDAP’s {CRYPT}$6$...Copied as is (the prefix ignores case)
An old mail server’s {NS-MTA-MD5}...Copied as ismail1
Hexadecimal MD5, SHA-1 or SHA-256 in a database (unsalted)Converted to Base64, prefixed with {MD5}, {SHA} or {SHA256}old1
NT hash (32 hexadecimal characters)Prefixed with {nthash}win1
argon2’s $argon2id$...Prefixed with {argon2}
Plain textAs is; add {clear} when the value itself starts with {

Hexadecimal to Base64: old databases often store hashes as hexadecimal strings, while rradius’s {MD5} and {SHA} kind need Base64:

printf '%s' 91f881a968b893e4092eca12a52293ef | xxd -r -p | base64
# kfiBqWi4k+QJLsoSpSKT7w==     →  store as {MD5}kfiBqWi4k+QJLsoSpSKT7w==
  • For salted hashes, the salt goes after. The {SSHA} kind is “hash followed by salt”, Base64-encoded together, computed as hash(password + salt). When the old system computes hash(salt + password), or mixes them some other way, there is no matching format, and those accounts can only have their passwords reset.
  • When unsure, try first with a test account whose password you know. A value in the wrong format never matches and lets nobody in, so trying is safe.
  • The full list of formats is in usage section 5.

What can and cannot be moved

Hashes only work with login methods that send the plain-text password to the server.

Login methodCan it use hashes?
PAP (VPN, the web logins of most NAS, TACACS+ PAP and ASCII)Every format
EAP-TTLS with inner PAP (Wi-Fi)Every format
CHAP (common for PPPoE)Plain text only
MS-CHAPv2, PEAP (the most common Wi-Fi user name and password method)Plain text or {nthash} only

So:

  • When the old system stored NT hashes, moved accounts can use PEAP directly (the demo win1).
  • When the old system has only other hashes and Wi-Fi must use user names and passwords, there are two ways: switch Wi-Fi to EAP-TTLS with inner PAP (operating system support varies, so check first); or ask users to change their password once, storing it as {nthash} at that point (see below).
  • PPPoE with CHAP cannot work without plain text; only a reset helps.

The automated test checks that all eight demo accounts can log in with PAP, and that the {SSHA} account is rejected with CHAP.

Importing

Turn the data exported from the old system into a migration file:

-- 2_imported_users.sql
INSERT INTO users (username, password, origin) VALUES
  ('ldap1', '{SSHA}ZvqZAfdyjd1PQiq8rurmdodN8ihkZW1vc2FsdA==', 'ldap'),
  ('shell1', '{crypt}$1$demosalt$EhA8qeu4qSun8gh9DajmS1', 'shadow');
  • Have the file ready before the first start. A migration file cannot change once applied; to add accounts later, add a file with the next number.
  • Lowercase account names and remove domains first, consistent with the normalisation settings below.
  • In SQL strings, single quotes are written twice. When a program generates this file, remember to handle quotes in names and hashes.
  • The origin column is not required; the example uses it to record where each account’s password came from, so you can later count how many old formats remain.
  • When the file is large (hundreds of thousands of rows), the import takes a while; raise [cluster] migrations_wait_ms above the import time, see usage section 2.5.
  • The exported file holds everyone’s password hashes, and weak hashes can be cracked offline. Protect it in transit and at rest, and delete temporary copies after the import. The same goes for the migration file itself.

You can also add accounts one by one with user add instead of a migration file, but it only accepts plain-text passwords (which it hashes itself), so it cannot be used to move existing hashes.

Inconsistent names

[auth.username]
strip_realm = "both"
lowercase = true

Users of the old system are used to typing EXAMPLE\ldap1, ldap1@example.com or LDAP1. This setting turns all of them into ldap1 before the account lookup: first it removes everything up to the last backslash, then everything after the last @, and finally lowercases.

  • Names in the table must be lowercase first. Otherwise the row Alice is never found.
  • Two accounts that differed only in case become one. Find and resolve them before importing.
  • Be careful with forwarding by realm ([proxy]): names with @ are matched against realms first, and those that match are forwarded and never get here.

Replacing the old formats

[accounts]
scheme = "bcrypt"
passwd = "UPDATE users SET password = ?2, origin = 'rradius' WHERE username = ?1"
rradius-server user passwd --config rradius.toml mail1    # asks for the new password twice

user passwd stores the new password in the format set by scheme, replacing the old hash; the example also changes origin to rradius.

  • Which scheme: for PAP only, the default bcrypt (sha512-crypt with very high login volumes); for PEAP and MS-CHAPv2, nthash; for CHAP, only clear. See chapter 19.
  • rradius does not replace old hashes automatically at login, and has no interface for users to change their own password. An administrator, or your portal, has to call user passwd (with the password on standard input).
  • Seeing how many remain: user show <account> prints that account’s origin. rradius has no command that queries the whole table; to count, you could occasionally compute it with sql_query in the accounting script and write it to the log with log() (this chapter does not include such a script).
  • Set a deadline. For accounts that have not changed their password by then, set the password to NULL with a migration file (accounts whose password column is NULL can never log in), and ask them to have an administrator reset it.

Before going live

  • Run both side by side for a while first. Point a few NAS at rradius and leave the rest on the old system; switch over completely once the login results agree.
  • Reply attributes from the old system (VLAN, rate, privilege) need moving too, into user_reply (chapter 2). Attribute names must be names in rradius’s dictionary, and a value in the wrong format makes the login fail, so after moving, actually log in with a few accounts rather than relying on --check.
  • The old system’s shared secrets can be kept, so the NAS only need the server address changed. Better still, use this chance to make them long and different per device.
  • Verifying {crypt} and {argon2} is deliberately slow, so many logins at once queue. The same goes for PBKDF2 with a high round count.
  • Not tested: an actual export and import from any particular old system. The demo hashes were computed from each format’s definition with Python’s hashlib and openssl passwd, and the scenario test confirms rradius verifies them; the project has also tested the PBKDF2 formats with values produced by a real OpenLDAP.

Common problems

SymptomCause
A moved account is rejected with the right passwordThe wrong prefix (a hexadecimal MD5 with {MD5} added but not converted to Base64, for example); the salt is in a different position from the format’s definition; or the hash was truncated or picked up whitespace during the import
Only accounts whose names have capitals cannot log inlowercase is on, but the names in the table were not lowercased
PAP works, Wi-Fi PEAP does notPEAP needs plain text or {nthash}; other hashes cannot do it
PAP works, PPPoE CHAP does notCHAP needs plain text
Names with @ get no reply or are forwardedThey match a realm in [proxy] and went to an upstream
Slower at login peaksbcrypt, argon2 or PBKDF2 with many rounds are queueing. Switch to sha512-crypt when passwords change, or accept the speed
migration file ... changed after it was applied at startupAn import file already applied was changed. To add data, add a file with the next number
Built with Hugo
Theme Stack designed by Jimmy