前言
RustGuac 提供浏览器中的远程桌面、SSH 和文件传输入口。开始试运行时使用 API Key 管理,日常使用则希望接入 DoraTiger Auth,复用现有 MFA,并将访问资格和管理员角色交给专用组管理。
本次基于 RustGuac 1.14.1 和 Authentik 2026.8.5,原服务与 Guacamole 并行运行。本文只处理 RustGuac 的 OIDC 认证,远程主机、连接凭据和 OpenBao 存储仍沿用原部署。
一、身份与远程连接
1.1 原生 OIDC
RustGuac 原生支持 OIDC,浏览器通过 Caddy HTTPS 入口进入应用,RustGuac 与云端 Authentik 交换认证信息,不需要 Proxy Outpost。官方集成说明
text12345浏览器 → Caddy → RustGuac ↔ Authentik ↓ 已授权的连接与凭据存储 ↓ 远程主机
登录 RustGuac 不等于自动获得所有远程主机权限。平台角色、连接目录权限、远端 SSH/RDP 账号分别生效;OIDC 只解决进入平台及识别用户的问题。
1.2 现有部署条件
本次 RustGuac 业务端口仅发布到 Debian 回环,由 Caddy 终止 HTTPS。OpenBao 不发布宿主机端口,负责已有地址簿与凭据。接入前保留 API Key 管理入口,备份 RustGuac 配置、用户数据库和相关凭据存储。
本文假定原平台已经能正常登录和打开连接。OIDC 验证不能替代远程桌面图像质量、长连接和文件传输检查;原试运行中的显示问题仍需要单独处理。
二、Authentik 应用与声明
2.1 管理员访问组
在“目录 → 组”创建 rustguac-admins,不启用 Authentik 超级用户权限,保存后加入准备管理远程连接的用户。
本实例已有对象采用这一名称。新部署多个 RustGuac 时,可以在组、应用和 Provider 名称前加入部署位置,但需要在两端同步使用,不能只改一侧。
2.2 groups 映射
进入“自定义 → 属性映射 → 创建”,类型选择 OAuth2/OpenID Scope Mapping,名称 doratiger-rustguac-groups,Scope name 填 groups:
python123456return { "groups": [ group.name for group in request.user.ak_groups.filter(name="rustguac-admins") ] }
保存后待 Provider 引用。这里仅发送本应用需要的组,不把其他应用的成员信息全部传给 RustGuac。
2.3 邮箱验证声明
RustGuac 会检查邮箱和 email_verified,不能仅看到 email 有值就认为身份匹配完成。本次只允许一个已确认的管理员邮箱,使用专用 email 映射,避免把所有用户的邮箱都标为已验证。
新建 Scope Mapping,名称 doratiger-rustguac-email,Scope name 为 email。下例的用户主键和邮箱必须替换为已经由管理员核验的真实身份:
python123456789expected_user_id = 123 expected_email = "admin@example.com" return { "email": request.user.email, "email_verified": ( request.user.pk == expected_user_id and request.user.email == expected_email ), }
123 只是示例。这个表达式没有完成邮件验证,它表达的是此前已经核验的特定身份;未经核验不能照填并声明通过。后续增加成员或改邮箱,需要同步调整可信来源和 RustGuac 账号,而不是把表达式简化成无条件 True。
2.4 Provider 与应用
创建 OAuth2/OpenID Connect Provider:
| 字段 | 配置 |
|---|---|
| Name | doratiger-rustguac |
| Client type | Confidential |
| Grant types | Authorization code |
| Authentication flow | 复用 DoraTiger 登录与 MFA |
| Authorization flow | doratiger-provider-authorization-implicit-consent |
| Invalidation flow | doratiger-provider-invalidation |
| Issuer mode | 每个 Provider 独立发行者 |
| Subject mode | hashed_user_id |
| Signing key | 现有签名证书 |
| Redirect URI | https://remote.example.com/auth/callback,Strict |
Scope mappings 选择标准 openid/profile、上面的专用 email 和 groups。专用 email 替代默认 email,避免同一声明有两个冲突来源。开启 ID Token 声明,保存 Client ID 和 Client Secret。
以 with existing provider 创建应用,名称 RustGuac,Slug rustguac,选择该 Provider,Launch URL 为 https://remote.example.com/。
保存后在应用的策略/组/用户绑定中添加 rustguac-admins,Order 为 0,启用,Negate 关闭。组绑定决定能否获得应用授权,组声明供 RustGuac 分配角色,两个位置分别配置。
三、RustGuac OIDC 配置
3.1 预创建平台用户
保留 API Key 登录,进入 RustGuac Admin 页面,在用户管理中添加目标邮箱,邮箱必须与 Authentik 返回值一致,角色按本次管理员用途选择 admin。
也可使用运行版本提供的 rustguac add-user --email ... --role ... 管理命令,但需确认操作的是同一份配置和用户数据库。不要在宿主机随意运行另一个二进制,创建到不同的数据库中。
本次选择预创建用户,关闭自动建号。远程管理入口不沿用照片库、代码仓库的默认开放策略。
3.2 配置文件
在原 config.toml 中添加或修改 [oidc],保留其他配置:
toml123456789[oidc] issuer_url = "https://auth.example.com/application/o/rustguac/" client_id = "REPLACE_WITH_CLIENT_ID" redirect_uri = "https://remote.example.com/auth/callback" auto_create_users = false default_role = "viewer" groups_claim = "groups" extra_scopes = ["groups"] allow_unverified_email = false
客户端密钥通过现有 Compose 的受限 env_file 注入:
dotenv1OIDC_CLIENT_SECRET=REPLACE_WITH_CLIENT_SECRET
该环境变量优先于配置文件中的 client_secret。env_file 权限设为 600,不公开输出 docker compose config 的解析内容。1.14.1 配置示例
修改环境变量后,在原 Compose 目录重建 RustGuac 服务:
bash12docker compose config --quiet docker compose up -d --force-recreate rustguac
这里只重建应用容器,保留原卷、OpenBao 服务和其他容器。服务名按原 Compose 确认。
3.3 组角色映射
使用原管理入口打开 Admin 页面,在 group-to-role mappings 中创建一条:
| 字段 | 内容 |
|---|---|
| Group | rustguac-admins |
| Role | admin |
保存后,用户登录时由 groups 声明决定角色。默认角色设为 viewer,避免无匹配身份默认获得较高权限;本次同时关闭自动建号,只允许预创建用户。
如果以后增加普通操作人员,应单独创建组、分配角色并核对可访问的连接目录,不直接加入管理员组。角色与访问控制
四、登录验证
4.1 浏览器登录
打开 RustGuac 首页,点击 Sign in with SSO。认证请求进入 DoraTiger 登录与 MFA,完成应用组检查后返回 /auth/callback。
确认平台内邮箱对应原先预创建的用户,管理员功能和原连接目录存在。我用浏览器从 RustGuac 跳转到 Authentik,登录后能回到 RustGuac 管理页。
4.2 拒绝条件
登录失败时分别核对:
- 用户是否在 Authentik 应用访问组中;
- email 是否与 RustGuac 预创建账号一致;
- email_verified 是否来自已核验的可信映射;
- groups 是否包含角色映射使用的完整组名。
本次不是新用户首次登录自动注册模式。仅在 Authentik 建号、入组,不会自动创建平台用户;需要先在 RustGuac 添加该用户并完善邮箱映射。
4.3 平台与会话
API Key 仍作为备用管理方式存在,需要独立保管。Authentik 的组授权不会自动撤销已有 API Key,也不代表已经打开的远程会话立即断开。停用用户应同时处理平台会话、密钥和相关远端账号。
本次未专项验证跨应用单点退出,不能将点击 RustGuac 退出理解为已退出所有应用。
五、维护与回退
备份原 config.toml、受限环境文件、平台用户数据库以及 OpenBao 数据和恢复材料。身份配置回退优先恢复 OIDC 配置、保留 API Key 入口;整库恢复可能覆盖期间新增用户、地址簿和其他应用变更。
应用、Provider 和专用映射只服务本实例。撤销接入时先停止客户端引用,再清理这些对象,不修改其他应用共享的登录和授权流程。
六、配置问题与解答
6.1 邮箱有值却不能登录
Q:是否应该开启 allow_unverified_email?
先检查身份源声明和账号匹配。本次保留 false,通过专用映射表达已核验邮箱。无条件允许未验证邮箱会改变账号信任条件,不能把它当作普通连通性开关。
6.2 与 Gitea 自动注册是否相同
Q:加入访问组后是否立即产生 RustGuac 用户?
不会。本次 auto_create_users=false,必须预创建邮箱一致的用户。默认 viewer 也不会替代用户存在性检查。
6.3 是否需要在 Caddy 增加前哨
Q:Caddy 已用于 code-server 的 Forward Auth,这里是否也要加?
不需要。RustGuac 自己处理 OIDC,Caddy 保持普通 HTTPS 反代。再次叠加前置认证会增加另一层会话,并不能替代应用内部的用户与角色。
参考
支付宝
微信