9. Forwarding by Realm

Scenario: a branch office’s rradius serves the branch’s NAS.

  • The branch’s own accounts (branch1, or [email protected]) are authenticated locally.
  • Visitors from a partner log in as [email protected] and are forwarded to the partner’s RADIUS servers. The partner has two; when the first does not answer, the second is used.
  • Headquarters accounts (@hq.example.com and subdomains like @eng.hq.example.com) are forwarded to headquarters.

Example directory: rradius-server/examples/scenarios/realm-proxy/

FileContents
rradius.toml[proxy] and the chain for local accounts
partner.secret, hq.secretShared secrets with the upstreams
migrations/Local accounts (same structure as the quick start) and the demo account branch1

How forwarding is decided

The realm is the part of User-Name after the last @.

[email protected]  ─► exact realm "partner.example.org" ─► partner-1, then partner-2 if no answer
[email protected]     ─► "*.hq.example.com" ────────────────► hq-1
[email protected]       ─► "hq.example.com" ──────────────────► hq-1
[email protected] ─► no realm matches ──────────────────► local chain
branch1                    ─► no @ ──────────────────────────────► local chain
  • Matching order: exact → the *. entry that covers it (longest first) → *, ignoring case. *.hq.example.com does not cover hq.example.com itself, so the example lists both.
  • Do not add * casually. It forwards every name with an @, including your own accounts like [email protected]. * is a suitable default exit only when there are no local accounts with a realm.
  • Forwarded requests are not handled locally: no chain, no script, no EAP. The whole EAP conversation of 802.1X is forwarded as is, and the keys come from the upstream.
  • Accounting is forwarded by realm too, and the NAS gets its reply only after the upstream answers. It is not written to the local accounting spool (the one in chapter 7 only covers accounting the database cannot take). To keep a record when no upstream answers, use [proxy.accounting_spool]; see chapter 11.

Steps

Local testing needs a server to play the “partner”. The simplest is a second copy of the quick start on other ports:

  1. Copy the whole of quick-start/ outside the repository (for example cp -R examples/scenarios/quick-start /tmp/partner), and in /tmp/partner/rradius.toml:

    • Change dictionary to the absolute path of share/dictionary in the repository.
    • Set auth_port = 11812, acct_port = 11813 and [metrics] port = 19812.
    • Add listen = "127.0.0.1" to [cluster], and add [[cluster.nodes]] at the end (id = 1, raft = "127.0.0.1:18100", api = "127.0.0.1:18200") to stay off this machine’s 8100 and 8200. listen is a must: once nodes are listed, the default is to listen on every interface, and the demo api.secret is public.

    Then start it.

  2. In realm-proxy/rradius.toml:

    • Change the address of branch-nas to 127.0.0.1.
    • Change partner-2 to address = "127.0.0.1", auth_port = 11812, acct_port = 11813, with secret_file pointing to ../quick-start/localhost.secret.
    • Leave partner-1 at its original address to simulate “the first server does not answer”.
  3. Start realm-proxy:

    ./target/release/rradius-server --config examples/scenarios/realm-proxy/rradius.toml
    
  4. Test:

    S=branch-nas-secret-change-me
    radtest [email protected] branch1-password 127.0.0.1 0 $S   # local, Filter-Id = branch
    radtest [email protected] bob-password 127.0.0.1 0 $S          # forwarded to partner, returns Welcome, bob
    

    The second is a few seconds slower: partner-1 got no answer within timeout_ms × attempts (3 seconds × 2), was marked down, and partner-2 was used. Later requests go straight to partner-2, and every 10 seconds a Status-Server checks whether partner-1 is back. The first radtest may time out before the answer arrives; sending it again succeeds.

The configuration explained

[proxy]
timeout_ms = 3000
attempts = 2
check_interval_ms = 10000

[[proxy.servers]]
name = "partner-1"
address = "198.51.100.10"
auth_port = 1812
acct_port = 1813
secret_file = "partner.secret"

[[proxy.realms]]
name = "partner.example.org"
servers = ["partner-1", "partner-2"]
strip_realm = true
  • servers are tried in order, those not marked down first. Authentication and accounting ports are judged separately.
  • Get the timing right: one server waits at most timeout_ms × attempts. That must be shorter than the NAS’s timeout, or the NAS gives up first; and timeout_ms must be longer than any deliberate delay before the upstream rejects (FreeRADIUS, for example, waits 1 second by default before an Access-Reject), or wrong passwords are mistaken for an upstream that does not answer.
  • strip_realm = true: the partner only knows alice, so @partner.example.org is removed before sending. MS-CHAPv2 (not inside EAP) responses are computed with the full name; keep it false then.
  • Upstream replies must carry a Message-Authenticator (require_message_authenticator = true, the default). Set false only for old upstreams that do not send it; not recommended.
  • When none answer, the NAS gets no reply. An Access-Reject would make the user think the password is wrong, so the NAS is left to time out and use its own backup.
  • How a down upstream comes back: every check_interval_ms a Status-Server is sent, and an answer restores it. For upstreams that do not answer Status-Server, set status_check = false on that server; it is then simply treated as restored when the time is up, and the next request decides.
  • Noticing a down server earlier (probe_interval_ms): by default an upstream is marked down only when real requests time out, so the first batch of requests after it fails all have to wait first. With probe_interval_ms = 30000 in [[proxy.servers]], once that server has given no answer of any kind for more than 30 seconds, Status-Server is sent actively, and 3 unanswered in a row mark it down. Backup servers that normally carry no traffic need this most. See chapter 11.

