5. Remote Access: VPN Logins Against the Company Directory, One-Time Codes for the Jump Host

Scenario:

  • The VPN gateway logs users in with their company directory (Active Directory or OpenLDAP) user name and password. Only members of the vpn-users group 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/

FileContents
rradius.tomlThe two chains, vpn and mfa
ldap.secretPassword of the directory service account (demo value)
migrations/1_schema.sqlmfa_users and mfa_pending for the codes, and accounting
migrations/2_demo_data.sqlJump 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.
  • urls are 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.
  • filter excludes 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’s memberOf is used; when the directory has no memberOf, search for groups with group_base_dn and group_filter instead, 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, set ca_file. Plain-text LDAP also needs allow_plaintext = true and is not recommended.
  • password_check = "bind" supports only PAP. The VPN gateway must send the password with PAP (RADIUS encrypts User-Password). To support CHAP, MS-CHAPv2 or PEAP, use password_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_attributes can 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 State can be used once and is valid for 60 seconds. It is stored in mfa_pending and taken with a DELETE in 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.lua keeps passwords in mfa_users.password and compares them in plain text. To use hashes or LDAP for the password, the script has to be rewritten: for example, change the chain to all_accept with 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 when State is 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.secret holds 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_groups and group_reply must be written exactly as in the directory; check the user’s memberOf with ldapsearch first. memberOf holds only direct memberships; for nested groups in AD, use group_base_dn with group_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_size per URL (4 by default). Raise it for high login volumes.
  • The contractors’ Session-Timeout only works when the gateway supports it.
Built with Hugo
Theme Stack designed by Jimmy