Extending openwisp-radius

One of the core values of the OpenWISP project is Software Reusability, for this reason openwisp-radius provides a set of base classes which can be imported, extended and reused to create derivative apps.

In order to implement your custom version of openwisp-radius, you need to perform the steps described in this section.

When in doubt, the code in the test project and the sample app will serve you as source of truth: just replicate and adapt that code to get a basic derivative of openwisp-radius working.

If you want to add new users fields, please follow the tutorial to extend the openwisp-users. As an example, we have extended openwisp-users to sample_users app and added a field social_security_number in the sample_users/models.py.

Note

Premise: if you plan on using a customized version of this module, we suggest to start with it since the beginning, because migrating your data from the default module to your extended version may be time consuming.

1. Initialize your custom module

The first thing you need to do is to create a new django app which will contain your custom version of openwisp-radius.

A django app is nothing more than a python package (a directory of python scripts), in the following examples we’ll call this django app myradius, but you can name it how you want:

django-admin startapp myradius

Keep in mind that the command mentioned above must be called from a directory which is available in your PYTHON_PATH so that you can then import the result into your project.

Now you need to add myradius to INSTALLED_APPS in your settings.py, ensuring also that openwisp_radius has been removed:

import os

INSTALLED_APPS = [
    # ... other apps ...
    # openwisp admin theme
    'openwisp_utils.admin_theme',
    # all-auth
    'django.contrib.sites',
    'allauth',
    'allauth.account',
    'allauth.socialaccount',
    # admin
    'django.contrib.admin',
    # rest framework
    'rest_framework',
    'django_filters',
    # registration
    'rest_framework.authtoken',
    'dj_rest_auth',
    'dj_rest_auth.registration',
    # social login
    'allauth.socialaccount.providers.facebook',  # optional, can be removed if social login is not needed
    'allauth.socialaccount.providers.google',  # optional, can be removed if social login is not needed
    # SAML login
    'djangosaml2',  # optional, can be removed if SAML login is not needed
    # openwisp
    # 'myradius', <-- replace with your app-name here
    'openwisp_users',
    'private_storage',
    'drf_yasg'
]

SITE_ID = 1
MEDIA_ROOT = os.path.join(BASE_DIR, 'media')
PRIVATE_STORAGE_ROOT = os.path.join(MEDIA_ROOT, 'private')

AUTHENTICATION_BACKENDS = (
    'openwisp_users.backends.UsersAuthenticationBackend',
    'openwisp_radius.saml.backends.OpenwispRadiusSaml2Backend', # optional, can be removed if SAML login is not needed
)

Important

Remember to include your radius app’s name before proceeding.

Note

For more information about how to work with django projects and django apps, please refer to the django documentation.

2. Install `openwisp-radius`

Install (and add to the requirement of your project) openwisp-radius:

pip install openwisp-radius

Note

Use pip install openwisp-radius[saml] if you intend to use Single Sign-On (SAML) feature.

3. Add `EXTENDED_APPS`

Add the following to your settings.py:

EXTENDED_APPS = ('openwisp_radius',)

4. Add `openwisp_utils.staticfiles.DependencyFinder`

Add openwisp_utils.staticfiles.DependencyFinder to STATICFILES_FINDERS in your settings.py:

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'openwisp_utils.staticfiles.DependencyFinder',
]

5. Add `openwisp_utils.loaders.DependencyLoader`

Add openwisp_utils.loaders.DependencyLoader to TEMPLATES in your settings.py, but ensure it comes before django.template.loaders.app_directories.Loader:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'OPTIONS': {
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'openwisp_utils.loaders.DependencyLoader',
                'django.template.loaders.app_directories.Loader',
            ],
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    }
]

6. Inherit the AppConfig class

Please refer to the following files in the sample app of the test project:

You have to replicate and adapt that code in your project.

Note

For more information regarding the concept of AppConfig please refer to the “Applications” section in the django documentation.

7. Create your custom models

For the purpose of showing an example, we added a simple details field to the models of the sample app in the test project.

You can add fields in a similar way in your models.py file.

Note

For doubts regarding how to use, extend or develop models please refer to the “Models” section in the django documentation.

8. Add swapper configurations

Once you have created the models, add the following to your settings.py:

