Authelia 与 Kasm Workspaces 集成指南：通过 OpenID Connect 1.0 实现 Web 桌面环境的单点登录-二趣网

Authelia 与 Kasm Workspaces 集成指南：通过 OpenID Connect 1.0 实现 Web 桌面环境的单点登录

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia

本文以 Authelia 的 OpenID Connect 1.0 Provider 为身份源，讲解如何将其与 Kasm Workspaces（基于浏览器的容器化桌面工作区平台）对接，实现统一的单点登录（SSO）与自动用户开通。读完本文，你将掌握在 Authelia 侧注册 OIDC 客户端、在 Kasm Workspaces Web GUI 侧填写授权端点与令牌端点等核心参数，以及围绕 PKCE、客户端密钥哈希等安全要点的完整实操方案。该集成对应的官方指南位于 docs/content/integration/openid-connect/clients/kasm-workspaces/index.md。

测试版本与集成前提

官方指南对以下版本组合完成了验证：

Authelia：v4.38.0
Kasm Workspaces：v1.13.0

示例环境使用如下假设值（生产环境中请全部替换为你的实际域名与凭据）：

应用根 URL：https://kasm.example.com/
Authelia 根 URL：https://auth.example.com/
Client ID：kasm
Client Secret：insecure_secret

其中example.com是占位域名，insecure_secret仅用于演示，严禁在生产环境直接使用。如果你在阅读官方在线文档时开启了站点变量替换功能，上述 URL 中的域名部分会被自动替换为文档站点变量。

Authelia 端：注册 Kasm Workspaces 客户端

完整客户端配置示例

以下 YAML 是用于对接 Kasm Workspaces 的 Authelia OpenID Connect 1.0 客户端注册配置，将其合并到configuration.yml的identity_providers.oidc段即可：

identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. ## See: https://www.authelia.com/c/oidc clients: - client_id: 'kasm' client_name: 'Kasm Workspaces' client_secret: '$pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng' # The digest of 'insecure_secret'. public: false authorization_policy: 'two_factor' require_pkce: false pkce_challenge_method: '' redirect_uris: - 'https://kasm.example.com/api/oidc_callback' scopes: - 'openid' - 'profile' - 'groups' - 'email' response_types: - 'code' grant_types: - 'authorization_code' access_token_signed_response_alg: 'none' userinfo_signed_response_alg: 'none' token_endpoint_auth_method: 'client_secret_basic'

注意：该配置片段只包含客户端注册部分。你必须同时完成 OpenID Connect 1.0 Provider 的其余必需配置（如 issuer、密钥等），完整的 Provider 级配置选项参见 docs/content/configuration/identity-providers/openid-connect/provider.md。

关键参数逐项解析

结合客户端配置文档 docs/content/configuration/identity-providers/openid-connect/clients.md 中的定义，本示例涉及的参数含义如下：

参数	取值	说明
`client_id`	`kasm`	客户端唯一标识，对应 Kasm 侧填写的 Client ID。该值必须在所有客户端中唯一，且只能包含 RFC 3986 定义的 Unreserved Characters，长度不超过 100 字符
`client_name`	`Kasm Workspaces`	客户端显示名称，便于在 Authelia 的授权与同意页面中识别
`client_secret`	PBKDF2 摘要	Kasm 是机密型（confidential）客户端，需要共享密钥。示例中的`$pbkdf2-sha512$...`是明文`insecure_secret`的哈希摘要，推荐使用哈希形式存储，明文存储已被弃用
`public`	`false`	保持默认的机密型客户端类型。若设为`true`（公开客户端），则`client_secret`必须为空字符串
`authorization_policy`	`two_factor`	该客户端的授权策略，可选`one_factor`、`two_factor`或 Provider 级`authorization_policies`中自定义的策略。此策略仅作用于授权请求，与访问控制规则（Access Control Rules）是两套独立的机制
`require_pkce`	`false`	是否强制该客户端使用 PKCE（RFC 7636）。也可通过 Provider 级`enforce_pkce`全局强制
`pkce_challenge_method`	`''`	强制使用的 PKCE challenge 方法，合法值为空字符串、`plain`或`S256`。设置非空值会同时等效启用`require_pkce`；`S256`是强烈推荐的方案（仅当依赖方支持时）
`redirect_uris`	`https://kasm.example.com/api/oidc_callback`	Kasm 的 OIDC 回调地址，必填。URIs 大小写敏感，scheme 必须是`http`或`https`，未列入此列表的回调将被视为不安全并拒绝
`scopes`	`openid profile groups email`	允许该客户端申请的 scope 列表。默认值为`openid,groups,profile,email`，对应 OpenID Connect 1.0 的 scope 定义（详见 docs/content/integration/openid-connect/openid-connect-1.0-claims.md）
`response_types`	`code`	仅使用授权码流（Authorization Code Flow）。官方文档安全提示：只推荐使用`code`响应类型，其余类型安全性较差
`grant_types`	`authorization_code`	允许的授权类型，默认即`authorization_code`，除非明确了解后果否则不建议修改
`access_token_signed_response_alg`	`none`	访问令牌的签名算法。Kasm 侧不消费 JWT 形式的访问令牌，因此设为`none`（即不签名、返回不透明令牌）
`userinfo_signed_response_alg`	`none`	UserInfo 端点的响应签名算法。设为`none`时 UserInfo 端点返回`application/json`格式的普通 JSON（参见 docs/content/integration/openid-connect/introduction.md 的 User Information Signing Algorithm 一节）
`token_endpoint_auth_method`	`client_secret_basic`	客户端在令牌端点的认证方式，即通过 HTTP Basic Auth 在请求头中携带 Client ID 与 Client Secret（RFC 6749 定义的方式）

