18. Accounts in Another System: Verifying over an HTTP API

Scenario: Wi-Fi at a hotel, a coworking space or a membership venue. Accounts and passwords already live in the membership system (or the booking or billing system), which has an HTTP API. You do not want to copy the accounts into rradius and then work out how to keep them in sync.

  • On every login, rradius asks the membership system over HTTPS “is this user name and password right”.
  • The membership system also answers with the person’s plan, which rradius turns into attributes for the NAS.
  • rradius stores no accounts; accounting is still recorded in rradius’s own table.

Example directory: rradius-server/examples/scenarios/external-api/

FileContents
rradius.toml[lua.http] and a chain with a single lua handler
member-api.luaThe script that calls the API
migrations/1_schema.sqlOnly the accounting table

Steps

The API address in the example (members.example.com) is made up; started as is, every login is rejected because it cannot connect. To use your own system:

  1. Put your API host in [lua.http] allowed_hosts in rradius.toml.

  2. In member-api.lua, change API (the URL) and API_KEY (the key), and adjust how requests and responses are handled for your API.

  3. Check and start:

    cd rradius-server
    ./target/release/rradius-server --check --config examples/scenarios/external-api/rradius.toml
    ./target/release/rradius-server --config examples/scenarios/external-api/rradius.toml
    
  4. For local testing, change the address of hotspot to 127.0.0.1:

    radtest <user> <password> 127.0.0.1 0 hotspot-shared-secret-change-me
    

The automated test starts a fake membership system locally, points the script’s URL at it, and checks:

SituationResult
The API answers 200 with header X-Plan: goldAccess-Accept, Filter-Id = "gold", Session-Timeout = 14400
The user name and password contain &, = and spacesSent encoded, and the API receives the right values
The API answers 401Access-Reject
A CHAP loginAccess-Reject: there is no plain-text password to give the API
The API never answersAccess-Reject after timeout_ms, logging member API gave no answer

The API the script assumes

POST https://members.example.com/v1/radius/login
Authorization: Bearer <API key>
Content-Type: application/x-www-form-urlencoded

username=<user>&password=<password>
ResponseMeaning
200, header X-Plan: <plan> (optional)The user name and password are right, and the person may get online
401, 403The user name or password is wrong, or the person may not get online now
Anything elseTreated as a failure; rejected, and the status code logged

Scripts have no JSON functions. So the example has the API answer with status codes and response headers, and form-encodes the request. When your API only speaks JSON:

  • The request can be built as a string yourself (escaping quotes and backslashes in values yourself, which is not recommended), or ask for an endpoint on the API side that accepts form encoding.
  • Taking values out of a JSON response is only possible with Lua string matching (string.match). That works for a simple fixed format, but is unreliable for complex structures.
  • The most robust option is a thin adapter service in front of the membership system, or an endpoint made specifically for RADIUS.

The configuration explained

Where scripts may connect

[lua.http]
allowed_hosts = ["members.example.com"]
timeout_ms = 1500
max_concurrent = 64
  • Without this section, scripts have no http_request. With it, they can connect only to the hosts in allowed_hosts, matched exactly by host and port, with no wildcards.
  • A host name alone allows only HTTPS on port 443. Write other ports as "billing.internal:8443". For unencrypted HTTP (recommended only on the local machine or an isolated network), write "http://legacy.internal:8080".
  • timeout_ms is the total time from connecting to reading the whole response. It must be shorter than the NAS’s retransmission time, or rradius is still waiting after the NAS has given up.
  • max_concurrent: the most requests waiting on one host at once. Beyond it, http_request fails at once (busy) instead of queueing. Logins and accounting are counted separately.
  • Certificates signed by an internal CA need ca_file. Server certificates are always verified; there is no option to turn verification off.

The chain

[[auth.handlers]]
type = "lua"
script = "member-api.lua"
verifies_password = true
  • verifies_password = true tells rradius “this script really checks the password”. Ordinary PAP logins do not need it; but for Wi-Fi EAP-TTLS with inner PAP to go through this script it must be set, or an accept from the script is treated as a reject.
  • Only login methods that carry the plain-text password work: PAP, and EAP-TTLS with inner PAP. CHAP, MS-CHAPv2 and PEAP do not send the password itself, so the API has nothing to compare.

The script

