本指南记录在 Ubuntu 22.04 LTS 环境下,基于 FreeRADIUS 3.x + PAM + Google Authenticator 构建双因子认证(2FA)服务,并对接企业 SSL-VPN 网关的完整实现方案,包含架构说明、环境部署、权限沙盒适配、自动化管理脚本及排错复盘。


一、 认证架构与交互原理

1. 认证拓扑

[ 用户端 ] 
    │  密码框输入: 静态密码 + 6位动态口令 (例: abcd123888666)
    ▼
[ SSL-VPN 网关 ] (PAP 协议转发原始凭据)
    │  RADIUS Access-Request (包含完整的拼接密码字符串)
    ▼
[ FreeRADIUS 服务 (UDP:1812) ]
    │  调用系统 PAM 接口 (/etc/pam.d/radiusd)
    ▼
[ PAM 认证链 ]
    ├── 1. pam_google_authenticator: 剥离末尾 6 位,对比 /etc/freeradius/3.0/otp/${USER} 计算 TOTP
    └── 2. pam_unix: 接收前半段静态密码,校验 /etc/shadow
    ▼
[ FreeRADIUS 返回 Access-Accept / Access-Reject ]

2. 核心设计原则

  • 密码拼接模式:客户端仅需单个密码输入框,兼容所有主流硬件与软件 VPN 网关,无需网关客户端支持复杂的二次挑战应答(Challenge-Response)。
  • 独立 OTP 集中存储:Google 令牌文件统一存放于 /etc/freeradius/3.0/otp/,避免服务进程跨用户读取家目录导致的权限与沙盒冲突。
  • 最小权限运行:保持 FreeRADIUS 运行于系统默认的 freerad 用户,通过 Systemd 组补充与路径放行机制满足安全基线。

二、 基础环境与组件安装

1. 节点时间校准(关键前提)

TOTP 动态令牌严格基于当前 Unix 时间戳计算(每 30 秒一个步长),服务器时间必须高度同步。

# 设置时区并启用 NTP 时间同步
sudo timedatectl set-timezone Asia/Shanghai
sudo timedatectl set-ntp true

# 检查系统时间状态
timedatectl status

验证指标:System clock synchronized: yes,且与标准时间误差需控制在 15 秒以内。

2. 安装核心软件包

sudo apt update
sudo apt install -y freeradius freeradius-utils libpam-google-authenticator qrencode

三、 Systemd 沙盒与服务权限加固(关键踩坑处理)

Ubuntu 22.04 的 FreeRADIUS Systemd 服务默认启用了严格的安全沙盒(ProtectSystem=full),这会导致:

  1. 默认无法读取 /etc/shadow,导致 pam_unix 校验本地密码失败。
  2. 整个 /etc 目录以只读(Read-Only)挂载,导致 pam_google_authenticator 在校验成功后因无法写入防重放时间戳临时文件而中断认证(报 Read-only file system 错误)。

1. 创建 Systemd 覆盖规则

sudo mkdir -p /etc/systemd/system/freeradius.service.d

sudo tee /etc/systemd/system/freeradius.service.d/override.conf > /dev/null << 'EOF'
[Service]
# 1. 显式追加 shadow 组权限,允许 pam_unix 读取本地系统密码散列
SupplementaryGroups=shadow

# 2. 对 OTP 目录放行写权限,允许 google-authenticator 更新防重放记录
ReadWritePaths=/etc/freeradius/3.0/otp
EOF

2. 初始化集中存放令牌目录

# 创建集中存放目录并赋予 freerad 组权限
sudo mkdir -p /etc/freeradius/3.0/otp
sudo chown -R freerad:freerad /etc/freeradius/3.0/otp
sudo chmod 700 /etc/freeradius/3.0/otp

# 将 freerad 用户加入 shadow 组
sudo usermod -aG shadow freerad

四、 FreeRADIUS 与 PAM 配置

1. 配置 PAM 认证链

修改 FreeRADIUS 专用的 PAM 认证文件,利用 forward_pass 实现自动剥离后 6 位动态口令:

sudo cp /etc/pam.d/radiusd /etc/pam.d/radiusd.bak

sudo tee /etc/pam.d/radiusd > /dev/null << 'EOF'
# 1. 以 freerad 运行身份读取集中目录下的令牌,剥离后 6 位验证 TOTP,其余部分向下传递
auth requisite pam_google_authenticator.so forward_pass user=freerad secret=/etc/freeradius/3.0/otp/${USER}

# 2. 接收前半段密码,向系统核验账户密码
auth required pam_unix.so use_first_pass