Kasm Workspaces 端：通过 Web GUI 配置 OpenID Connect

Kasm Workspaces 提供一种配置方式：Web GUI。进入管理界面后按以下路径操作：

进入Authentication（认证）菜单；
打开OpenID子菜单；
按下表配置各选项（对应 Kasm 的 "Create OpenID Config" 表单）：

Kasm 表单字段	填写值	说明
Automatic User Provision	按需启用	启用后，首次通过 Authelia 登录的用户会在 Kasm Workspaces 中自动创建
Auto Login	按需启用	启用自动登录，用户访问 Kasm 时免去手动点击登录的步骤
Default	按需启用	将 Authelia 设为 Kasm 的默认登录方式
Client ID	`kasm`	与 Authelia 侧`client_id`保持一致
Client Secret	`insecure_secret`	与 Authelia 侧`client_secret`的明文值保持一致（生产环境请替换）
Authorization URL	`https://auth.example.com/api/oidc/authorization`	Authelia 的授权端点
Token URL	`https://auth.example.com/api/oidc/token`	Authelia 的令牌端点
User Info URL	`https://auth.example.com/api/oidc/userinfo`	Authelia 的 UserInfo 端点
Scope (One Per Line)	`openid`、`profile`、`groups`、`email`（每行一个）	与 Authelia 侧`scopes`列表对应
User Identifier	`preferred_username`	使用 Authelia UserInfo 返回的`preferred_username`声明作为 Kasm 的用户名

图中展示的是 Kasm Workspaces 的 "Create OpenID Config" 表单（官方指南原图）：必填字段包括 Display Name、Client ID、Authorization URL、Token URL、User Info URL、Scope 与 Username Attribute，可选字段包括 Logo URL、Enabled、Auto Login、Default、Hostname 与 Groups Attribute。请确保表单中的auth.example.com三个端点 URL 与 Authelia 实际部署地址一致。

需要说明的是，Authelia 的 OpenID Connect 1.0 端点路径是有固定约定的：授权端点为/api/oidc/authorization、令牌端点为/api/oidc/token、UserInfo 端点为/api/oidc/userinfo。除手工填写外，依赖方也可以通过/.well-known/openid-configuration发现这些端点（详见 docs/content/integration/openid-connect/introduction.md 的 Endpoint Implementations 一节），Kasm 的 OIDC 回调则指向https://kasm.example.com/api/oidc_callback。

集成要点与安全建议

官方文档在oidc-common公共短代码（docs/layouts/_shortcodes/oidc-common.html）中，对所有 OIDC 集成指南统一注入了以下必须在配置前了解的重要事项，Kasm 集成同样适用：

client_id必须唯一：本文使用kasm仅为演示可读性，生产环境应使用随机生成的值。官方推荐 64 个随机字符，且只允许 RFC 3986 Unreserved Characters，长度不超过 100 字符。
client_secret严禁复用演示值：insecure_secret只用于示例。生产环境应使用随机密码生成器生成，并优先以哈希形式（如示例中的$pbkdf2-sha512$...摘要）存储在 Authelia 配置中——明文存储虽仍可用但已弃用。若使用哈希存储，需注意过高的哈希工作因子可能导致客户端请求超时，可参考 docs/content/integration/openid-connect/frequently-asked-questions.md 中关于 work factors 调优的说明。
Provider 级配置不可省略：上文 YAML 仅包含客户端注册片段，你仍须完成 Provider 的必需配置项。

其他值得注意的安全要点：

授权策略：authorization_policy: 'two_factor'意味着用户通过 Kasm 登录时必须完成 Authelia 侧的两步验证。如你的安全基线允许，可改为one_factor，但两步验证能显著降低凭据泄露风险。
PKCE：本示例中require_pkce保持默认false、pkce_challenge_method为空，是因为 Kasm Workspaces 为机密型 Web 应用且使用client_secret_basic认证。若你的部署环境或后续 Kasm 版本支持 PKCE，强烈建议启用S256方法以抵御授权码拦截攻击。
回调地址匹配：Kasm 的回调 URL 必须与redirect_uris完全一致（大小写敏感），否则授权请求会被 Authelia 拒绝并报错。

验证集成是否成功

完成两侧配置后，建议按以下步骤验证：

重启 Authelia 使新的客户端注册配置生效，并观察启动日志确认无配置告警；
在未登录状态下访问 Kasm Workspaces 的登录页，确认 Authelia 成为可选（或默认）登录方式；
点击登录后，浏览器应跳转到https://auth.example.com，完成单因素或双因素认证；
认证成功后浏览器携带授权码回调至https://kasm.example.com/api/oidc_callback，Kasm 使用client_secret_basic向令牌端点换取令牌并调用 UserInfo 端点获取preferred_username；
若启用了 Automatic User Provision，首次登录的用户应自动出现在 Kasm 的用户列表中，且用户名取自preferred_username。

若登录失败，优先核对三处：Kasm 表单中的三个端点 URL 是否与 Authelia 实际地址一致、redirect_uris与回调地址是否完全匹配、两侧的 Client ID / Client Secret 是否一致。整个流程中 Authelia 的日志会记录授权与令牌交换的详细错误信息，是排障的首要依据。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析