alphagov / govwifi-frontend

Freeradius server configuration for GovWifi

GovWifi Frontend

Purpose

This is the FreeRADIUS configuration for the GovWiFi project.

How to install and use

Currently it is not possible to run this service from inside this repository alone.

We instead recommend using the acceptance-tests repo to set up a development environment for making changes to FreeRADIUS or the healthcheck service.

Makefile targets are:

• make test - Currently a no-op. Tests are located in the acceptance-tests repo
• make lint - Runs linting on the healtcheck service, provided by rubocop-govuk

Components

This project has three main components: the RADIUS server, the FreeRADIUS Prometheus Exporter, and the healthcheck service.

This RADIUS server is restarted daily by a separate app, the Safe Restarter.

Healthcheck

When hit with a HTTP call, the healthcheck service will test the radius server to ensure it can still authorise users.

To accomplish this, eapol_test is used to simulate authentication using PEAP-MSCHAPv2.

All code is located under the healthcheck directory.

Radius

FreeRadius is an implementation of the RADIUS protocol.

Our servers implement:

• EAP-TLS (client certificate authentication)
• PEAP-MSCHAPv2 (Protected EAP with username + password)

Files

There are currently 5 files fetched when the service is initialised.

• clients.conf Allows access points to communicate with the radius servers. This is generated by the GovWifi Admin service.
• ca.pem, server.pem, server.key Used to set up TLS tunnels, and authenticate clients using EAP-TLS

They are currently stored in an encrypted S3 bucket, and only the RADIUS servers are authorised to access files within the bucket.

Files are fetched once a night when the servers are restarted for updates.

High Level Process

When someone attempts to use GovWifi:

1. The username and password is sent to the radius server
2. Radius receives, and sends a request to the authentication backend to fetch the known password
3. The user password is checked against the known password
4. the login attempt is logged in the logging backend
5. either the user is accepted, or rejected depending on whether their password accepted.

FreeRADIUS Prometheus Exporter

The FreeRADIUS Prometheus Exporter is an open source Prometheus exporter for FreeRADIUS.

It uses the FreeRADIUS Status Server to query information about server state and the packages being processed. The Status Server is enabled by adding the status configuration file to the radius/sites-enabled directory.

The Prometheus exporter exposes these metrics on /metrics which can be then read by a Prometheus server.

For more information see the FreeRADIUS Prometheus Exporter's readme. For information about configuring the Status Server please see FreeRADIUS's documentation.

How to contribute

1. Fork the project
2. Create a feature or fix branch
3. Run the linter: make lint
4. Run the acceptance tests
5. Raise a pull request

License

This codebase is released under the MIT License.