Base configuration

The default server configuration should be tested via the following command:

radiusd -XC

If the configuration is correct, then the server will print the following message:

Configuration appears to be OK

If that message does not appear, then it is necessary to correct any and all errors before proceeding to the next step. It is a good idea to ensure that the current configuration works before making changes to it.

Editing mods-available/rest

rest {
	# example - "http://localhost"
	connect_uri = 'http://<http_server_fqdn>'     (1)
}

1	A common URL prefix for all REST API endpoints called by this module instance. Connect URI is used to reduce repetition in the config.

Enabling mods-available/rest

The rest module is enabled by creating a soft link from the mods-enabled/ directory to the mods-available/ directory.

cd raddb/mods-enabled && ln -s ../mods-available/rest

Calling the rest module

Calling a generic API endpoint

The REST module allows a different REST API endpoint to be configured for each type of section it can be called in.

If called in recv Access-Request (≥ v4.0.x) or authorize { … } (≤ v3.2.x) the rest.authorize module section will be evaluated.

server default {
	...
	recv Access-Request {
		rest
		...
	}
	...
}

rest {
	...
	authorize {
		request {
			uri = "${...connect_uri}/user/%{User-Name}?action=authorize" (1)
			method = 'get' (2)
		}
	}
	...
}

1	The URL to authenticate against. Will be expanded (if required).
2	The HTTP 'verb' to use.

If called in recv Accounting-Request (≥ v4.0.x) or accounting { … } (≤ v3.2.x) the rest.authorize mould section will be evaluated.

server default {
	...
	recv Accounting-Request {
		rest
		...
	}
	...
}

rest {
	...
	accounting {
		request {
			uri = "${...connect_uri}/user/%{User-Name}/sessions/%{Acct-Unique-Session-ID}?action=accounting" (1)
			method = 'post' (2)
		}
	}
	...
}

1	The URL to authenticate against. Will be expanded (if required).
2	The HTTP 'verb' to use.

Authenticating a user with HTTP basic auth

The REST module can also authenticate users by performing HTTP basic access authentication against a REST API endpoint.

With HTTP Basic Auth, the user’s credentials will be base64 encoded and submitted in the clear.

It is strongly recommended to use https:// with HTTP basic auth, to prevent snooping.

server default {
	...
	recv Access-Request {
		if (&User-Password) {
			&control.Auth-Type := rest
		}
	}

	authenticate rest {
		rest
	}
	...
}

rest {
	...
	authenticate {
		request {
			uri = "${...connect_uri}/authenticate" (1)
			auth = basic (2)
			username = "%{User-Name}"      (3)
			password = "%{User-Password}"  (4)
			method = 'get'  (5)
		}
		tls = ${..tls}  (6)
	}
	...
}

1	The URL to authenticate against. Will be expanded (if required).
2	Specify the type of authentication we’ll be using (HTTP basic auth).
3	Username to submit for HTTP Basic Auth. Will be expanded.
4	Password to submit for HTTP Basic Auth. Will be expanded.
5	The HTTP 'verb' to use.
6	HTTP(s) settings for the module instance.

After configuring the module, the server should be tested again via the following command:

radiusd -XC

When the configuration is correct, then the server will print the following message:

Configuration appears to be OK

Note that this test checks only that the configuration files can be parsed. It does not check that the module works correctly when packets are received.

When the configuration is correct, FreeRADIUS can then be started in debugging mode:

radiusd -X

If the module has been configured correctly, the final (or almost final) message will be

Ready to process requests

This message should be in bold on the console. Depending on which other modules are enabled, there may be a small number messages after this one.

If the server starts, then the next step is then to perform run-time tests.

Errors

If the Ready to process requests message does not appear, then the debug output will contain error messages clearly describing what went wrong. These error message must be read in order to gain insight as to the source of the problem.

Otherwise, look for messages containing ERROR or WARNING, or the module name. While the server can produce a large volume of messages, most of those can be ignored when debugging a particular problem. Simply search for a few key strings based on the files you changed, and the solution to the problem should be clear.

We recommend running the radiusd -XC test was performed before making any module changes for other reasons. If previous configuration worked, and the only change was to a particular module, then the source of the error is simple. There is no need to go searching through other configuration files or third-party web sites. Instead, change and test the module configuration until the server works.