[Plugin] os-keyrad – RADIUS server GUI with Keycloak backend

[Moeni]

Hi everyone,

I wanted to share a small side project that might be useful for anyone running Keycloak as their identity provider who wants to use it in combination with a RADIUS server.

What is it?

keyrad is a standalone RADIUS server written in Go that authenticates users directly against Keycloak. It's not a wrapper around FreeRADIUS. It maps Keycloak roles, groups, and scopes to RADIUS attributes, including MikroTik VSAs (which was one of the original use cases).

Key benefit: OTP/TOTP support

A major advantage of keyrad is that it supports password + OTP/TOTP authentication together with Keycloak. The plugin exposes the OTP challenge message and the relevant authentication toggles in the GUI (PAP, challenge-response, Message-Authenticator). If you're already using Keycloak with TOTP for your users, this lets you bring that same second factor to RADIUS-authenticated services (WPA2-Enterprise WiFi, VPN gateways, hotspot logins) without standing up a separate OTP backend or maintaining a parallel user database.

The OPNsense part:

os-keyrad is an OPNsense MVC plugin that gives you a web GUI to manage keyrad. It handles general settings (Keycloak URLs, realm, client credentials, RADIUS listen address), a clients grid (FreeRADIUS-style shared secrets), an attribute mappings grid (roles/groups to RADIUS attributes), and service control (start/stop/restart/apply). The plugin renders the keyrad.yaml and clients.conf files via the standard template engine.

Important warnings to be upfront about:

• This is a GUI-only plugin: The keyrad daemon binary is not included. You need to cross-compile it for FreeBSD/OPNsense and place it at /usr/local/bin/keyrad manually. Instructions are in the repo.
• Testing status: The core keyrad project is at v2.0.x and is already used in production environments. The OPNsense GUI is newer still. I would classify this as "ready for curious testers" rather than production-ready. On my OPNsense(DEC740) it works as intendet.

Links:

OPNsense plugin (os-keyrad): https://github.com/gpappsoft/os-keyrad

Core RADIUS server (keyrad): https://github.com/gpappsoft/keyrad

Original MikroTik forum thread: link

Why post here?

I know the OPNsense community values transparency and proper packaging. I'm posting this to see if there's interest and to get feedback from anyone who might test it – particularly on the plugin's MVC structure, the template generation, or any FreeBSD-specific issues with the binary.


Happy to answer any questions, and thanks for looking.

Cheers,
Marco

[Patrick M. Hausen]

This is great news! Thanks for sharing.

We are very interested in any path that allows us to throw AD/LDAP out the window in favour of Keycloak (where we already have built substantial experience and even sell consulting), so this might be just the missing component for systems that do not support OpenID.