Important

The development of django-freeradius has moved to openwisp-radius, we highly suggest users and readers of this documentation to migrate or use the more up to date documentation of openwisp-radius.

API Documentation

django-freeradius provides an API that can be used by freeradius to perform the following operations:

  • Authorize
  • Accounting
  • Post Auth

The API also provides other features that can be useful to perform integrations with third-party software:

  • Batch User Creation
  • Login (Obtain User Auth Token)

API Token

Only requests containing the right API token will able to talk to the API endpoints.

Remember to set API token of your instance by setting DJANGO_FREERADIUS_API_TOKEN in your django settings.py.

It is highly recommended that you use a hard to guess value, longer than 15 characters containing both letters and numbers. Eg:

DJANGO_FREERADIUS_API_TOKEN = "165f9a790787fc38e5cc12c1640db2300648d9a2"

HTTP clients must send this token, either in the form of a bearer token or in the form of a query string parameter as shown below.

  • Bearer token (recommended):

    curl -X POST http://localhost:8000/api/v1/authorize/ \
     -H "Authorization: Bearer <token>" \
     -d "username=<username>&password=<password>"

  • Querystring:

    curl -X POST http://localhost:8000/api/v1/authorize/?token=<token> \
     -d "username=<username>&password=<password>"

Requests which contain an invalid token will receive a 403 HTTP error.

For information on how to configure FreeRADIUS to send the bearer token, see Configure the REST module.

Accounting

/api/v1/accounting/

GET

Returns a list of accounting objects

GET /api/v1/accounting/

[
  {
      "called_station_id": "00-27-22-F3-FA-F1:hostname",
      "nas_port_type": "Async",
      "groupname": null,
      "id": 1,
      "realm": "",
      "terminate_cause": "User_Request",
      "nas_ip_address": "172.16.64.91",
      "authentication": "RADIUS",
      "stop_time": null,
      "nas_port_id": "1",
      "service_type": "Login-User",
      "username": "admin",
      "update_time": null,
      "connection_info_stop": null,
      "start_time": "2018-03-10T14:44:17.234035+01:00",
      "output_octets": 1513075509,
      "calling_station_id": "5c:7d:c1:72:a7:3b",
      "input_octets": 9900909,
      "interval": null,
      "session_time": 261,
      "session_id": "35000006",
      "connection_info_start": null,
      "framed_protocol": "test",
      "framed_ip_address": "127.0.0.1",
      "unique_id": "75058e50"
  }
]

POST

Add or update accounting information (start, interim-update, stop); does not return any JSON response so that freeradius will avoid processing the response without generating warnings

Param Description
session_id Session ID
unique_id Accounting unique ID
username Username
groupname Group name
realm Realm
nas_ip_address NAS IP address
nas_port_id NAS port ID
nas_port_type NAS port type
start_time Start time
update_time Update time
stop_time Stop time
interval Interval
session_time Session Time
authentication Authentication
connection_info_start Connection Info Start
connection_info_stop Connection Info Stop
input_octets Input Octets
output_octets Output Octets
called_station_id Called station ID
calling_station_id Calling station ID
terminate_cause Termination Cause
service_type Service Type
framed_protocol Framed protocol
framed_ip_address framed IP address

Filters

The JSON objects returned using the GET endpoint can be filtered/queried using specific parameters.

Filter Parameters Description
username Username
called_station_id Called Station ID
calling_station_id Calling Station ID
start_time Start time (greater or equal to)
stop_time Stop time (less or equal to)
is_open If stop_time is null

Authorize

/api/v1/authorize/

Responds to only POST, used for authorizing a given username and password.

POST /api/v1/authorize/ HTTP/1.1 username=testuser&password=testpassword
Param Description
username Username for the given user
password Password for the given user

See also DJANGO_FREERADIUS_API_AUTHORIZE_REJECT.

PostAuth

/api/v1/postauth/

Sets the response data to None in order to instruct FreeRADIUS to avoid processing the response body.

Responds only to POST.

Batch user creation

/api/v1/batch/

Note

This API endpoint allows to use the features described in Importing users and Generating users.

Responds only to POST, used to save a RadiusBatch instance. It returns the information of the batch operation and the list of the users generated. It is possible to generate the users of the RadiusBatch with two different strategies: csv or prefix.

The csv method needs the following parameters:

Param Description
name Name of the operation
strategy “csv”
csvfile file with the users
expiration_date date of expiration of the users

These others are for the prefix method:

Param Description
name name of the operation
strategy prefix
prefix prefix for the generation of users
number_of_users number of users
expiration_date date of expiration of the users

Login (Obtain User Auth Token)

/api/v1/account/token/

Note

This endpoint does not require the sending of the API Token described in the beginning of this document.

Responds only to POST, this endpoint is enabled only if rest_framework.authtoken is in settings.INSTALLED_APPS (which is optional).

Returns the user access token, which can be used to authenticate the user via the freeradius authorization mechanism.

Parameters:

Param Description
username string
password string