account required pam_unix.so
session required pam_unix.so
EOF

2. 启用 FreeRADIUS PAM 模块

# 启用 PAM 模块
sudo ln -sf /etc/freeradius/3.0/mods-available/pam /etc/freeradius/3.0/mods-enabled/pam

# 强制默认认证走 PAM
sudo sed -i '1i DEFAULT Auth-Type := PAM\n' /etc/freeradius/3.0/mods-config/files/authorize

# 确保 default 站点的 authenticate 节点已开启 pam
sudo sed -i 's/^[ \t]*#[ \t]*pam$/\tpam/' /etc/freeradius/3.0/sites-enabled/default

3. 配置 RADIUS 客户端白名单(Clients)

编辑 /etc/freeradius/3.0/clients.conf,在文件末尾定义 SSL-VPN 网关接入规则:

sudo tee -a /etc/freeradius/3.0/clients.conf > /dev/null << 'EOF'

# 本地调试与排错使用 (radtest)
# 默认 client localhost 使用 secret = testing123,若需更改可在对应区块配置

# 企业 SSL-VPN 网关接入配置
client ssl-vpn-gateway {
    ipaddr = 10.255.20.0/24         # 替换为实际 VPN 网关内网出口 IP (或子网段)
    secret = VpnRadiusSecret2026  # 替换为自定义高强度共享密钥
    require_message_authenticator = no
}
EOF

4. 语法检测与启动服务

# 检测配置文件语法
sudo freeradius -XC

# 重载 Systemd 并重启服务
sudo systemctl daemon-reload
sudo systemctl restart freeradius
sudo systemctl enable freeradius

验证指标:执行 sudo systemctl status freeradius,状态为 active (running),且显示已加载 override.conf。


五、 账号自动化生命周期管理脚本

1. 一键创建/开通 VPN 用户 (add-vpn-user.sh)

自动创建本地锁定用户、静默生成 Google Authenticator 密钥、移至统一目录并直接在终端打印绑定二维码。

sudo tee /usr/local/bin/add-vpn-user.sh > /dev/null << 'EOF'
#!/usr/bin/env bash
set -e

if [ "$#" -ne 2 ]; then
    echo "用法: sudo $0 <用户名> <静态密码>"
    exit 1
fi

USERNAME="$1"
PASSWORD="$2"
OTP_DIR="/etc/freeradius/3.0/otp"

# 1. 创建仅认证用途的系统本地账号
if id "$USERNAME" &>/dev/null; then
    echo "[-] 用户 $USERNAME 已存在,直接更新密码与令牌..."
else
    useradd -m -s /usr/sbin/nologin "$USERNAME"
    echo "[+] 用户 $USERNAME 创建成功"
fi
echo "$USERNAME:$PASSWORD" | chpasswd

# 2. 静默生成 Google TOTP 密钥
mkdir -p "$OTP_DIR"
sudo -u "$USERNAME" google-authenticator -t -d -f -r 3 -R 30 -w 3 -C
mv "/home/$USERNAME/.google_authenticator" "$OTP_DIR/$USERNAME"
chown freerad:freerad "$OTP_DIR/$USERNAME"
chmod 600 "$OTP_DIR/$USERNAME"

# 3. 提取密钥并在终端渲染二维码
SECRET=$(head -n 1 "$OTP_DIR/$USERNAME")
echo ""
echo "=================================================="
echo " VPN 账号开通成功"
echo " 用户名: $USERNAME"
echo " 静态密码: $PASSWORD"
echo " 令牌密钥: $SECRET"
echo " 登录方式: 密码框输入 [静态密码 + 手机App当前6位动态码]"
echo "=================================================="
echo "请指导员工使用 Google Authenticator / 微软验证器 扫码绑定:"
echo ""
qrencode -t ANSIUTF8 "otpauth://totp/SSL-VPN:${USERNAME}?secret=${SECRET}&issuer=SSL-VPN"
echo "=================================================="
EOF

sudo chmod +x /usr/local/bin/add-vpn-user.sh

使用示例:

sudo add-vpn-user.sh zhangsan StrongPass2026!

2. 一键回收/注销 VPN 用户 (del-vpn-user.sh)

用于离职员工账号清理,物理删除其系统账户、家目录及 OTP 密钥文件。

sudo tee /usr/local/bin/del-vpn-user.sh > /dev/null << 'EOF'
#!/usr/bin/env bash
set -e

if [ "$#" -ne 1 ]; then
    echo "用法: sudo $0 <用户名>"
    exit 1