# Setting models for swapper module
OPENWISP_RADIUS_RADIUSREPLY_MODEL = 'myradius.RadiusReply'
OPENWISP_RADIUS_RADIUSGROUPREPLY_MODEL = 'myradius.RadiusGroupReply'
OPENWISP_RADIUS_RADIUSCHECK_MODEL = 'myradius.RadiusCheck'
OPENWISP_RADIUS_RADIUSGROUPCHECK_MODEL = 'myradius.RadiusGroupCheck'
OPENWISP_RADIUS_RADIUSACCOUNTING_MODEL = 'myradius.RadiusAccounting'
OPENWISP_RADIUS_NAS_MODEL = 'myradius.Nas'
OPENWISP_RADIUS_RADIUSUSERGROUP_MODEL = 'myradius.RadiusUserGroup'
OPENWISP_RADIUS_RADIUSPOSTAUTH_MODEL = 'myradius.RadiusPostAuth'
OPENWISP_RADIUS_RADIUSBATCH_MODEL = 'myradius.RadiusBatch'
OPENWISP_RADIUS_RADIUSGROUP_MODEL = 'myradius.RadiusGroup'
OPENWISP_RADIUS_RADIUSTOKEN_MODEL = 'myradius.RadiusToken'
OPENWISP_RADIUS_PHONETOKEN_MODEL = 'myradius.PhoneToken'
OPENWISP_RADIUS_ORGANIZATIONRADIUSSETTINGS_MODEL = 'myradius.OrganizationRadiusSettings'
OPENWISP_RADIUS_REGISTEREDUSER_MODEL = 'myradius.RegisteredUser'

# You will need to change AUTH_USER_MODEL if you are extending openwisp_users
AUTH_USER_MODEL = 'openwisp_users.User'

Substitute myradius with the name you chose in step 1.

9. Create database migrations

Copy the migration files from the sample_radius’s migration folder.

Now, create database migrations as per your custom application’s requirements:

./manage.py makemigrations

If you are starting with a fresh database, you can apply the migrations:

./manage.py migrate

However, if you want migrate an existing freeradius database please read the guide in the setup.

Note

For more information, refer to the “Migrations” section in the django documentation.

10. Create the admin

Refer to the admin.py file of the sample app.

To introduce changes to the admin, you can do it in two main ways which are described below.

Note

For more information regarding how the django admin works, or how it can be customized, please refer to “The django admin site” section in the django documentation.

1. Monkey patching

If the changes you need to add are relatively small, you can resort to monkey patching.

For example:

from openwisp_radius.admin import (
    RadiusCheckAdmin,
    RadiusReplyAdmin,
    RadiusAccountingAdmin,
    NasAdmin,
    RadiusGroupAdmin,
    RadiusUserGroupAdmin,
    RadiusGroupCheckAdmin,
    RadiusGroupReplyAdmin,
    RadiusPostAuthAdmin,
    RadiusBatchAdmin,
)
# NasAdmin.fields += ['example_field'] <-- Monkey patching changes example

2. Inheriting admin classes

If you need to introduce significant changes and/or you don’t want to resort to monkey patching, you can proceed as follows:

from django.contrib import admin
from openwisp_radius.admin import (
    RadiusCheckAdmin as BaseRadiusCheckAdmin,
    RadiusReplyAdmin as BaseRadiusReplyAdmin,
    RadiusAccountingAdmin as BaseRadiusAccountingAdmin,
    NasAdmin as BaseNasAdmin,
    RadiusGroupAdmin as BaseRadiusGroupAdmin,
    RadiusUserGroupAdmin as BaseRadiusUserGroupAdmin,
    RadiusGroupCheckAdmin as BaseRadiusGroupCheckAdmin,
    RadiusGroupReplyAdmin as BaseRadiusGroupReplyAdmin,
    RadiusPostAuthAdmin as BaseRadiusPostAuthAdmin,
    RadiusBatchAdmin as BaseRadiusBatchAdmin,
)
from swapper import load_model
Nas = load_model('openwisp_radius', 'Nas')
RadiusAccounting = load_model('openwisp_radius', 'RadiusAccounting')
RadiusBatch = load_model('openwisp_radius', 'RadiusBatch')
RadiusCheck = load_model('openwisp_radius', 'RadiusCheck')
RadiusGroup = load_model('openwisp_radius', 'RadiusGroup')
RadiusPostAuth = load_model('openwisp_radius', 'RadiusPostAuth')
RadiusReply = load_model('openwisp_radius', 'RadiusReply')
PhoneToken = load_model('openwisp_radius', 'PhoneToken')
RadiusGroupCheck = load_model('openwisp_radius', 'RadiusGroupCheck')
RadiusGroupReply = load_model('openwisp_radius', 'RadiusGroupReply')
RadiusUserGroup = load_model('openwisp_radius', 'RadiusUserGroup')
OrganizationRadiusSettings = load_model('openwisp_radius', 'OrganizationRadiusSettings')
User = get_user_model()

admin.site.unregister(RadiusCheck)
admin.site.unregister(RadiusReply)
admin.site.unregister(RadiusAccounting)
admin.site.unregister(Nas)
admin.site.unregister(RadiusGroup)
admin.site.unregister(RadiusUserGroup)
admin.site.unregister(RadiusGroupCheck)
admin.site.unregister(RadiusGroupReply)
admin.site.unregister(RadiusPostAuth)
admin.site.unregister(RadiusBatch)

@admin.register(RadiusCheck)
class RadiusCheckAdmin(BaseRadiusCheckAdmin):
    # add your changes here

@admin.register(RadiusReply)
class RadiusReplyAdmin(BaseRadiusReplyAdmin):
    # add your changes here

@admin.register(RadiusAccounting)
class RadiusAccountingAdmin(BaseRadiusAccountingAdmin):
    # add your changes here

