Table of Contents Table of contents: Radiator® AAA Server <AuthBy FREERADIUSSQL> 3.78 - <AuthBy FREERADIUSSQL> <AuthBy HTGROUP> 3.80 - <AuthBy HTGROUP>

3.79. <AuthBy RADIUSdeskSQL>

This clause handles authentication and accounting using a RADIUSdesk-compatible SQL database. The <AuthBy RADIUSdeskSQL> module inherits parameters from <AuthBy SQL>. <AuthBy RADIUSdeskSQL> can be considered an extension of <AuthBy FREERADIUSSQL>, offering additional functionality and features. The following list highlights the enhancements provided by <AuthBy RADIUSdeskSQL> compared to <AuthBy FREERADIUSSQL>:
User Profile Support
If a User-Profile check attribute is specified for a user, additional queries are performed to determine the user's profile.
Account Disablement
When a permanent user is disabled in RADIUSdesk, the Rd-Account-Disabled check attribute is set, and the module rejects the authentication request with the message "Account Disabled".
Gigaword Support
Support for Acct-Input-Gigawords in accounting records.
Realm Restrictions
Support for Dynamic Client to Realm or NAS to Realm restrictions.
Auto-Registration
Option to auto-register unknown users.
Custom Attribute Recording
Option to specify an attribute to be recorded during Access Request and Accounting Start requests.
Group Identification
Option to specify a Group Name and Group ID per Radiator instance. These values will be included with the SQL statement for the radacct table used during Accounting Start. This feature is particularly useful in large deployments with multiple Radiator instances where database sharding is implemented.
For a configuration sample, see a configuration sample file goodies/fidelio-hotspot.cfg

Background

Before diving into the configurable parameters, it's essential to understand some key concepts in RADIUSdesk. This background information will provide context and help you better comprehend the parameters and their applications.
Realms
In RADIUS, a realm is typically specified as a suffix to a username, separated by a delimiter (e.g., jsmith@example.com, where "jsmith" is the username and "example.com" is the realm). However, RADIUSdesk offers more flexibility by allowing you to group users by realm without requiring the realm component to be part of the username. This approach provides greater freedom when defining usernames.
Dynamic Clients and NAS
RADIUSdesk offers two methods for declaring RADIUS clients.
1. Dynamic Clients
All Dynamic Clients have a common shared secret and are identified by the Nas-Identifier attribute of the incoming RADIUS request. This is typically used for clients that contact the RADIUS server from an unknown IP Address.
radiusdesk-dynamic-client.png
2. NAS
Each NAS is identified by the IP Address and each NAS can also have a unique shared secret. This is typically used for clients that contact the RADIUS server from a known IP Address.
radiusdesk-nas.png
Restricting Realms
RADIUSdesk enables realm restrictions for Dynamic Clients and NAS entries. You can limit access to specific realms, ensuring that users from unauthorized realms are denied network access. If a user who belongs to a realm that is not included attempts to access the network, the authentication request will be rejected.
Profiles
RADIUSdesk has a Profile applet used to manage user profiles. Each profile can contain multiple Profile Components. A Profile Component consists of a number of check and reply attributes. These attributes are selected from the dictionaries provided by FreeRADIUS. Sometimes the dictionaries in FreeRADIUS are different compared to the dictionary in Radiator. How to take care of this will be covered later in the document with a practical example.
Password Attribute
In recent FreeRADIUS releases, user passwords are stored in the Cleartext-Password attribute. This is a change from older releases, which used the User-Password attribute. RADIUSdesk follows the same convention as recent FreeRADIUS releases, using Cleartext-Password for storing user passwords.
Register Users
RADIUSdesk provides a comprehensive API that mirrors the functionality of its web GUI. With <AuthBy RADIUSdeskSQL>, you can leverage this API to auto-register unknown users.

RADIUSdesk and Radiator Dictionary Compatibility