fi

USERNAME="$1"
OTP_FILE="/etc/freeradius/3.0/otp/${USERNAME}"

# 系统关键账号保护名单
PROTECTED=("root" "freerad" "daemon" "bin" "sys" "sync" "sshd" "ubuntu")
for p in "${PROTECTED[@]}"; do
    if [ "$USERNAME" == "$p" ]; then
        echo "[!] 禁止删除系统保留账号: $USERNAME"
        exit 1
    fi
done

echo "[-] 正在清理用户 $USERNAME ..."

# 1. 删除 OTP 密钥
if [ -f "$OTP_FILE" ]; then
    rm -f "$OTP_FILE"
    echo "[+] 已移除 OTP 令牌文件"
fi

# 2. 终止残留会话并删除系统账号与家目录
if id "$USERNAME" &>/dev/null; then
    pkill -u "$USERNAME" 2>/dev/null || true
    userdel -r "$USERNAME" 2>/dev/null || userdel "$USERNAME"
    echo "[+] 已删除系统用户及家目录"
fi

echo "[√] 用户 $USERNAME 权限已彻底注销。"
EOF

sudo chmod +x /usr/local/bin/del-vpn-user.sh

六、 SSL-VPN 网关对接配置标准

在 SSL-VPN 网关的“RADIUS 认证配置”页面中,必须严格对照以下参数落地:

配置项推荐值关键说明
服务器地址10.255.20.162FreeRADIUS 部署主机的内网 IP
端口1812默认 RADIUS 认证端口(UDP)
认证协议PAP严禁选 CHAP。PAP 能传递明文字符串给 PAM 解析,CHAP 会哈希混淆导致无法剥离动态码
认证共享密钥VpnRadiusSecret2026必须与 /etc/freeradius/3.0/clients.conf 中填写的 secret 严格一致
认证超时10 - 15 秒动态口令计算和 PAM 链处理较普通认证稍长,留出充裕的响应窗口
状态启用(开启)保存前确认开关置于开启状态

网关连通性测试注意:

  • 在网关控制台点击“测试”时,必须明确输入用户名(如 ceshi)与拼接密码(如 静态密码+当前动态码)。
  • 若用户名留空,网关发出的探测包将不包含 User-Name 属性,会导致 FreeRADIUS 直接报 Attribute "User-Name" is required 并 Reject。

七、 生产故障复盘与排错指南

在部署与联调过程中遇到底层拒绝时,按以下定位树快速排查:

1. 核心问题复盘

错误现象抓包/日志关键信息根因分析最终解决方案
本地 radtest 超时无响应(0) No reply from server1. 目标写了 127.0.0.1 但密钥错填为了网关专用的密钥;


2. 防火墙拦截了 UDP 1812。 | 本地测试 127.0.0.1 统一使用默认密钥 testing123;或为 localhost 设置统一 secret。 |
| 用户 ID 切换失败 | Failed to change user id to "xxx" | FreeRADIUS 以 freerad 运行时,因缺少权限无法 setuid 切换到目标账号读取其家目录下的 .google_authenticator。 | 放弃分散存储,将令牌统一挪入 /etc/freeradius/3.0/otp/,PAM 参数显式指定 user=freerad。 |
| 只读文件系统报错 | Failed to create tempfile ... Read-only file system | Systemd 的 ProtectSystem=full 将 /etc 视为只读,阻止了动态码防重放时间戳的回写。 | 在 override.conf 中配置 ReadWritePaths=/etc/freeradius/3.0/otp 放行写权限。 |
| 静态密码校验失败 | pam_unix(radiusd:auth): authentication failure | Systemd 启动进程缺少 shadow 附加组,导致 pam_unix 无权读取 /etc/shadow。 | 在 override.conf 中配置 SupplementaryGroups=shadow。 |
| 动态码连续测试失败 | 第一次 Accept,紧接着测第二次变成 Reject | google-authenticator 启用了 -d(防重放),同一个 6 位动态码在 30 秒周期内已被标记消费。 | 正常安全机制,等待手机 App 刷新出下一个 6 位动态码后再测试即可。 |

2. 常用排错命令集合

# 查看实时 PAM 安全审计日志(最直接定位账号/密码/OTP错误)
sudo tail -f /var/log/auth.log

# 开启 FreeRADIUS 前台深度调试模式(排查 RADIUS 报文属性)
sudo systemctl stop freeradius
sudo freeradius -X

# 测试本地认证回路
radtest <用户名> <静态密码+最新6位动态码> 127.0.0.1 0 testing123