Skip to content

operator-mfa.md

Latest commit

 

History

History
131 lines (95 loc) · 4.31 KB

operator-mfa.md

File metadata and controls

131 lines (95 loc) · 4.31 KB

Operator two-factor authentication recovery

This guide explains how to reset two-factor authentication (2FA/MFA) for a daloRADIUS operator account from the server command line. Use it when an operator has lost access to their authenticator app or recovery codes and cannot complete login.

Resetting MFA does not change the operator password and does not delete the operator account. It only clears the TOTP secret, last accepted counter, confirmation timestamp, and recovery codes. The operator can then log in with their existing password and enroll MFA again from the operators interface.

Before you start

  1. Log in to the server that hosts the daloRADIUS database.
  2. Identify the operator username to reset.
  3. Identify the daloRADIUS database name, user, and operators table name.

For standard installations these values are configured in:

app/common/includes/daloradius.conf.php

The relevant settings are:

$configValues['CONFIG_DB_USER'] = 'raduser';
$configValues['CONFIG_DB_PASS'] = 'radpass';
$configValues['CONFIG_DB_NAME'] = 'raddb';
$configValues['CONFIG_DB_TBL_DALOOPERATORS'] = 'operators';

If your installation uses different values, replace the example database name and table name in the commands below.

Upgrading an existing installation

Fresh installations already include the operator MFA schema in contrib/db/mariadb-daloradius.sql. Existing installations must apply the database migration before operators enable MFA or use the MFA recovery page.

Back up the database first, then run the migration script from the daloRADIUS source tree.

For a standard MariaDB/MySQL installation:

mariadb -u raduser -p raddb < contrib/db/migrations/2026-06-operator-totp-mfa.sql

For a Docker Compose installation, run this from the directory that contains docker-compose.yml:

docker compose exec -T radius-mysql sh -lc 'mariadb -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' \
  < contrib/db/migrations/2026-06-operator-totp-mfa.sql

The migration is idempotent: it adds the missing MFA columns and registers the MFA page in the operators ACL metadata if they are not already present.

Standard MariaDB/MySQL installation

In the examples below, replace administrator with the operator username you want to unlock.

Check that the operator exists and confirm their current MFA state:

mariadb -u raduser -p raddb <<'SQL'
SELECT id, username, totp_enabled, totp_confirmed_at
FROM operators
WHERE username = 'administrator';
SQL

Reset MFA for that operator:

mariadb -u raduser -p raddb <<'SQL'
UPDATE operators
   SET totp_enabled = 0,
       totp_secret = NULL,
       totp_last_counter = NULL,
       totp_confirmed_at = NULL,
       totp_recovery_codes = NULL
 WHERE username = 'administrator';
SQL

Verify the reset:

mariadb -u raduser -p raddb <<'SQL'
SELECT id, username, totp_enabled, totp_confirmed_at
FROM operators
WHERE username = 'administrator';
SQL

The totp_enabled value should now be 0.

Note: If the operator username contains a single quote ('), escape it for SQL by replacing it with two single quotes ('') before running the commands.

Docker Compose installation

Run these commands from the directory that contains docker-compose.yml. Replace administrator with the operator username you want to unlock.

Check that the operator exists:

docker compose exec -T radius-mysql sh -lc 'mariadb -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' <<'SQL'
SELECT id, username, totp_enabled, totp_confirmed_at
FROM operators
WHERE username = 'administrator';
SQL

Reset MFA for that operator:

docker compose exec -T radius-mysql sh -lc 'mariadb -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' <<'SQL'
UPDATE operators
   SET totp_enabled = 0,
       totp_secret = NULL,
       totp_last_counter = NULL,
       totp_confirmed_at = NULL,
       totp_recovery_codes = NULL
 WHERE username = 'administrator';
SQL

Verify the reset:

docker compose exec -T radius-mysql sh -lc 'mariadb -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' <<'SQL'
SELECT id, username, totp_enabled, totp_confirmed_at
FROM operators
WHERE username = 'administrator';
SQL

The operator can now log in with their existing password. Ask them to re-enable two-factor authentication and store their new recovery codes.