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/
| File | Contents |
|---|---|
rradius.toml | Configuration file |
make-certs.sh | Creates a demo CA, a server certificate and one laptop certificate |
migrations/1_schema.sql | accounts (users and devices), group_reply (VLAN per group), accounting |
migrations/2_demo_data.sql | Staff staff1 (enabled), staff2 (disabled), laptop laptop-001 |
eapol/peap.conf, eapol/tls.conf | Test 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="[email protected]" 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_fileis the CA that issues client certificates. Only it is trusted, not the system’s root certificates.- When
methodshas two or more entries, every client must seteap_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.sqlshows 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, souser_querycannot be used (a NULL password column is rejected). reply_queryis used by both kinds of login, returning the three VLAN attributes by group. The:1inTunnel-Type:1is a tag, and the three attributes must use the same tag.
[auth.username]
strip_realm = "suffix"
lowercase = true
- Staff may type
[email protected]; account lookup usesstaff1. - 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 = falseto use the certificate’s first name instead. - To decide on certificate fields in a script (an OU, for example), use
tls_subject_attrsrather than matching the whole subject string; see usage section 4.2.
Other login methods
This chapter uses the two most common ones. Other choices:
| Situation | What to use | Where |
|---|---|---|
| Passwords exist only as hashes (bcrypt, argon2, brought over from an old system), or LDAP should verify by bind | EAP-TTLS with inner PAP: add "ttls" to methods | usage section 2.12, chapter 17 |
| Devices carry USIM cards the company issued | EAP-AKA' | chapter 13 |
| Devices cannot do 802.1X, but each person should have their own Wi-Fi passphrase | A WPA2 passphrase per person | chapter 12 |
| Devices can do nothing at all (printers) | MAC authentication | chapter 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
serverAuthEKU;make-certs.shadds it. - Revocation: with
crl_fileset, every CA in the chain needs a CRL; send SIGHUP after updating them. When the CA offers only OCSP, setocsp. Without either, disabling a device relies onenabledin 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
| Symptom | Cause |
|---|---|
Startup fails, mentioning eap_methods | methods 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 rejected | certificate_query finds nothing: the name differs from the table, or kind or enabled is wrong |
| EAP-TLS log says the Identity does not match | The client’s Identity differs from both the certificate’s SAN and CN; change the client setting or set match_identity = false |
UnknownRevocationStatus appears | crl_file is set but the CRL of some CA in the chain is missing |
| Phones keep asking whether to trust the certificate | The device does not have the CA, or the server name differs from the configured one |