Scenario: the internet, or a stretch of network you do not trust, lies between the NAS and rradius. RADIUS over UDP protects only part of its contents, with the shared secret and MD5, and is not fit to cross such a network directly. Use RadSec instead (RADIUS over TLS, RFC 6614): the whole packet is inside TLS, and both sides verify each other by certificate.
- The wireless controller at headquarters has a fixed address and is recognised by certificate plus address.
- The branch gateways are behind NAT with no fixed address, and are recognised by certificate alone.
- To disconnect a user at a branch, rradius cannot reach the gateway behind NAT, so the request travels over the RadSec connection the gateway opened itself.
- The management system at headquarters also connects in over RadSec, and sends disconnect requests on the same connection.
Example directory: rradius-server/examples/scenarios/radsec/
| File | Contents |
|---|---|
rradius.toml | [radius.tls], three kinds of client, [radius.coa] |
make-certs.sh | Creates a demo CA, a server certificate and three client certificates |
migrations/ | Accounts (same structure as the quick start) and the demo account alice |
hq-wlc.secret, helpdesk.secret | The shared secret for the controller over UDP, and the shared secret the help desk uses to send CoA |
How it differs from UDP
| UDP | RadSec | |
|---|---|---|
| Ports | authentication 1812, accounting 1813 | One TCP port, 2083; authentication, accounting and Status-Server share one connection |
| How the NAS is recognised | Source address | Source address, certificate, or both |
| Shared secret | Each NAS’s own | Fixed as radsec (set by the RFC); protection comes from TLS |
| Message-Authenticator settings | Apply | Do not apply; TLS guarantees integrity |
Once connected, requests take exactly the same path as over UDP: the same authentication chains, scripts, EAP, forwarding by realm and accounting spool.
Steps
1. Create the certificates
cd rradius-server/examples/scenarios/radsec
./make-certs.sh
certs/ then holds ca.pem, the server’s server.pem/server.key (name radius.example.net), and three client certificates: hq-wlc, branch-gw and noc. For testing only. In production, use a private CA dedicated to issuing NAS certificates (see “Before going live” below).
2. Start
cd ../../.. # back to rradius-server
./target/release/rradius-server --config examples/scenarios/radsec/rradius.toml
The log shows RadSec listening on 0.0.0.0:2083.
3. Check the handshake
Before any NAS is available, connect once with openssl using the branch gateway’s certificate to confirm the certificate part works:
cd examples/scenarios/radsec
openssl s_client -connect 127.0.0.1:2083 -servername radius.example.net \
-CAfile certs/ca.pem -cert certs/branch-gw.pem -key certs/branch-gw.key
Verify return code: 0 (ok)means both sides’ certificates passed. Press Ctrl+C to finish.result="accepted"incurl -s http://127.0.0.1:9812/metrics | grep rradius_radsec_connectionsincreases by 1.- Connect again with the
hq-wlccertificate: the handshake succeeds, but the connection is closed at once, and the log saysits certificate fits no client. Thehq-wlcclient has anaddress, so it only accepts connections from10.30.0.10, and none of the clients recognised by certificate alone has that name.
openssl can only check the handshake. Real logins have to come from a NAS or proxy that speaks RadSec; the automated test does this part in code: it connects with the branch-gw certificate, logs alice in (Access-Accept with Filter-Id = "staff") and sends accounting.
4. NAS configuration
Every NAS is configured differently, but the items to set are the same:
| Item | Value |
|---|---|
| Server address and port | rradius’s address, TCP 2083 |
| Transport | RadSec, RADIUS over TLS, or “TLS” |
| Trusted CA | The CA that issues rradius’s server certificate (ca.pem in the example) |
| Server name | The name on the server certificate (radius.example.net in the example) |
| Client certificate and private key | This NAS’s own (branch-gw.pem, branch-gw.key in the example) |
| Shared secret | radsec |
The configuration explained
[radius.tls]
bind = "0.0.0.0"
port = 2083
cert_file = "certs/server.pem"
key_file = "certs/server.key"
client_ca_file = "certs/ca.pem"
min_tls_version = "1.2"
network_clients_need_tls_name = true
client_ca_fileis the CA that issues NAS certificates. rradius trusts only it, not the system’s root certificates. A NAS with no certificate, or one not signed by it, fails the handshake.min_tls_versionis"1.2"by default. When every NAS supports TLS 1.3, it can be"1.3".[radius]is required; RadSec is a section under it. UDP ports 1812 and 1813 stay open as usual; to keep UDP from being reached from outside, block it with the firewall.
Three kinds of client
[[radius.clients]]
name = "hq-wlc"
address = "10.30.0.10"
tls_name = "hq-wlc.example.net"
secret_file = "hq-wlc.secret"
[[radius.clients]]
name = "branch-gw"
tls_name = "branch-gw.example.net"
secret = "unused-on-radsec-change-me"
max_radsec_connections = 4
| Setting | How it matches | Suits |
|---|---|---|
address only | Source address. Any certificate from the same CA can act as this client | A CA that signs only for NAS, fixed addresses |
address plus tls_name | Source address, and the certificate must be valid for this name | NAS with fixed addresses, hq-wlc in the example |
tls_name only | The certificate must be valid for this name, from an address no other entry covers | NAS behind NAT whose addresses change, branch-gw in the example |
tls_nameis matched against the certificate’s DNS SAN, wildcards on the certificate included; the CN is not used.- The source address comes first. When the source falls inside an entry with an
address, that entry handles it, and the certificate does not move the connection to another client. So the source of a NAS recognised by certificate alone must not fall inside another client’s range. secretis still required. RadSec does not use it; it is used only when a client with anaddresscomes over UDP.- A client with only
tls_namecan only use RadSec; UDP never matches it. max_radsec_connectionslimits how many connections this client may have open at once. Without it, one certificate can use up all of[radius.tls]’smax_connections(1024 by default).- Be careful with range clients. When
addressis a range and there is notls_name, any address in the range can connect with any certificate from this CA. The example setsnetwork_clients_need_tls_name = true, so such clients do not accept RadSec connections (they can still use UDP).
The script knows which NAS it is
When a request comes over RadSec, the script can read the connection’s certificate: radsec_subject is the subject as text, and radsec_subject_attrs.CN[1] is one of its fields. It says who the NAS is, not who the user is. For UDP requests and replayed accounting it is nil. See usage section 4.2.
Disconnects over the NAS’s own connection
The branch gateway is behind NAT, so rradius has no address to send a Disconnect-Request to. When a client with only tls_name has a connection open, rradius sends it on the RadSec connection it opened instead.
[radius]
coa_timeout_ms = 2000
[radius.coa]
bind = "0.0.0.0"
port = 3799
[[radius.coa.clients]]
name = "helpdesk"
address = "10.30.0.50"
secret_file = "helpdesk.secret"
The help desk system (helpdesk) sends the request over UDP to rradius’s port 3799, naming the NAS with NAS-Identifier:
echo 'User-Name=alice,NAS-Identifier=branch-gw,Acct-Session-Id=rs-1' \
| radclient 127.0.0.1:3799 disconnect helpdesk-coa-secret-change-me
(For local testing, change the address of helpdesk to 127.0.0.1 first.)
- How the NAS is found: the request’s
NAS-IP-Address,NAS-IPv6-AddressandNAS-Identifierare matched, in that order, against client addresses ornames.branch-gwhas no address, so its name is used. - It is sent once on the connection, waiting
coa_timeout_ms. TCP does not lose packets, socoa_attemptsis not used. - When the gateway has no connection open, the answer is a NAK with
Error-Cause502 (Request Not Routable). The command above gets exactly this when no gateway is connected. - The NAS must be willing to receive Disconnect and CoA on the connection it opened. Not every device supports this; check with the vendor first.
- Scripts can send them too:
send_disconnect('branch-gw', {...})uses the same connection, and raises an error when there is none. The command-linerradius-server disconnectdoes not run inside the server and cannot reach the connection, so it cannot target this kind of client. - In a cluster, only the node holding that connection can send. When the gateway is connected to node1, the request must go to node1; sent to another node it gets 502.
The management system over RadSec too: coa_sender
[[radius.clients]]
name = "noc"
tls_name = "noc.example.net"
secret = "unused-on-radsec-change-me"
coa_sender = true
When the sender already connects to rradius over RadSec, set coa_sender = true and it can send Disconnect-Request and CoA-Request on the same connection, with no separate UDP or shared secret. Answers are written back on the same connection.
- Off by default. Senders and NAS share port 2083, so a firewall cannot tell them apart; this setting is what decides who may disconnect users. Requests from clients without it are dropped, with
is not a coa_senderin the log. - Requires
[radius.coa]and[radius.tls]. When requests come only over RadSec,[[radius.coa.clients]]can be left out, but the UDP port 3799 is still opened.
For the full rules (session lookup when only a user name is given, forwarding by realm to upstreams, the various NAKs), see chapter 7 and usage section 4.8.
Revoking a NAS
Three ways, from fastest to slowest:
- Remove its
[[radius.clients]]entry and send SIGHUP. Open connections are closed at their next packet. - Revoke the certificate: set
crl_file, put the new revocation list in place and send SIGHUP. The certificate then fails the handshake, and open connections are closed when they are checked again (at the SIGHUP, and once a minute after that). The revocation lists must cover every CA in the chain; missing one blocks every device. - When the CA offers only OCSP, set
ocsp, the same way as for EAP-TLS; see chapter 15.
Before going live
- The CA signs only for NAS. When the CA in
client_ca_filealso signs users’ EAP-TLS certificates, a user’s certificate can be used to connect in as a NAS (clients with onlyaddresscannot stop it). Use a separate CA, or settls_nameon every client. - Limit the sources of 2083 with the firewall. With clients recognised by certificate alone, unknown connections cannot be stopped by source address before the handshake, so anyone who can reach the port can use up TLS handshakes.
- Replace certificates before they expire. An expired certificate fails the handshake, and an open connection stays open at most one more minute. After replacing the server certificate, send SIGHUP: new connections use the new one, and open ones are unaffected.
- Behind a load balancer, it must run in TCP mode and send a PROXY protocol header, with its addresses listed in
proxy_protocol_from; TLS is still handled by rradius. See usage section 2.7. - Different certificates for different names on one port (multi-tenant) use
[[radius.tls.certificates]]; see the same section. - Idle connections are closed after 300 seconds without a complete packet (
idle_timeout_ms), and the NAS reconnects. A NAS that sends Status-Server regularly is not closed. - Not tested: RadSec with any real NAS. Interoperability tests have covered authentication, accounting and CoA with FreeRADIUS 3.2.10 as a proxy. CoA over the NAS’s own connection has only been tested with a NAS simulated in code.
Common problems
| Symptom | Cause |
|---|---|
The log shows RadSec handshake with ... failed | The NAS presented no certificate, the certificate is not signed by client_ca_file, it has been revoked, or the TLS versions do not match |
RadSec connection from unknown client | The source is in no client’s address, and there is no client recognised by certificate alone |
The handshake succeeds but the connection drops at once, with its certificate fits no client | The certificate’s name is not that of any client with only tls_name; or the source falls inside a client with an address and the certificate is not valid for its tls_name (the message is then is not valid for client ...'s tls_name) |
has no tls_name, which network_clients_need_tls_name asks for | A range client has no tls_name, and network_clients_need_tls_name is on |
| Connected, but no request gets a reply | The NAS’s shared secret is not radsec |
| A disconnect gets 502 | NAS-Identifier is not the client’s name, that NAS has no connection open, or it is connected to another node |
| A disconnect gets 505 | The NAS did not answer within coa_timeout_ms: it does not support receiving CoA on this connection |
| The connection drops every 5 minutes | The idle timeout; raise idle_timeout_ms or have the NAS send Status-Server |