How to customize an OEM instance of FreeRADIUS

Getting the most out of your OEM deployment

As the most popular RADIUS server in the world, FreeRADIUS is used by many hardware vendors. They ship their products with FreeRADIUS embedded as an embedded or “OEM” product. It is common for them to need some additional features or some customizations which are not part of the core FreeRADIUS functionality.

With Open Source software, the temptation for vendors is to say “we have the source, we can change it”, and then make many changes to create a custom version of FreeRADIUS. This process does not always work. Vendors can make their lives easier by following our best practices for customization, which we outline here.

Our guiding principle for FreeRADIUS customization is to keep things simple and modular, by leveraging its API and its plugin architecture. This practice makes upgrade paths much simpler, and the embedded product much easier to maintain. It can also have positive legal implications!

Best practice #1: Don’t make changes to the core code

It can be tempting to build customizations directly into the core code of FreeRADIUS. However, there are some serious drawbacks to this approach.

It makes upgrades difficult. Whenever a new version of FreeRADIUS is released, any local changes will have to be integrated into the new version. These local changes may conflict with changes made in the upstream distribution, and can require significant work to merge. In addition, there will be additional work on testing and QA in order to ensure quality and stability. All of this effort takes time and expertise.

Any new FreeRADIUS features will need to be re-implemented. If a new release of FreeRADIUS has some functionality that a vendor would like to use, it is often difficult to integrate those features into a heavily modified implementation. Typically, the vendor ends up having to re-implement the new features themselves into their own customized version. Which is another waste of time and resources.

It requires maintaining RADIUS expertise in house. One of the key benefits of embedding FreeRADIUS as an OEM product is that you do not need to have any particular RADIUS expertise in-house to use it. FreeRADIUS handles the RADIUS portion of the work, and your team can focus on the part which integrates it with the rest of your product. In addition, your team can rely on Network RADIUS for any RADIUS or FreeRADIUS questions.

Once you start making customizations to the core code, you lose the benefit of using an upstream release. A local version which is heavily modified will require significant experience in RADIUS and FreeRADIUS, In order to maintain the product over multiple releases and over multiple years. If anyone on the local team moves elsewhere, the company will be left with software which is critical for a product line, but which has no one internally to support or even understand it.

In our experience working with OEM vendors of FreeRADIUS, we’ve seen cases where upgrades are avoided altogether because the system is so heavily patched that it is essentially a custom RADIUS server. This approach is costly, and is not recommended.

Best practice #2: Leverage the API and plugin modules

In most cases, customizations to FreeRADIUS can be handled through its powerful plugin architecture.

Plugin modules communicate with FreeRADIUS via an internal API which has been unchanged for many years. If a vendor has a proprietary system which needs to exchange information with FreeRADIUS, it is possible to create a separate plugin module which accesses the external system. Similarly, a vendor needing new functionality can create a custom module which implements that functionality. This module will have full access to the FreeRADIUS internals, and can do just about anything.

Because the FreeRADIUS software is publicly available, we have seen some vendors put their customizations directly into the core APIs of FreeRADIUS. This approach gives them the worst of both the open source world, and the proprietary software world.

Because they are altering an open source product, they must release their customizations under a GPL license as well. This of course might reveal more than they want to about their proprietary products. Conversely, because their customizations are embedded in various places throughout the source code, there are usually only a handful of people on the vendor side that understand and are able to maintain it.

Aside from just being a better programming practice in general, the use of plugin module makes a clear separation between the Open Source code, and any external APIs used by the vendor. The result is that a vendor can have a standard RADIUS server, accommodate highly customized behavior, and protect their intellectual property all at the same time.

Best practice #3: Keep data external to FreeRADIUS where possible

Vendors sometimes maintain user account information and configurations within the FreeRADIUS server, in custom configuration. This practice is not recommended. Any bulk data should be stored in a database. Database APIs are standardized, well understood, and can be easily accessed by external systems. In contrast, configuration files are bespoke, and it is difficult to share the information the contain via a simple API.

A common use-case is to have many users, but only a few different types of user profile. For example, user profiles could be “super-user”, “admin”, “read-only”, or “normal”. These profiles could be assigned to many thousands of users.

Even worse, the use of devices from multiple network equipment vendors means that the RADIUS response required to set the “admin” profile may be different from vendor to vendor!

For this scenario, any RADIUS-specific profiles need to be kept in the FreeRADIUS configuration. However, these profiles are few in number, the contents of the profile are small (only a few if / then / else conditions and setting of attributes), and the profiles rarely change.

In contrast, there are many thousands of users, where those users are added, deleted, and modified regularly. That user information belongs in a database, which can contain the profile name along with any additional per-user data such as names, passwords, etc..

The bottom line

FreeRADIUS provides many mechanisms for allowing customizations to be implemented without touching the core code at all. This modularity is very much by design, making FreeRADIUS extremely flexible and able to integrate with external systems, without requiring deep expertise of the underlying technology.

In general, OEM vendors should make use tools like configuration files, external databases, plugin modules, and the internal APIs in order to achieve the customization they need.

We’re here to help!

FreeRADIUS is used by all of the cloud-based RADIUS providers, as well as nearly all the networking companies (Aruba, Extreme, etc.) and token card companies (RSA, etc.). We’ve helped those customers build and maintain their OEM versions of FreeRADIUS. In cases where we’ve been involved from the start, maintenance is straightforward. We check configuration files and their REST API and the vendor is off to the races. In other cases where the source code has been heavily modified before we’re called in, we need to spend a lot of time untangling the changes that have been made before we can even start moving forward.

If you need help with an OEM implementation of FreeRADIUS, reach out to us by visiting our quote page.