Local accounts

[auth.username]
strip_realm = "suffix"
lowercase = true

[email protected] matches no realm, so it stays local, and the account lookup uses branch1.

Roaming between organisations: RadSec upstreams

When the partner is another organisation across the internet, do not forward over UDP; use RadSec (RADIUS over TLS): the whole packet is inside TLS, and both sides verify each other by certificate.

  1. Prepare certificates. Get the CA that issues the partner’s server certificate from the partner (or the roaming federation) and save it as partner-ca.pem. When the partner verifies rradius, also prepare a certificate and private key issued by a CA the partner trusts (our-cert.pem, our-cert.key). Ask for the name on the partner’s server certificate, such as radius.partner.example.org.

  2. Change the upstream configuration. Turn partner-1 into RadSec:

    [[proxy.servers]]
    name = "partner-1"
    address = "198.51.100.10"
    transport = "tls"
    tls_name = "radius.partner.example.org"
    ca_file = "partner-ca.pem"
    cert_file = "our-cert.pem"
    key_file = "our-cert.key"
    
    • Without port it is 2083, used for both authentication and accounting; auth_port and acct_port can no longer be set.
    • No secret is needed: the RadSec shared secret is fixed as radsec (RFC 6614), and the partner uses the same. Set secret or secret_file only when the partner specifies another.
    • A realm’s servers can mix RadSec and UDP upstreams, with failover in order as usual.
  3. Check and start:

    ./target/release/rradius-server --check --config examples/scenarios/realm-proxy/rradius.toml
    

    An unreadable certificate file, a private key that does not match its certificate, or a missing tls_name or ca_file is reported here, naming the upstream and the field.

  4. Confirm: send a login that is forwarded to the partner. The log shows proxy server partner-1: connected to 198.51.100.10:2083, and rradius_proxy_connections_total{server="partner-1",result="connected"} in /metrics is 1. Later requests use the same connection, without a new handshake each time.

Differences from UDP upstreams:

  • No retransmission. TCP guarantees delivery, so a request is sent once and attempts does not apply; with no answer within timeout_ms, the next server is used. One server waits at most one timeout_ms.
  • Authentication and accounting are marked down together, because there is one port and one connection.
  • One connection has at most 256 requests waiting for answers at once; more queue. With a partner far away and busy, this is the ceiling (about 25,000 requests per second at a 10 ms round trip, an estimate). Measured on one machine, one connection handles about 100,000 requests per second, around a tenth less than a UDP upstream; see usage section 2.13.
  • CoA uses this connection too: Disconnect and CoA forwarded by realm to a RadSec upstream are sent on the same connection. The partner must be willing to receive them on it; check with the partner first.
  • Revocation lists (crl_file) are read only at startup and on SIGHUP; send SIGHUP when the partner replaces its list.

Before going live

  • UDP upstreams must be on a trusted network (a leased line, a VPN), because RADIUS over UDP encrypts only the password. Across the internet, use RadSec upstreams (see the previous section).
  • Upstream addresses must be IPs, not host names.
  • Shared secrets with UDP upstreams should differ per organisation and be long.
  • Loops: when two servers forward to each other, rradius drops and logs requests that carry its own Proxy-State.
  • Monitoring: request counts, timeouts and down state of every upstream are in /metrics; see usage section 2.8.
  • Reloading (SIGHUP) applies changes to [proxy], and every upstream is treated as healthy again.
  • CoA can be forwarded by realm too: when no local NAS is found and the realm of User-Name matches an entry, Disconnect and CoA requests go to that realm’s upstreams (to the upstream’s coa_port, 3799 by default); see usage section 4.8.
  • Not available yet: round robin, routing decided by a script, DTLS, TLS-PSK. See usage section 2.13.

More approaches

This chapter covers the most basic “failover in order”. The following are explained in chapter 11 with a roaming federation scenario:

NeedApproach
Spread requests over several upstreams, optionally weightedbalance = "load-balance", weight
Too many upstreams to configure one by one[proxy.discovery]: look up the other side’s RadSec servers in DNS by realm
Forwarded accounting must not be lost when no upstream answers[proxy.accounting_spool]
The other side also sends requests in[radius.tls]; see chapter 10

Common problems

SymptomCause
Local accounts with a realm are forwardedThere is a *, or a *. entry covering your own domain
Forwarded logins are always slowThe first upstream never answers requests but does answer the Status-Server checks (it answers Status-Server but does not handle authentication). Remove it from servers, or set status_check = false
After a login with a wrong password, the upstream is marked downtimeout_ms is shorter than the upstream’s delay before rejecting
A RadSec upstream never connects, with cannot connect ... TLS: in the logThe partner’s certificate is not signed by the CA in ca_file or is not valid for tls_name, or the partner does not accept the certificate rradius presents (cert_file not set, or not signed by a CA the partner trusts). The log message says which
A RadSec upstream connects but every request times outThe shared secret is not radsec, so the partner’s replies fail verification: ask which secret the partner uses, and set it in secret
Built with Hugo
Theme Stack designed by Jimmy