local response, problem = http_request{
  url = API,
  method = 'POST',
  headers = {
    Authorization = 'Bearer ' .. API_KEY,
    ['Content-Type'] = 'application/x-www-form-urlencoded',
  },
  body = 'username=' .. url_encode(user) .. '&password=' .. url_encode(password),
}

if not response then
  log('member API gave no answer:', problem)
  return 'reject'
end
  • What http_request returns: when a response arrives, a table (status, body, headers, with lowercase header names); 4xx and 5xx count as arriving. When none arrives (timeout, cannot connect, not on the allow list, response too large, too busy), nil and the reason.
  • Always url_encode values that come from users. User names and passwords are typed by users; without encoding, an & in the name slips an extra parameter to the API.
  • Take more care when putting values into the URL path: url_encode raises a script error (and the request is rejected) for the empty string, . and .., because .. in a path reaches another endpoint. The example puts values in the request body, and logins whose name is exactly . or .. are still rejected because of the script error.
  • What to do when the API does not answer is up to the script. The example rejects. It could let people through instead (a hotel may prefer guests to get online first), but that means any password works while the API is down; think it through.
  • Do not log passwords. The example’s log() writes only the reason and status code. rradius’s own log does not write URL paths, headers or bodies, only the host and the kind of error.
  • The API key is written in the script, so make the script file readable only by the account that runs rradius. To change the key, edit the file and send SIGHUP.
  • Check values in the response too. The example accepts only an X-Plan that looks like a name before putting it in Filter-Id.

When the API slows down or stops

Every login waits for the API, so the API’s speed is the login speed.

  • The API stops: every login waits timeout_ms before being rejected. At most max_concurrent logins wait at once; more are rejected at once, so rradius’s own capacity is not used up.
  • Watch the metrics: rises in rradius_script_http_requests_total{result="timeout"}, {result="error"} or {result="busy"} mean API trouble; {result="ok"} counts responses received (401 included).
  • NAS retransmissions: while a request is still being handled, the NAS’s retransmissions are dropped, so the API is not asked twice. Retransmissions within 10 seconds after handling get the previous answer directly.
  • rradius does not remember previous answers. Every login asks once. To reduce the load on the API, the script could record a “pass” in an rradius table for a few minutes (sql_execute) and check the table first; but passwords cannot be stored in plain text, so that approach needs your own design, and the example does not do it.
  • The script’s execution limit ([lua] max_execution_ms) does not count time spent waiting for the API.

Should accounting notify the API too

The example’s accounting only writes to the local table. To notify the membership system when users come online and go offline, the accounting script can also call http_request, but note:

  • The NAS gets a reply only when the accounting script returns accept. If the script fails when the API does not answer, the NAS retransmits and the script runs again; the API must tolerate receiving the same notification twice.
  • Do not let API failures block accounting. The more robust approach is for accounting to write to the table and return accept as usual, with another program sending the data from the table to the membership system.

Before going live

  • Limit sources and rates on the API side. rradius forwards whatever user name and password anyone types on the login page, so password guessing traffic reaches the API too.
  • DNS: the allow list matches host names and does not check the addresses they resolve to. If DNS is tampered with, requests may go elsewhere; HTTPS certificate verification is the protection then, so do not use http://.
  • Redirects are not followed. When the API answers 3xx, the script gets the 3xx.
  • Several nodes: each node calls the API on its own, so the API must accept every node’s source address.
  • Not tested: any real membership or billing system. The scenario test uses a fake local API (without TLS), so HTTPS certificate verification is not part of that test; other tests in the project cover http_request itself.

Common problems

SymptomCause
attempt to call a nil value in the log, pointing at the http_request lineThe configuration file has no [lua.http]
Every login is rejected, with member API gave no answer: ... is not in lua.http.allowed_hosts in the logThe host or port in the script is not exactly the same as in allowed_hosts
member API gave no answer in the log, with a timeout as the reasonThe API is too slow or unreachable; try the same URL with curl from the node
The reason concerns the certificateThe API’s certificate is signed by an internal CA; set ca_file
rradius_script_http_requests_total{result="busy"} increasesMore than max_concurrent requests waiting at once: the API is too slow, or the limit is too low
PAP works, Wi-Fi does notWi-Fi uses PEAP or MS-CHAPv2; this approach only works with EAP-TTLS inner PAP, and the handler needs verifies_password = true
Startup fails, saying there are no trusted root certificatesThe host has no system CA certificates (common in minimal containers); install ca-certificates or set ca_file
Built with Hugo
Theme Stack designed by Jimmy