OpenVPN + Keycloak：OAuth2 设置

使用 openvpn-auth-oauth2 插件将 OpenVPN 与 Keycloak 集成

此前，Yandex Cloud 上受保护环境的资源访问依赖于自建 OpenVPN 服务，并采用 PAM 认证方式。随着用户数量增长，集成 Keycloak 成为必然选择。openvpn-auth-oauth2 插件支持通过 Keycloak 实现 OAuth2 认证，兼容基于 Debian 和 RedHat 的系统。

在 Ubuntu 24.04 LTS 上，可直接从项目仓库安装：

curl -L https://raw.githubusercontent.com/jkroepke/openvpn-auth-oauth2/refs/heads/main/packaging/apt/openvpn-auth-oauth2.sources | sudo tee /etc/apt/sources.list.d/openvpn-auth-oauth2.sources
sudo apt update
sudo apt install openvpn-auth-oauth2

在 Keycloak 中创建客户端

在 Keycloak 中为插件创建新客户端：

• 设置客户端 ID：openvpn-auth-oauth2。
• 启用客户端认证：开启。
• 启用标准流程：开启。
• 设置访问类型：保密。

复制客户端密钥——配置时需用到。

配置 openvpn-auth-oauth2 插件

主配置文件：/etc/openvpn-auth-oauth2/config.yaml。最小可用配置如下：

http:
  baseurl: "https://vpn.yourdomain.com"
  listen: ":9000"
  secret: "your_secret_password"
oauth2:
  issuer: "https://keycloak.yourdomain/realms/securerealm"
  client:
    id: "openvpn-auth-oauth2"
    secret: "your_secret_from_keycloak_client"
openvpn:
  addr: "unix:///run/openvpn/server.sock"
  password: "your_secret_password"

参数说明：

• baseurl：OAuth2 接口域名，通过 nginx 反向代理至端口 9000。
• listen：服务监听端口。
• secret：Cookie 加密密钥（16/24/32 字符）。
• issuer：包含领域信息的 Keycloak 地址。
• client.id/secret：Keycloak 客户端凭证。
• openvpn.addr/password：OpenVPN 套接字路径与密码。

配置 OpenVPN 服务器

创建 /etc/openvpn/server/server-keycloak.conf 文件：

port 56890
management /run/openvpn/server.sock unix /etc/openvpn/password.txt
management-client-auth
auth-user-pass-optionals
auth-gen-token 28800 external-auth
proto udp
dev tun
ca /etc/openvpn/certs/ca.crt
cert /etc/openvpn/certs/server.crt
key /etc/openvpn/certs/server.key
dh /etc/openvpn/certs/dh.pem
server 10.212.245.0 255.255.255.0
client-config-dir /etc/openvpn/ccd
ifconfig-pool-persist /etc/openvpn/ipp.txt
push "route 10.167.0.0 255.255.0.0"
push "route 10.168.0.0 255.255.0.0"
push "route 10.169.0.0 255.255.0.0"
keepalive 10 120
cipher AES-256-GCM
max-clients 100
persist-tun
status /var/log/openvpn/openvpn-keycloak-status.log
verb 3

关键集成选项：

• management ...：外部控制使用的 Unix 套接字。
• management-client-auth：允许外部命令执行。
• auth-user-pass-optionals：客户端无需提供用户名和密码。
• auth-gen-token 28800 external-auth：由插件生成令牌，有效期 8 小时（28800 秒）。

启动服务：

systemctl enable openvpn-server@server-keycloak --now

通过 nginx 进行反向代理

安装 nginx 与 certbot 以支持 HTTPS。配置文件位于 /etc/nginx/conf.d/vpn.yourdomain.com.conf：

server {
    server_name vpn.yourdomain.com;
    listen 80;
    listen [::]:80;
    access_log /var/log/nginx/vpn.yourdomain.com-access.log;
    error_log /var/log/nginx/vpn.yourdomain.com-error.log;

    location ^~ /.well-known/acme-challenge/ {
        default_type "text/plain";
        root /var/www/certbot;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    server_name vpn.yourdomain.com;
    listen 443 ssl;
    error_log /var/log/nginx/vpn.yourdomain.com-error.log;

    ssl_certificate /etc/letsencrypt/live/vpn.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vpn.yourdomain.com/privkey.pem;

    location ^~ /.well-known/acme-challenge/ {
        default_type "text/plain";
        root /var/www/certbot;
    }

    location / {
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://localhost:9000;
    }
}

重新加载 nginx：systemctl reload nginx。

客户端配置与测试

客户端 .ovpn 文件内容：

client
dev tun
proto udp
remote vpn.yourdomain.com 56890
nobind
persist-key
persist-tun
verb 3
<ca>
-----BEGIN CERTIFICATE-----
Here your CA certificate
-----END CERTIFICATE-----
</ca>
cipher AES-256-GCM

导入 OpenVPN 客户端（如 OpenVPN Access Server）。连接时，浏览器将自动跳转至 Keycloak 登录页面。认证成功后：

• 浏览器显示确认信息。
• VPN 连接建立成功。

仅支持命令行的客户端不支持浏览器认证流程，需额外定制。

核心要点

• openvpn-auth-oauth2 插件以 Keycloak 的 OAuth2 替代 PAM，实现可扩展的认证机制。
• 使用 Unix 套接字保障 OpenVPN 管理安全。
• 令牌有效期：28800 秒（8 小时），可通过 auth-gen-token 调整。
• 必须通过 nginx 反向代理实现 HTTPS 与 Let’s Encrypt 自动证书管理。
• 适合中高级 DevOps 工程师进行配置与系统集成。

— Editorial Team