RADIUSdesk utilizes FreeRADIUS dictionaries when formulating Profile Components. However, differences may exist between FreeRADIUS dictionary entries and those in Radiator.
Next will be a couple of practical points on environments where Juniper BNGs are used as RADIUS clients. For instance, the ERX dictionary used by Juniper equipment (typically located at /usr/share/freeradius/dictionary.erx) may have discrepancies.
FreeRADIUS dictionary snippet:
VENDOR        ERX 4874
BEGIN-VENDOR  ERX
ATTRIBUTE     ERX-Virtual-Router-Name 1 string
Radiator dictionary snippet:
#
# Define additional Unisphere ERX Family Attributes
# based on http://www.juniper.net/techpubs/software/junos/junos114/
# radius-dictionary/unisphereDictionary_for_JUNOS__v11-4.dct
#
VENDOR     ERX 4874
VENDORATTR 4874 Unisphere-Virtual-Router 1 string
Ensuring Compatibility
Since Radiator queries the SQL database using these values, it's crucial that Radiator can resolve the values from the SQL database. To achieve compatibility, use RADIUSdesk's dictionary override feature to align the FreeRADIUS dictionary with the Radiator dictionary. For more information, see: https://radiusdesk.com/wiki24/technical/fr-dictionary Opens in new window.

Disconnecting Active Sessions

RADIUSdesk's latest version features a Packet of Disconnect (POD) functionality, allowing you to send disconnect requests to BNG/RADIUS clients. This feature is triggered by the following actions:
  • Kicking an active session off using the "Kick User Off" button.
  • Disabling a permanent user with an active session.
  • Changing the profile of a permanent user with an active session.