@admin.register(Nas)
class NasAdmin(BaseNasAdmin):
    # add your changes here

@admin.register(RadiusGroup)
class RadiusGroupAdmin(BaseRadiusGroupAdmin):
    # add your changes here

@admin.register(RadiusUserGroup)
class RadiusUserGroupAdmin(BaseRadiusUserGroupAdmin):
    # add your changes here

@admin.register(RadiusGroupCheck)
class RadiusGroupCheckAdmin(BaseRadiusGroupCheckAdmin):
    # add your changes here

@admin.register(RadiusGroupReply)
class RadiusGroupReplyAdmin(BaseRadiusGroupReplyAdmin):
    # add your changes here

@admin.register(RadiusPostAuth)
class RadiusPostAuthAdmin(BaseRadiusPostAuthAdmin):
    # add your changes here

@admin.register(RadiusBatch)
class RadiusBatchAdmin(BaseRadiusBatchAdmin):
    # add your changes here

11. Setup Freeradius API Allowed Hosts

Add allowed freeradius hosts in settings.py:

OPENWISP_RADIUS_FREERADIUS_ALLOWED_HOSTS = ['127.0.0.1']

Note

12. Setup Periodic tasks

Some periodic commands are required in production environments to enable certain features and facilitate database cleanup:

You need to create a celery configuration file as it’s created in example file.

2. In the settings.py, configure the CELERY_BEAT_SCHEDULE. Some celery tasks take an argument, for instance 365 is given here for delete_old_radacct in the example settings. These arguments are passed to their respective management commands. More information about these parameters can be found at the management commands page.

Add the following in your settings.py file:

CELERY_IMPORTS = ('openwisp_monitoring.device.tasks',)

Note

Celery tasks do not start with django server and need to be started seperately, please read about running celery and celery-beat tasks.

13. Create root URL configuration

The root url.py file should have the following paths (please read the comments):

from openwisp_radius.urls import get_urls
# Only imported when views are extended.
# from myradius.api.views import views as api_views
# from myradius.social.views import views as social_views
# from myradius.saml.views import views as saml_views

urlpatterns = [
    # ... other urls in your project ...
    path('admin/', admin.site.urls),
    # openwisp-radius urls
    path('accounts/', include('openwisp_users.accounts.urls')),
    path('api/v1/', include('openwisp_utils.api.urls')),
    # Use only when extending views (dicussed below)
    # path('', include((get_urls(api_views, social_views, saml_views), 'radius'), namespace='radius')),
    path('', include('openwisp_radius.urls', namespace='radius')), # Remove when extending views
]

Note

For more information about URL configuration in django, please refer to the “URL dispatcher” section in the django documentation.

14. Import the automated tests

When developing a custom application based on this module, it’s a good idea to import and run the base tests too, so that you can be sure the changes you’re introducing are not breaking some of the existing features of openwisp-radius.

In case you need to add breaking changes, you can overwrite the tests defined in the base classes to test your own behavior.

See the tests of the sample app to find out how to do this.

You can then run tests with:

# the --parallel flag is optional
./manage.py test --parallel myradius

Substitute myradius with the name you chose in step 1.

Other base classes that can be inherited and extended

The following steps are not required and are intended for more advanced customization.

1. Extending the API Views

The API view classes can be extended into other django applications as well. Note that it is not required for extending openwisp-radius to your app and this change is required only if you plan to make changes to the API views.

Create a view file as done in API views.py.

Remember to use these views in root URL configurations in point 11. If you want only extend the API views and not social views, you can use get_urls(api_views, None) to get social_views from openwisp_radius.

Note

For more information about django views, please refer to the views section in the django documentation.

3. Extending the SAML Views

The SAML view classes can be extended into other django applications as well. Note that it is not required for extending openwisp-radius to your app and this change is required only if you plan to make changes to the SAML views.

Create a view file as done in saml views.py.

Remember to use these views in root URL configurations in point 11. If you want only extend the API views and social view but not SAML views, you can use get_urls(api_views, social_views, None) to get saml_views from openwisp_radius.

Note

For more information about django views, please refer to the views section in the django documentation.

Extending openwisp-radius

1. Initialize your custom module

2. Install openwisp-radius

3. Add EXTENDED_APPS

4. Add openwisp_utils.staticfiles.DependencyFinder

5. Add openwisp_utils.loaders.DependencyLoader

6. Inherit the AppConfig class

7. Create your custom models

8. Add swapper configurations

9. Create database migrations

10. Create the admin

1. Monkey patching

2. Inheriting admin classes

11. Setup Freeradius API Allowed Hosts

12. Setup Periodic tasks

13. Create root URL configuration

14. Import the automated tests

Other base classes that can be inherited and extended

1. Extending the API Views

2. Extending the Social Views

3. Extending the SAML Views

2. Install `openwisp-radius`

3. Add `EXTENDED_APPS`

4. Add `openwisp_utils.staticfiles.DependencyFinder`

5. Add `openwisp_utils.loaders.DependencyLoader`