Ironchip RADIUS server

The Ironchip RADIUS server is Ironchip’s own RADIUS server. It lets you integrate RADIUS-compatible services using an API key, without needing NPS. This guide is for the administrator who installs it on Windows or Linux. It works without passwords: the user approves access on their device.

Requirements

Access to the Ironchip admin console.
A 64-bit Windows or Linux server to run the RADIUS server on.
The device or service you want to protect (VPN, firewall, wifi) must be able to send RADIUS requests to UDP port 1812 on that server.
The users enrolled in Ironchip, or identity synchronization configured.

Configure Ironchip

Create a Passwordless RADIUS application. The console gives you an API key that the RADIUS server uses to talk to Ironchip.

Go to Applications and click New application.
In the Standard authentication protocols section, choose Passwordless RADIUS.
Give it an identifying name (at least 3 characters) and click Add.
Copy the API key or click Download credentials to download it in the credentials.json file.

Configure the Ironchip RADIUS server

Download the executable from the latest release: ironchip_lbauth_radius_server.exe for Windows or ironchip_lbauth_radius_server for Linux.
Copy it to a permanent folder on the server. The service runs from that location, so do not move it afterward.
Next to the executable, create a configuration file with the same name as the executable and a .json extension: ironchip_lbauth_radius_server.json. If you rename the executable, rename the file too.

Paste this content and replace the values in <>:

{
  "radius_address": "0.0.0.0:1812",
  "radius_key": "<SHARED_SECRET>",
  "ironchip_api_host": "https://api.ironchip.com",
  "ironchip_api_secret": "<API_KEY>",
  "log_level": "info"
}

Open a terminal with administrator privileges (PowerShell on Windows, or use sudo on Linux) and go to the executable’s folder.

Install the service:

.\ironchip_lbauth_radius_server.exe service install

chmod +x ironchip_lbauth_radius_server
sudo ./ironchip_lbauth_radius_server service install

Start the service:

.\ironchip_lbauth_radius_server.exe service start

sudo ./ironchip_lbauth_radius_server service start

Configure the service you want to protect to use this server as its RADIUS server: the address of the machine where it runs, port 1812, and the same shared secret you set in radius_key.

Configuration file fields

Field	Required	Default	Description
`radius_address`	No	`0.0.0.0:1812`	Address and UDP port the server listens on.
`radius_key`	Yes		Secret shared with the device that sends the RADIUS requests. You choose it, but it must be the same in the file and on that device.
`ironchip_api_host`	No	`https://api.ironchip.com`	URL of the Ironchip API.
`ironchip_api_secret`	Yes		The API key of the Passwordless RADIUS application.
`log_level`	No	`info`	Log level: `debug`, `info`, `warning`, `error` or `fatal`.
`attributes`	No		Standard RADIUS attributes added to the access-accept response. See Response attributes.
`vendor-specific_attributes`	No		Vendor-specific attributes added to the response. See Response attributes.

The executable reads this file with every command, including service install, so create it before you install the service. If the file is not found, a required field is missing or log_level is not valid, it exits with an error.

Response attributes

Some devices need attributes in the RADIUS response, for example to assign each user a VPN group. Define them in attributes (standard attributes from RFC 2865) and in vendor-specific_attributes (vendor attributes, which the server sends inside attribute 26). Each attribute has three fields:

number: the attribute number. In vendor-specific_attributes it is the vendor number (Vendor-Id).
type: the data type: string, short, integer or integer64.
data: a fixed value or a template with data about the user who just authenticated.

You can repeat the same number in several attributes. The template must be the whole value of data, as in the example below: if you mix it with other text, the attribute is not sent. These are the available templates:

Template	Data
`{{.subject}}`	User identifier.
`{{.name}}`	User name.
`{{.email}}`	User email address.
`{{.timestamp}}`	Timestamp of the authorization.
`{{.external_username}}`	Username in the external service.
`{{.external_service_id}}`	Identifier of the external service.
`{{.customer_name}}`	Company name.
`{{.group_names}}`	The user’s groups. One attribute is sent for each group.
`{{.location_name}}`	Name of the location the user connects from.
`{{.location_score}}`	Location score.

{
  "radius_address": "0.0.0.0:1812",
  "radius_key": "<SHARED_SECRET>",
  "ironchip_api_host": "https://api.ironchip.com",
  "ironchip_api_secret": "<API_KEY>",
  "log_level": "info",
  "attributes": [{ "number": 11, "type": "string", "data": "{{.group_names}}" }],
  "vendor-specific_attributes": [{ "number": 43, "type": "string", "data": "1304" }]
}

In this example, the Filter-Id attribute (11) carries the name of each of the user’s groups. Use the string type unless the device requires another.

Verify the integration

Check that the service is running:

.\ironchip_lbauth_radius_server.exe service status

sudo ./ironchip_lbauth_radius_server service status

The output includes status: running.

Sign in from the protected service with an Ironchip user. The user receives the approval request on their device and, once they approve it, the server answers with access accepted. If Ironchip does not authorize the user, it answers with access rejected.

The server uses only the username in the request; the password is ignored. Some devices still require it to be filled in, as the example below shows.

Service commands

The executable is managed with service (alias s). service status also has the alias s, so s s is the same as service status.

Command	What it does
`service install`	Installs the `IronchipRADIUS` service (display name: Ironchip RADIUS server).
`service start`	Starts the service.
`service stop`	Stops the service.
`service restart`	Restarts the service. Do this after changing the configuration file.
`service status`	Shows whether the service is running (`running`) or stopped (`stopped`).
`service uninstall`	Uninstalls the service.
`service run`	Runs the server in the terminal, outside the service manager. Fails if the service is not installed or is already running.

Logs

On Windows, the server writes to Event Viewer, in the Application log, with the source Ironchip RADIUS Server. On Linux it writes to the process output, which the system’s service manager collects (with systemd, read it with journalctl -u IronchipRADIUS). Raise log_level to debug to see the detail of each authorization, and set it back to info when you are done.

Troubleshooting

The service does not start: check that the .json file exists with the same name as the executable, in the same folder, and that radius_key and ironchip_api_secret have a value.
The device gets no response: open UDP port 1812 (or the one in radius_address) in the server’s firewall and check that the device points to the right IP address.
Access rejected for a user who exists: check that ironchip_api_secret is the API key of the Passwordless RADIUS application and that the username in the request is the one Ironchip knows. The server logs the authorization error.
The shared secret does not match: the device discards the responses. Use exactly the same value in radius_key and on the device.
Attributes are missing from the response: check that each data is a fixed value or a single template and that the data matches the type. If an attribute fails, the server still accepts the access, but it does not send that attribute or the ones after it, and it logs the error.

Authentication example

The video shows access to a WatchGuard VPN with the Ironchip RADIUS server running.

In the video, a password is entered because WatchGuard does not allow empty fields. The text in that field can be random, as in the two examples in the video.

Accessing a WatchGuard VPN with the Ironchip RADIUS serverPlay video

Was this page helpful?