The disconnect method used is determined by the Type option of a Dynamic Client or NAS in RADIUSdesk, with the logic defined in /var/www/rdcore/cake4/rd_cake/src/Controller/Component/KickerComponent.php
The Juniper type of equipment will typically require RADIUSdesk to send a COA/POD to the BNG. The snippet below shows the code from KickerComponent.php:
private function kickJuniperSession($ent){
  // -- Sample Disconnect —
  // echo "Acct-Session-ID='2040',User-Name='zaguy@example.com'" | radclient \
  // -c '1' -n '3' -r '3' -t '3' -x '127.0.0.1:3799' 'disconnect' 'testing123'
  $sessionid = $ent->acctsessionid;
  $username  = $ent->username;
  $ip        = $ent->nasipaddress;
  $fwd_ip    = $ip; // You can replace this with a central IP to forward it to
  $secret    = 'testing123';

  shell_exec("echo \"Acct-Session-ID='$sessionid',User-Name='$username',
  NAS-IP-Address='$ip'\" | radclient -c '1' -n '3'
  -r '3' -t '3' -x '$fwd_ip:3799' 'disconnect' '$secret'");
}
AuthBy RADIUSdeskSQL configuration parameters
Having covered these key concepts, we can now explore the available parameters for <AuthBy RADIUSdeskSQL>.

3.79.1. RealmChkDynamicClients

When set, this optional flag enables <AuthBy RADIUSdeskSQL> to apply restrictions defined for RADIUSdesk Dynamic Client items. These restrictions are based on the user's realm and the Nas-Identifier in the authentication request. Defaults to not enabled.
# Enable this flag parameter
RealmChkDynamicClients

3.79.2. RealmChkNas

When set, this optional flag enables <AuthBy RADIUSdeskSQL> to apply restrictions defined for RADIUSdesk NAS items. These restrictions are based on the user's realm and the IP address of the authentication request. Defaults to not enabled.
# Enable this flag parameter
RealmChkNas

3.79.3. AutoRegister

This optional flag enables the auto-registration feature. When set, additional mandatory parameters are required to ensure proper user registration functionality. Defaults to not enabled.
The following example shows all parameters that are required or typically configured when AutoRegister is enabled. Each parameter is described in detail separately.
AutoRegister
RegUrl       https://radiusdesk.example.com/cake4/rd_cake/permanent-users/add.json
RegSslCaFile %D/certs/radiusdesk-ca.pem
RegToken     c03cae5d-392c-4cb5-b422-4c628d451ced
RegCloudId   24
RegProfile   AUTOREGISTER
RegRealm     samplerealm
AutoRegisterHook file:"%D/rdAddPermanentUser.pl"

3.79.4. RegUrl

This parameter is required when AutoRegister is enabled. It specifies the API endpoint for registering users on RADIUSdesk, typically in the format: http[s]://<IP address|FQDN>/cake4/rd _ cake/permanent-users/add.json
When using a Fully Qualified Domain Name (FQDN), it's recommended to add the entry to the Radiator server's hosts file to ensure functionality in case of DNS failure.
RegUrl https://radiusdesk.example.com/cake4/rd_cake/permanent-users/add.json

3.79.5. RegSslCaFile

This optional parameter is used with AutoRegister. It locates the file containing the certificates of the trusted certificate authorities. If not defined when using https:// in RegUrl, <AuthBy RADIUSdeskSQL> will disable certificate verification. If set, certificate verification will be enforced. It's recommended to store the Certificate Authority file in the DbDir subdirectory named certs, for example /etc/radiator/certs/.
RegSslCaFile %D/certs/radiusdesk-ca.pem

3.79.6. RegToken

This parameter is required when AutoRegister is enabled. It specifies the API key that identifies a RADIUSdesk admin. This is used to authenticate API calls. The recommended way is to create a dedicated admin in RADIUSdesk for user registration and use the API key displayed when editing this admin's profile. Note that the API key will change if the admin's password is updated. 
RegToken c03cae5d-392c-4cb5-b422-4c628d451ced
radiusdesk-regtoken.png

3.79.7. RegCloudId

This parameter is required when AutoRegister is enabled. It specifies the ID of the Cloud under which the user will be registered. In RADIUSdesk, Clouds are entities that group items, and each Cloud has a unique ID. You can find the Cloud ID in the Clouds applet under the Cloud ID column.
RegCloudId 24

3.79.8. RegProfile

This parameter is required when AutoRegister is enabled. It specifies the profile that will be assigned to the newly registered user. The profile name must match an existing profile defined in RADIUSdesk.
RegProfile AUTOREGISTER

3.79.9. RegRealm

This parameter is required when AutoRegister is enabled. It specifies the realm that will be assigned to the newly registered user. The realm name must match an existing realm defined in RADIUSdesk.
RegRealm samplerealm

3.79.10. AutoRegisterHook

This parameter is required when AutoRegister is enabled. It the hook to register the user. A sample hook named rdAddPermanentUser.pl is in goodies directory radiusdesk.
AutoRegisterHook is called with the following arguments:
  1. A handle to the current Radius::AuthRADIUSdeskSQL object
  2. The username to be registered
  3. Reference to the current request
Here's an example of configuring AutoRegisterHook. This assumes we have our AutoRegisterHook file called rdAddPermanentUser.pl in the DbDir directory /etc/radiator
AutoRegisterHook file:"%D/rdAddPermanentUser.pl"

3.79.11. RecordExtraAttr1

This optional parameter specifies a RADIUS attribute that, if present in the incoming request, will:
  • Update the extra_name field of a permanent user upon successful authentication.
  • Populate the operator_name field in the radacct table on accounting start requests.
You can also add custom attributes to the RADIUS request packet before it reaches <AuthBy RADIUSdeskSQL>, allowing for flexibility beyond the attributes included in the original request from the RADIUS client.
RecordExtraAttr1 OSC-User-Identifier

3.79.12. AcctGroupname

This optional parameter records a string value in the groupname field of the radacct table on accounting start requests. It's useful in large deployments with multiple Radiator instances sharing a database, allowing you to tag or group instances with specific values, such as geographical locations.
AcctGroupname AU-01

3.79.13. AcctGroupId

This optional parameter records an integer value in the group_id field of the radacct table on accounting start requests. It's useful in large deployments with multiple Radiator instances sharing a database, enabling sharding to segment database tables.
To use this feature, apply the RADIUSdesk SQL patch 9.001_add_group_id_for_sharding.sql. See RADIUSdesk installation instructions for the details of applying RADIUSdesk SQL patches.
AcctGroupId 7

3.79.14. ConvertCleartextPassword, AuthCheck, AuthReply and other <AuthBy FREERADIUSSQL> parameters

ConvertCleartextPassword flag parameter is required in <AuthBy RADIUSdeskSQL> because RADIUSdesk stores user passwords as values in the Cleartext-Password check attribute in SQL. This parameter defaults to enabled and should only be disabled in special cases.
# Special configuration: disable this flag parameter
ConvertCleartextPassword 0
AuthCheck, AuthReply and other parameters also available in AuthBy FREERADIUS should only be set in special cases. At the time of writing, the default values match the RADIUSdesk defaults.
Table of Contents Table of contents: Radiator® AAA Server <AuthBy FREERADIUSSQL> 3.78 - <AuthBy FREERADIUSSQL> <AuthBy HTGROUP> 3.80 - <AuthBy HTGROUP>