Scenario:
- The VPN gateway logs users in with their company directory (Active Directory or OpenLDAP) user name and password. Only members of the
vpn-usersgroup may connect; IT staff and contractors get different access rules by group, and contractors stay connected for at most 8 hours. - The jump host (SSH with pam_radius, or any other system that supports RADIUS) asks for the password and then for the 6-digit code (TOTP) from an authenticator app on the phone.
Each kind of device uses its own named chain: the client’s auth = "name" decides which.
Example directory: rradius-server/examples/scenarios/remote-access/
| File | Contents |
|---|---|
rradius.toml | The two chains, vpn and mfa |
ldap.secret | Password of the directory service account (demo value) |
migrations/1_schema.sql | mfa_users and mfa_pending for the codes, and accounting |
migrations/2_demo_data.sql | Jump host account ops1, code key JBSWY3DPEHPK3PXP |
The jump host script is the repository’s examples/two-step-totp.lua; accounting reuses accounting.lua from the quick start.
VPN: the LDAP chain
[auth.chains.vpn]
policy = "first_match"
[[auth.chains.vpn.handlers]]
type = "ldap"
urls = ["ldaps://dc1.corp.example.com", "ldaps://dc2.corp.example.com"]
bind_dn = "CN=svc-radius,OU=Service Accounts,DC=corp,DC=example,DC=com"
bind_password_file = "ldap.secret"
base_dn = "OU=People,DC=corp,DC=example,DC=com"
filter = "(&(sAMAccountName={user})(!(userAccountControl:1.2.840.113556.1.4.803:=2)))"
password_check = "bind"
required_groups = ["CN=vpn-users,OU=Groups,DC=corp,DC=example,DC=com"]
- The flow: bind as the service account, find the user with
filter({user}is escaped), then bind once more with the user’s DN and password to check the password. Not found means skip (pass to the next handler); more than one match means reject. urlsare tried in order, moving to the next only when a server cannot be reached or times out. A server that answers with an error (a wrong service account password, for example) rejects at once without trying the next, so service account problems show up immediately.filterexcludes disabled accounts: the example above is for AD. OpenLDAP can use(&(uid={user})(!(pwdAccountLockedTime=*))), depending on how the directory is set up; check it against your own directory first.required_groups: people not in the group are rejected just like a wrong password. By default the user’smemberOfis used; when the directory has nomemberOf, search for groups withgroup_base_dnandgroup_filterinstead, see usage section 3.5.ldaps://or StartTLS.ldap://upgrades with StartTLS automatically; when the directory certificate is not signed by a CA the system trusts, setca_file. Plain-text LDAP also needsallow_plaintext = trueand is not recommended.password_check = "bind"supports only PAP. The VPN gateway must send the password with PAP (RADIUS encryptsUser-Password). To support CHAP, MS-CHAPv2 or PEAP, usepassword_check = "attribute"to read a password attribute, which requires the directory to store plain text or NT hashes.
[[auth.chains.vpn.handlers.group_reply]]
group = "CN=it-staff,OU=Groups,DC=corp,DC=example,DC=com"
attributes = { "Filter-Id" = "vpn-it" }
[[auth.chains.vpn.handlers.group_reply]]
group = "CN=contractors,OU=Groups,DC=corp,DC=example,DC=com"
attributes = { "Filter-Id" = "vpn-contractor", "Session-Timeout" = "28800" }
- A user gets the attributes of each group they belong to. The VPN gateway must have a filter or group policy of the same name, and the attribute names depend on the gateway (some use
Class, some vendor attributes). reply_attributescan turn the user’s own LDAP attributes into RADIUS attributes, such as a fixed IP per person.
[auth.chains.vpn.username]
strip_realm = "both"
lowercase = true
Users may type CORP\alice or alice@corp.example.com; the directory lookup uses alice for both. Named chains do not inherit [auth.username]; it has to be written under each chain.
Testing the VPN chain
The LDAP addresses in the example are made up; replace them with your own directory to test:
radtest alice 'her-password' 127.0.0.1 0 vpn-gw-shared-secret-change-me
(For local testing, change the address of vpn-gw to 127.0.0.1.) The authentication log’s handler is ldap. The log does not distinguish reasons for a reject (a wrong password and not being in the group look the same). Directory problems get a line of their own: an unreachable server or timeout is a WARN auth ldap handler: <URL>: <error> (the next server is tried); an error from the directory, such as a wrong service account password, is an ERROR auth ldap handler: <URL>: <error>; rejecting. When there is no such message and the cause is still unclear, first use ldapsearch with the service account to look up the user and their memberOf.
Jump host: password plus TOTP
[auth.chains.mfa]
policy = "first_match"
[[auth.chains.mfa.handlers]]
type = "lua"
script = "../../two-step-totp.lua"
The flow:
jump host ── Access-Request (user, password) ──────────► rradius checks the password
◄─ Access-Challenge (State, "Enter your code")
user types the code
jump host ── Access-Request (user, code, State) ───────► rradius checks the TOTP
◄─ Access-Accept
- A
Statecan be used once and is valid for 60 seconds. It is stored inmfa_pendingand taken with aDELETEin the second step, so two requests can never use the same challenge. - Each code can be used only once: the time step last used is recorded, and only later ones are accepted.
- Five wrong guesses lock the account for 5 minutes. Only someone who knows the password can trigger the lock. Guesses at the password itself are not limited; the jump host or a firewall has to limit them.
- The two steps can land on different nodes; every write in the example goes through the cluster, so this is not a problem.
Testing
For local testing, change the address of jump-host to 127.0.0.1. radtest does not handle Access-Challenge, so send two requests:
radtest ops1 ops1-password 127.0.0.1 0 jump-host-shared-secret-change-me
# an Access-Challenge comes back; note the value of State (starting with 0x)
oathtool --totp -b JBSWY3DPEHPK3PXP # produce the current code
echo 'User-Name=ops1,User-Password=<code>,State=<value of State>' \
| radclient 127.0.0.1:1812 auth jump-host-shared-secret-change-me
The second request gets an Access-Accept. Sending the same State again is rejected.
On an SSH jump host
pam_radius shows the Reply-Message of an Access-Challenge to the user and sends the answer back, so an SSH login asks for the password and then the code. Put rradius’s address and the contents of jump-host.secret in /etc/pam_radius.conf; a timeout of 5 seconds or more is recommended.
Using your own accounts
two-step-totp.luakeeps passwords inmfa_users.passwordand compares them in plain text. To use hashes or LDAP for the password, the script has to be rewritten: for example, change the chain toall_acceptwith an LDAP handler first to check the password and the script doing only the code. Then the “password” of the second step is the code, which LDAP rejects, so the script has to take over whenStateis present. That is more involved; try it in a test environment first.- Code keys are Base32, one per person, given to the user as a QR code (
otpauth://totp/...) to scan.
Before going live
ldap.secretholds the directory service account’s password; make it readable only by the account that runs rradius. The service account only needs to search users and groups; it needs no write access.- The DNs in
required_groupsandgroup_replymust be written exactly as in the directory; check the user’smemberOfwithldapsearchfirst.memberOfholds only direct memberships; for nested groups in AD, usegroup_base_dnwithgroup_filter = "(member:1.2.840.113556.1.4.1941:={dn})"(this form has not yet been tested against AD). - LDAP connections are kept and reused, up to
pool_sizeper URL (4 by default). Raise it for high login volumes. - The contractors’
Session-Timeoutonly works when the gateway supports it.