统一认证实践(13)Authentik 接入 RustGuac 与管理员角色映射
创建于 2026-11-16
更新于 2026-11-18
科技
Debian
docker
authentik
rustguac
oidc
4542 字 · 约 16 分钟

前言

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。官方集成说明

text
1
2
3
4
5
浏览器 → 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:

python
1
2
3
4
5
6
return { "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。下例的用户主键和邮箱必须替换为已经由管理员核验的真实身份:

python
1
2
3
4
5
6
7
8
9
expected_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],保留其他配置:

toml
1
2
3
4
5
6
7
8
9
[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 注入:

dotenv
1
OIDC_CLIENT_SECRET=REPLACE_WITH_CLIENT_SECRET

该环境变量优先于配置文件中的 client_secret。env_file 权限设为 600,不公开输出 docker compose config 的解析内容。1.14.1 配置示例

修改环境变量后,在原 Compose 目录重建 RustGuac 服务:

bash
1
2
docker 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 反代。再次叠加前置认证会增加另一层会话,并不能替代应用内部的用户与角色。

参考

手机扫码阅读
本文作者: 有次元袋的 tiger
本文链接: https://www.superheaoz.top/2026/11/62513/
版权声明: 本站点所有文章除特别声明外,均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来自 我的个人天地!