3. Enterprise Wi-Fi (802.1X)

Scenario: the company’s WPA2/WPA3-Enterprise wireless network.

  • Company laptops carry certificates signed by the company CA, log in with EAP-TLS, and go into device VLAN 10.
  • Staff’s own phones have no certificate, log in with a user name and password over PEAP-MSCHAPv2, and go into staff VLAN 20.
  • People who leave and lost laptops are disabled in the table and can no longer log in, without waiting for certificate revocation.

Example directory: rradius-server/examples/scenarios/enterprise-wifi/

FileContents
rradius.tomlConfiguration file
make-certs.shCreates a demo CA, a server certificate and one laptop certificate
migrations/1_schema.sqlaccounts (users and devices), group_reply (VLAN per group), accounting
migrations/2_demo_data.sqlStaff staff1 (enabled), staff2 (disabled), laptop laptop-001
eapol/peap.conf, eapol/tls.confTest configurations for eapol_test

Accounting reuses accounting.lua from the quick start.

Steps

1. Create the certificates

cd rradius-server/examples/scenarios/enterprise-wifi
./make-certs.sh

This creates ca.pem, server.pem/server.key (name radius.corp.example.com) and device.pem/device.key (name laptop-001.corp.example.com) in certs/. For testing only. In production, server and client certificates are issued by the company CA, and the server’s private key never leaves the server.

2. Change the client address and start

For local testing, change address = "10.30.0.10" in [[radius.clients]] to 127.0.0.1.

cd ../../..   # back to rradius-server
./target/release/rradius-server --config examples/scenarios/enterprise-wifi/rradius.toml

3. Test with eapol_test

eapol_test is in the eapoltest package on Debian and Ubuntu. Run it in the scenario directory so the certificate paths in its configuration resolve:

cd examples/scenarios/enterprise-wifi
eapol_test -c eapol/peap.conf -a 127.0.0.1 -s wlc-shared-secret-change-me
eapol_test -c eapol/tls.conf -a 127.0.0.1 -s wlc-shared-secret-change-me

Both must print SUCCESS, with Tunnel-Private-Group-Id in the Access-Accept (20 for PEAP, 10 for TLS). rradius’s authentication log:

authentication protocol="radius" client="wlc" source=127.0.0.1 user="anonymous@corp.example.com" account="staff1" chain="eap" handler="eap-peap" decision="accept"
authentication protocol="radius" client="wlc" source=127.0.0.1 user="laptop-001.corp.example.com" account="laptop-001.corp.example.com" chain="eap" handler="eap-tls" decision="accept"

For PEAP, user is the anonymous outer name and account is the real inner account.

These two eapol_test configurations have been run for real in Docker with the eapoltest package. This scenario’s automated test only uses PAP to check the chain and the VLANs; EAP itself is covered by the project’s interoperability tests. The automated test of chapter 15 goes through a full EAP-TLS exchange.

The configuration explained

[radius.eap]
cert_file = "certs/server.pem"
key_file = "certs/server.key"
client_ca_file = "certs/ca.pem"
methods = ["tls", "peap"]

[[radius.clients]]
name = "wlc"
address = "10.30.0.10"
secret_file = "wlc.secret"
eap_methods = ["tls", "peap"]
  • client_ca_file is the CA that issues client certificates. Only it is trusted, not the system’s root certificates.
  • When methods has two or more entries, every client must set eap_methods, and the list order is the order they are offered in. A client can refuse the first and ask for the second (EAP Nak), so if one controller should only accept certificates, list only ["tls"] for it.
  • A valid certificate does not by itself mean the login is accepted. After the handshake succeeds, the name on the certificate goes to the authentication chain, so disabling a device only takes a table change.
[[auth.handlers]]
type = "sql"
user_query = "SELECT password FROM accounts WHERE name = ? AND kind = 'user' AND enabled = 1"
certificate_query = "SELECT 1 FROM accounts WHERE name = ? AND kind = 'device' AND enabled = 1"
reply_query = "SELECT r.attribute, r.value FROM accounts a JOIN group_reply r ON r.grp = a.grp WHERE a.name = ?"
  • PEAP uses user_query: MS-CHAPv2 has to compare against plain text or an NT hash, so the password is stored as {nthash} (2_demo_data.sql shows how it is computed). Accounts stored as bcrypt or argon2 cannot use PEAP; use EAP-TTLS with inner PAP instead, see usage section 2.12.
  • EAP-TLS uses certificate_query: a row found means accept. Devices have no password, so user_query cannot be used (a NULL password column is rejected).
  • reply_query is used by both kinds of login, returning the three VLAN attributes by group. The :1 in Tunnel-Type:1 is a tag, and the three attributes must use the same tag.
[auth.username]
strip_realm = "suffix"
lowercase = true
  • Staff may type Staff1@corp.example.com; account lookup uses staff1.
  • Certificate logins do not strip the realm: the certificate proves the full name, so a login is rejected when the name would change by more than case. Store devices under the full name on the certificate, and keep @ out of device names.

The name on the certificate

  • rradius uses the certificate’s DNS SAN and email SAN as names, and the CN only when there are neither. The client’s EAP Identity must match one of them (match_identity = true, the default).
  • When clients fill in an anonymous Identity, set match_identity = false to use the certificate’s first name instead.
  • To decide on certificate fields in a script (an OU, for example), use tls_subject_attrs rather than matching the whole subject string; see usage section 4.2.

Other login methods

This chapter uses the two most common ones. Other choices:

SituationWhat to useWhere
Passwords exist only as hashes (bcrypt, argon2, brought over from an old system), or LDAP should verify by bindEAP-TTLS with inner PAP: add "ttls" to methodsusage section 2.12, chapter 17
Devices carry USIM cards the company issuedEAP-AKA'chapter 13
Devices cannot do 802.1X, but each person should have their own Wi-Fi passphraseA WPA2 passphrase per personchapter 12
Devices can do nothing at all (printers)MAC authenticationchapter 4

Before going live

  • Clients must verify the server certificate. PEAP’s protection rests entirely on TLS; when clients do not verify, a fake access point can obtain password hashes. Push the CA and the server name (radius.corp.example.com) to devices through MDM or group policy. This is the most common deployment mistake.
  • The server certificate should carry the serverAuth EKU; make-certs.sh adds it.
  • Revocation: with crl_file set, every CA in the chain needs a CRL; send SIGHUP after updating them. When the CA offers only OCSP, set ocsp. Without either, disabling a device relies on enabled in the table. See chapter 15 for how and the trade-offs.
  • Devices that roam do a full handshake every time: that is the default. To let reconnecting devices resume their previous session, set resumption_ms; see chapter 15.
  • One login must complete on one node. With several nodes, wireless controllers must always send to the same one (active/standby), or a load balancer must pin by source; see chapter 8.
  • This has not yet been tested with real access points and every operating system, only with eapol_test. Before going live, try it once with your real controller and a few phones and laptops.

Common problems

SymptomCause
Startup fails, mentioning eap_methodsmethods has several methods and a client does not set eap_methods
PEAP fails, log shows decision="reject"The account does not exist, is disabled, or its password is not plain text or {nthash}
EAP-TLS handshake succeeds but the login is rejectedcertificate_query finds nothing: the name differs from the table, or kind or enabled is wrong
EAP-TLS log says the Identity does not matchThe client’s Identity differs from both the certificate’s SAN and CN; change the client setting or set match_identity = false
UnknownRevocationStatus appearscrl_file is set but the CRL of some CA in the chain is missing
Phones keep asking whether to trust the certificateThe device does not have the CA, or the server name differs from the configured one
Built with Hugo
Theme Stack designed by Jimmy