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/
| File | Contents |
|---|---|
rradius.toml | The sql handler, name normalisation, [accounts] |
migrations/1_schema.sql | users (with an extra origin column recording the source), user_reply, accounting |
migrations/2_imported_users.sql | Eight 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\[email protected]' 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 system | Store as | Demo account |
|---|---|---|
LDAP userPassword already of the form {SSHA}..., {SSHA512}..., {SHA}..., {MD5}..., {SMD5}... | Copied as is | ldap1, ldap2 |
OpenLDAP’s {PBKDF2-SHA256}rounds$salt$hash (also -SHA1, -SHA512) | Copied as is | ldap3 |
{X-PBKDF2}HMACSHA2+256:rounds:salt:hash | Copied as is | ldap4 |
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 is | mail1 |
| 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 text | As 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 ashash(password + salt). When the old system computeshash(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 method | Can 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
origincolumn 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_msabove 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, [email protected] 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
Aliceis 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 defaultbcrypt(sha512-cryptwith very high login volumes); for PEAP and MS-CHAPv2,nthash; for CHAP, onlyclear. 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’sorigin. rradius has no command that queries the whole table; to count, you could occasionally compute it withsql_queryin the accounting script and write it to the log withlog()(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
NULLwith a migration file (accounts whose password column isNULLcan 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
hashlibandopenssl 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
| Symptom | Cause |
|---|---|
| A moved account is rejected with the right password | The 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 in | lowercase is on, but the names in the table were not lowercased |
| PAP works, Wi-Fi PEAP does not | PEAP needs plain text or {nthash}; other hashes cannot do it |
| PAP works, PPPoE CHAP does not | CHAP needs plain text |
Names with @ get no reply or are forwarded | They match a realm in [proxy] and went to an upstream |
| Slower at login peaks | bcrypt, 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 startup | An import file already applied was changed. To add data, add a file with the next number |