Authelia 集成 Apache Guacamole：OpenID Connect 1.0 单点登录实战指南

Authelia 集成 Apache GuacamoleOpenID Connect 1.0 单点登录实战指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaApache Guacamole 是一款无客户端的远程桌面网关通过浏览器即可访问 RDP、SSH 与 VNC 会话。本文以仓库中的集成文档 docs/content/integration/openid-connect/clients/apache-guacamole/index.md 为骨架完整讲解如何将 Authelia 作为 OpenID Connect 1.0 Provider为 Apache Guacamole 提供 SSO 与多因素认证。读完本文你将掌握在 Authelia 中注册 Guacamole 客户端、在 Guacamole 侧配置 OpenID 扩展的全部步骤并理解隐式流Implicit Flow、ID Token 签名与 claim 映射等底层机制。测试版本与环境假设该集成指南对应的测试版本如下组件版本Autheliav4.39.24Apache Guacamolev1.5.5示例配置基于以下假设实际部署时请替换为你的真实域名应用根地址Guacamolehttps://guacamole.example.com/Authelia 根地址https://auth.example.com/Client IDguacamole文档中example.com、auth等值可替换为部署环境的实际值官方文档通过 sitevar 变量自动替换。配置前的必读要点在动手配置之前有几项 OpenID Connect 1.0 注册客户端的通用约束需要先了解对应仓库中oidc-common短代码模板 docs/layouts/_shortcodes/oidc-common.html 的内容client_id必须全局唯一且只能包含 RFC3986 Unreserved Characters即字母、数字及-、.、_、~长度不得超过 100 个字符。指南中的guacamole仅为演示用途生产环境建议生成 64 位随机字符串。client_secret不要直接使用演示值。虽然 Authelia 允许在配置中以明文存储 secret但该行为已标记为弃用官方强烈建议使用 PBKDF2 等哈希形式存储参见 docs/content/integration/openid-connect/frequently-asked-questions.md。同时要注意哈希开销过大可能导致客户端认证超时需适当调整工作因子。示例配置只包含客户端注册部分identity_providers.oidc下的 Provider 级必填配置如 issuer、签名密钥等仍需按 OpenID Connect 1.0 Provider 配置指南 另行补齐。客户端还有大量可选配置项未在示例中出现完整字段说明见 OpenID Connect 1.0 Clients 配置文档。第一步在 Authelia 中注册 Guacamole 客户端在 Authelia 的configuration.yml中identity_providers.oidc.clients列表下新增如下客户端注册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: guacamole client_name: Apache Guacamole public: true authorization_policy: two_factor require_pkce: false pkce_challenge_method: redirect_uris: - https://guacamole.example.com scopes: - openid - profile - groups - email response_types: - id_token grant_types: - implicit access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_basic各配置项的作用与依据这些字段在源码中的定义位于 internal/configuration/schema/identity_providers.go 的IdentityProvidersOpenIDConnectClient结构体要点如下public: true将客户端标记为公开客户端Public Client Type。Guacamole 的 OpenID 扩展在浏览器端完成认证无法安全保管 client secret因此采用公开客户端模式。对应结构体字段Public bool默认false。authorization_policy: two_factor访问该客户端需要两步认证。这也是客户端的默认策略——从源码 identity_providers.go 的DefaultOpenIDConnectClientConfiguration可见AuthorizationPolicy默认为two_factorScopes默认为openid、groups、profile、email。require_pkce: false与pkce_challenge_method: 由于 Guacamole 使用隐式流而非授权码流PKCE 不适用故显式关闭。字段RequirePKCE默认falsePKCEChallengeMethod合法值为、plain、S256。redirect_uris授权完成后浏览器重定向回 Guacamole 的地址白名单。此处必须与 Guacamole 侧openid-redirect-uri完全一致。scopes本次授权请求的声明范围包括openid、profile、groups、email。groups是 Authelia 提供的自定义 scope用于把用户所属组下发给客户端Guacamole 借此实现基于组的访问控制。response_types: [id_token]隐式流中仅返回 ID Token。配合grant_types: [implicit]二者共同锁定隐式流 ID Token only的交互模式。对照 OpenID Connect 1.0 集成介绍 中的响应类型表id_token对应的默认响应模式为form_post与fragment。access_token_signed_response_alg: none与userinfo_signed_response_alg: none不要求对 Access Token 与 UserInfo 响应做 JWS 签名。源码中AccessTokenSignedResponseAlg、UserinfoSignedResponseAlg的默认值即为none可选值包括none、HS256/384/512、RS256/384/512、ES256/384/512、PS256/384/512、Ed25519等。token_endpoint_auth_method: client_secret_basic声明客户端在令牌端点使用 HTTP Basic 携带 secret 认证该值也是源码中TokenEndpointAuthMethod的默认值。由于此客户端为public类型实际隐式流中不涉及令牌端点认证。第二步在 Apache Guacamole 侧启用并配置 OpenID 扩展安装 OpenID Connect 扩展在配置 Guacamole 之前必须先安装其 openid 扩展安装包通常为guacamole-auth-openid部署到 Guacamole 扩展目录并重启服务。没有该扩展Guacamole 不会提供任何 OpenID 配置项。修改 Guacamole 配置文件Guacamole 的配置通过配置文件完成即guacamole.properties位于 GUACAMOLE_HOME 下。将 Authelia 作为 OpenID Connect 1.0 Provider 的配置如下openid-client-id: guacamole openid-scope: openid profile groups email openid-issuer: https://auth.example.com openid-jwks-endpoint: https://auth.example.com/jwks.json openid-authorization-endpoint: https://auth.example.com/api/oidc/authorization?state1234abcedfdhf openid-redirect-uri: https://guacamole.example.com openid-username-claim-type: preferred_username openid-groups-claim-type: groups各项含义如下openid-client-id与 Authelia 注册的client_id保持一致值为guacamole。openid-scope请求的 scope 列表空格分隔须与 Authelia 客户端配置中授权的 scopes 对齐openid profile groups email。openid-issuerOpenID Connect 签发者Issuer即 Authelia 的根地址。Authelia 的issuer与 OIDC 发现端点绑定客户端可据此获取元数据。openid-jwks-endpointAuthelia 的 JSON Web Key Set 端点。用于验证 Authelia 签发的 ID Token 签名。该路径在 OpenID Connect 1.0 集成介绍 的端点表中被列为jwks_uri即https://auth.example.com/jwks.json。openid-authorization-endpointAuthelia 的授权端点。注意示例 URL 中的?state1234abcedfdhf只是 Guacamole 初始化 state 参数的方式实际授权流程中 state 由 Guacamole 动态生成用以防止 CSRF。openid-redirect-uri认证完成后浏览器重定向回 Guacamole 的地址必须与 Authelia 客户端redirect_uris中的条目完全一致https://guacamole.example.com。openid-username-claim-typepreferred_username。指定从 ID Token 的哪个 claim 提取用户名用于映射 Guacamole 本地用户。openid-groups-claim-typegroups。指定从 ID Token 的哪个 claim 提取用户组Guacamole 据此将用户映射到已配置的 Guacamole 用户组并继承相应权限。认证流程与底层端点完成上述两步配置后用户访问 Guacamole 时的认证流程如下用户未登录时访问https://guacamole.example.com/Guacamole 将浏览器重定向到 Authelia 授权端点/api/oidc/authorization携带response_typeid_token、client_idguacamole、scopeopenid profile groups email、state与redirect_uri等参数。Authelia 按客户端authorization_policy本例为two_factor要求用户完成认证密码 第二因素或已存在会话则直接通过。认证通过后Authelia 以隐式流将签名的 ID Token 通过 fragment 或 form_post 返回给 Guacamole 的重定向地址。Guacamole 通过openid-jwks-endpoint获取 Authelia 的公钥校验 ID Token 签名后按openid-username-claim-type与openid-groups-claim-type提取preferred_username与groupsclaim映射到本地用户与用户组完成登录。上述端点路径均有据可查授权端点为https://auth.example.com/api/oidc/authorizationJWKS 端点为/jwks.json此外 Authelia 还实现了/api/oidc/token、/api/oidc/userinfo、/api/oidc/introspection、/api/oidc/revocation以及发现端点/.well-known/openid-configuration详见 OpenID Connect 1.0 集成介绍 的 Endpoint Implementations 章节。安全与生产环境注意事项授权策略示例使用two_factor即使用户已有密码会话访问 Guacamole 仍会要求第二因素适合将 Guacamole 作为高价值资源保护。若你希望单因素即可登录可改为one_factor但需自行评估风险。客户端标识符生产环境请使用随机生成的 64 位字符串作为client_id生成方式参见 Frequently Asked Questions不要沿用guacamole演示值。隐式流的定位隐式流已被 OAuth 2.0 生态逐步弃用但 Guacamole 的 OpenID 扩展至今仍基于该流程。若你关注此问题应关注 Guacamole 上游对授权码流 PKCE 的支持进展Authelia 侧对authorization_code与 PKCES256均有完整支持。声明稳定性的说明Authelia 的 ID Token 中sub与iss是稳定且不变的标识。Guacamole 这类依赖preferred_username、groups等可读声明做账号映射的客户端要求管理员确保用户名与组名在目录中保持一致避免因声明变化导致账号错配。验证与故障排查要点确认扩展已加载Guacamole 管理界面或日志中出现 OpenID 相关配置项即说明扩展生效若属性被忽略多半是扩展未安装或未重启。检查回调地址一致性openid-redirect-uri与 Authelia 的redirect_uris必须逐字节一致含协议、端口、路径否则 Authelia 会拒绝该重定向。验证 ID Token 校验可通过 Authelia 的jwks.json手工解码 ID Token 验证签名算法是否与客户端response_types/grant_types匹配本例中未要求对 ID Token 使用特定算法默认由 Provider 全局签名密钥处理。观察 Authelia 日志授权失败时Authelia 日志会明确指出缺少的 scope、非法的 redirect_uri 或未匹配的授权策略是定位问题的最快途径。延伸阅读OpenID Connect 1.0 集成介绍协议支持范围、端点实现、签名与加密算法、响应类型与模式等权威说明。OpenID Connect 1.0 Clients 配置文档客户端全部配置项、默认值与 JSON Schema 约束。OpenID Connect 1.0 Provider 配置文档Provider 级必填配置与高级选项。OpenID Connect 常见问题client_id/client_secret生成、secret 哈希存储与工作因子调优。客户端配置结构体源码internal/configuration/schema/identity_providers.go。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考