使用 Authelia OpenID Connect 1.0 为 engomo 配置单点登录（SSO）完整指南

使用 Authelia OpenID Connect 1.0 为 engomo 配置单点登录SSO完整指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本指南面向希望将 engomo 接入 Authelia 作为身份提供方OpenID Connect 1.0 Provider的部署者完整覆盖 Authelia 侧客户端注册的 YAML 配置、engomo 侧 Web GUI 的操作步骤以及 client_id、client_secret、redirect_uris、PKCE 等关键参数的底层语义与安全建议。阅读并实践本文后你将能够独立完成 engomo 与 Authelia 的授权码Authorization Code流程对接并掌握为任意 OpenID Connect 1.0 Relying Party 配置 Authelia 客户端的通用方法。集成背景与适用范围Authelia 可以作为 OpenID Connect 1.0 Provider 为第三方应用提供统一的认证与授权服务并已通过 OpenID Certified™ 认证Basic OP / Implicit OP / Hybrid OP / Form Post OP / Config OP 五个 profile。engomo 是本次集成中的 Relying Party依赖方 / 客户端应用通过标准的 OpenID Connect 1.0 授权码流程消费 Authelia 签发的令牌。本文对应的官方集成文档位于 docs/content/integration/openid-connect/clients/engomo/index.md属于community社区支持级别的集成指南即该指南由社区维护、以最佳努力best effort方式提供。在开始之前建议先通读 OpenID Connect 1.0 集成总览了解 Authelia 实现的响应类型Response Types、响应模式Response Modes、授权类型Grant Types与客户端认证方法Client Authentication Methods等基础概念。已测试版本根据官方集成文档本次集成基于以下版本验证Autheliav4.39.24release tag 为v4.39.24engomo官方文档未标注具体版本号请以你实际部署的版本为准支持级别说明该集成属于 community 级别意味着集成文档与配置样例由社区贡献并非 Authelia 官方认证的商业合作不同版本的 engomo 行为可能存在差异若遇到兼容性问题应从 engomo 侧与 Authelia 侧双向排查Authelia 的核心 OpenID Connect 1.0 实现本身是 OpenID Certified™ 的但具体应用的适配质量取决于该应用对协议的支持程度。集成前置条件与假设官方示例基于以下假设配置前请将example.com、auth等占位值替换为你自己的域名项目假设值说明Application Root URLhttps://engomo.example.com/engomo 应用的访问根地址Authelia Root URLhttps://auth.example.com/Authelia 门户的访问根地址同时作为 OIDC IssuerClient IDengomo在 Authelia 注册的客户端标识Client Secretinsecure_secret客户端密钥仅演示用生产环境必须替换注意官方文档中example.com等值可通过文档站点提供的“Set Documentation Variables”功能自动替换为你的实际域名对应 Hugo shortcodesitevar见 docs/layouts/_shortcodes/sitevar.html。auth是 Authelia 子域名的默认变量名domain是你的主域名变量名。集成前的必读事项所有 Authelia OpenID Connect 客户端集成文档都要求读者在配置前注意以下几点对应 oidc-common shortcode 中的 “Before You Begin” 部分client_id 必须全局唯一同一 Authelia 实例下所有客户端不能重复。本文使用engomo仅为了可读性与演示生产环境应使用随机生成的长字符串建议 64 个随机字符。client_id 字符集限制只能包含 RFC3986 Unreserved Characters即字母、数字以及-、.、_、~且长度不能超过 100 字符否则部分 Relying Party 在编码凭据时会出错。client_secret 不应以明文长期存储明文存储行为已被废弃未来版本可能不再支持强烈推荐使用哈希格式存储详见下文“密钥生成与哈希存储”。示例配置不完整下方 Authelia 配置片段只包含客户端注册部分你还必须配置 OpenID Connect 1.0 Provider 配置 中要求的其他强制元素如 issuer、密钥、存储等。示例配置只是子集它只展示了客户端可用选项的一小部分建议通读 OpenID Connect 1.0 Clients 完整配置指南 了解全部选项及其影响。第一步在 Authelia 中注册 engomo 客户端以下 YAML 是官方文档给出的 Authelia 侧客户端配置示例可直接放入你的configuration.ymlidentity_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: engomo client_name: engomo 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://engomo.example.com/auth - com.engomo.engomo://callback/ scopes: - openid - email - profile response_modes: - form_post response_types: - code grant_types: - authorization_code access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_post配置字段逐项解析下面结合 OpenID Connect 1.0 Clients 参考文档 逐项说明上述配置的含义与默认值client_id必填string客户端唯一标识必须与 engomo 侧配置的 Client ID 完全一致。限制为 ≤100 字符、仅含 RFC3986 Unreserved Characters、全局唯一。client_name可选string客户端显示名称用于 Authelia 门户中向用户展示。client_secret条件必填stringAuthelia 与 engomo 之间的共享密钥两侧必须一致。对于 confidential机密型客户端必须提供除非token_endpoint_auth_method使用非密钥型凭据对于 public公开型客户端则必须留空。示例中的值$pbkdf2-sha512$310000$...是明文insecure_secret的 PBKDF2-SHA512 哈希摘要310000 次迭代而非明文本身。public布尔默认false是否启用 public 客户端类型。false表示 engomo 属于 confidential 客户端有能力保密凭据。若为true则 client_secret 必须为空字符串。engomo 为服务端承载的 Web 应用因此按 confidential 处理。authorization_policystring默认two_factor该客户端的授权策略取值可为one_factor、two_factor或 provider 级 authorization_policies 中自定义的策略名。它与访问控制规则Access Control Rules是两套独立机制切勿混淆参见 FAQ为什么访问控制配置对 OpenID Connect 1.0 不生效。require_pkce布尔默认false是否强制该客户端使用 PKCE。示例为false即不强制。如需对所有客户端强制可使用 provider 级enforce_pkce选项。从安全角度若 engomo 支持 PKCE建议开启见下文安全实践。pkce_challenge_methodstring默认强制使用指定的 PKCE challenge 方法合法值为空字符串、plain、S256。设置此值会同时隐式启用require_pkce。示例为空字符串即不强制S256是强烈推荐值只要 Relying Party 支持。redirect_uris必填list(string)允许该客户端回调的 URI 白名单大小写敏感未列入的回调一律视为不安全。示例包含两个 URIhttps://engomo.example.com/authengomo Web 端的授权回调地址com.engomo.engomo://callback/engomo 原生移动端 App 的自定义 URI scheme 回调由此可推断 engomo 同时提供 Web 与原生客户端形态这与 Authelia 对 OAuth 2.0 for Native AppsRFC8252 的完整支持相对应。scopeslist(string)默认openid,groups,profile,email允许该客户端请求的 scope 列表。示例仅开放openid、email、profile未含groupsscope 定义可参考 Scope 定义文档。若配置了未定义的 scopeAuthelia 会在日志中给出警告除非客户端启用了client_credentials授权。response_modeslist(string)默认值取决于 response_typescode时含form_post与query允许的响应模式。示例仅允许form_post即授权响应通过 HTML 表单 POST 方式回传给回调地址这也是 engomo 所要求的模式。Authelia 完整支持form_post、query、fragment以及 JARM 系列jwt、form_post.jwt、query.jwt、fragment.jwt。response_typeslist(string)默认code允许的响应类型。示例仅允许code即纯授权码流程Authorization Code Flow——这也是官方推荐的最安全响应类型其余类型implicit / hybrid安全性较差。grant_typeslist(string)默认authorization_code允许该客户端使用的授权类型。示例仅authorization_code。注意文档建议除非明确知道自己在做什么否则不要配置此选项refresh_token仅应授予拥有offline_accessscope 的客户端。access_token_signed_response_algstring默认noneAccess Token 的签名算法。none表示 Access Token 保持不透明opaque格式而非 JWT 格式——这是 Authelia 的默认与推荐行为原因详见 FAQ为什么 Access Token 不是 JSON Web Token。若配置为其他值则启用 RFC9068 JWT Profile Access Token。userinfo_signed_response_algstring默认noneUserInfo 端点响应的签名算法。none表示 UserInfo 端点返回普通 JSON 文档application/json而非签名的 JWT。多数客户端仅支持noneengomo 亦然。token_endpoint_auth_methodstring默认client_secret_basic客户端在 Token 端点认证自身的方法。示例使用client_secret_post即把 client_id 与 client_secret 放在 POST 请求体application/x-www-form-urlencoded中提交RFC6749 2.3.1。支持的取值还包括client_secret_basic、client_secret_jwt、private_key_jwt、none。提示上表中各字段的完整说明含默认值、合法性约束与安全提示均可在 OpenID Connect 1.0 Clients 参考文档 中按字段名检索例如 client_secret、redirect_uris、response_modes、token_endpoint_auth_method。别忘了 Provider 级强制配置上述片段中的注释已强调identity_providers.oidc下除了clients还必须包含 Provider 级的基础配置如issuer、jwks密钥、access_token_lifespan等。完整可参考仓库根目录的 config.template.yml 模板以及 OpenID Connect 1.0 Provider 配置指南。若 Provider 配置缺失或不完整Authelia 启动时会报错或 OIDC 端点不可用。第二步在 engomo 应用中完成配置根据官方集成文档engomo 侧的配置只有一种方式通过其 **Web GUI图形界面**完成。engomo 没有提供基于文件的配置入口。操作步骤如下以管理员身份登录你的 engomo composer设计器/管理端。选择Server服务器。选择Authentication认证。点击以新增一种认证方法。将Name名称设置为Authelia。在Type类型中选择OpenID Connect。点击Create创建。填写以下三个关键字段字段值Issuer签发方https://auth.example.comClient IDengomoClient Secretinsecure_secretIssuer 必须与 Authelia 的根 URL 完全一致不含末尾/即 Authelia 门户地址本身。engomo 会通过向https://auth.example.com/.well-known/openid-configuration发起 OpenID Connect Discovery 1.0 请求自动发现授权端点、Token 端点、UserInfo 端点、JWKS 等元数据。Authelia 同时提供 OAuth 2.0 Authorization Server Metadata 端点/.well-known/oauth-authorization-server完整端点清单见 集成总览的 Endpoint Implementations 章节。点击Save保存完成配置。保存后engomo 即可引导用户跳转到https://auth.example.com完成认证示例配置下为 two_factor 双因素认证Authelia 将按form_post模式将授权码回传到https://engomo.example.com/auth随后 engomo 以client_secret_post方式在 Token 端点换取令牌。密钥生成与哈希存储生产环境必读示例中的insecure_secret仅用于演示绝对不要在生产环境使用。Authelia 官方推荐按以下方式生成与存储凭据详见 FAQ如何生成 client identifier 或 client secret生成 client_id72 字符的 RFC3986 随机字符串# Docker 方式 docker run --rm authelia/authelia:latest authelia crypto rand --length 72 --charset rfc3986 # 裸机方式 authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986生成 client_secret 并输出其 PBKDF2 哈希用于填入 Authelia 配置明文输出用于配置 engomo 侧# Docker 方式 docker run --rm authelia/authelia:latest authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986 # 裸机方式 authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986上述两条命令分别对应 生成安全随机值参考指南 与 生成随机密码哈希指南。使用rfc3986字符集可以规避部分 Relying Party包括 engomo 这类商业应用在 Token 端点认证时对凭据 URL 编码不规范的兼容性问题对应 FAQ凭据正确却报错的问题。重要原则engomo 侧配置的是明文secretAuthelia 侧配置的是该明文 secret 的哈希二者互为对应关系每个客户端应使用独立的随机凭据对长度建议超过 40 字符如果客户端请求超时可能是因为 PBKDF2 哈希工作因子迭代次数过高导致每次认证耗时过长。可用time authelia crypto hash generate pbkdf2 --variant sha512 --iterations 310000 --password insecure_password实测耗时再按硬件能力适当调整迭代次数详见 密码哈希调优参考明文存储 client_secret 的行为已被废弃请使用哈希格式。关键参数背后的实现原理form_post 响应模式与授权码流程engomo 配置要求response_modes: [form_post]且response_types: [code]即纯授权码流程 Form Post 响应模式。Authelia 的授权端点实现位于 internal/handlers/handler_oauth2_authorization.goToken 端点实现位于 internal/handlers/handler_oauth2_token.go。其中 Form Post 模式对应 OpenID Connect Core 1.0 与 OAuth 2.0 Form Post Response Mode 规范授权结果以自动提交的 HTML 表单 POST 到回调地址避免在 URL 中暴露授权码降低泄露风险。client_secret_post 认证token_endpoint_auth_method: client_secret_post要求 engomo 在 Token 请求体中携带client_id与client_secret字段。Authelia 侧对凭据的校验逻辑位于 internal/oidc 包provider 与 store 相关实现校验时会对配置中哈希存储的 secret 执行 PBKDF2 验证。这也是为何哈希迭代次数过高会导致 Token 请求超时——每次认证都需重算哈希。opaque Access Token 与 none 签名算法access_token_signed_response_alg: none与userinfo_signed_response_alg: none是 Authelia 的默认值Access Token 为不透明字符串非 JWTengomo 如需校验 Access Token应通过 Authelia 的 Introspection 端点/api/oidc/introspection完成UserInfo 端点/api/oidc/userinfo则直接返回 JSON 用户信息。使用none意味着无需为客户端配置额外的 JWK 签名密钥部署最简单。PKCE 与安全加固建议示例中require_pkce: false、pkce_challenge_method: 表示未强制 PKCE。虽然授权码流程 confidential 客户端 client_secret_post 已具备基本安全性但官方仍推荐若 engomo 支持 PKCE应将require_pkce设为true、pkce_challenge_method设为S256。PKCERFC7636通过绑定code_verifier缓解授权码拦截攻击且对使用自定义 URI scheme如com.engomo.engomo://callback/的原生移动端尤为重要——原生回调 URI 比 Web 回调更容易受到拦截PKCE 是 RFC8252OAuth 2.0 for Native Apps 的核心要求。Authelia 对 PKCE 的实现与S256/plain两种 challenge 方法的语义说明见 集成总览的 Proof Key for Code Exchange 章节。其他可选的加固手段Pushed Authorization RequestsPAR可在客户端级require_pushed_authorization_requests或 Provider 级enforce强制使用显著提升授权流程对钓鱼攻击的抵抗力但多数客户端不支持Authelia 完整支持 RFC9126端点位于/api/oidc/pushed-authorization-requestIssuer IdentificationRFC9207与JARM允许 Relying Party 校验授权响应确由预期 Issuer 返回且未被篡改Authelia 均已完整实现是否启用取决于 engomo 的支持情况Consent同意可通过consent_mode与pre_configured_consent_duration调整用户授权确认的交互方式相关行为细节见 FAQ为什么 Authelia 总是要求同意。验证与排障配置完成后可按以下顺序验证集成是否生效验证 Discovery 端点可达浏览器访问https://auth.example.com/.well-known/openid-configuration确认返回的issuer与 engomo 侧填写的 Issuer 完全一致且authorization_endpoint、token_endpoint、userinfo_endpoint、jwks_uri指向正确的 Authelia 路径路径清单见 集成总览的 Endpoint Implementations 章节。验证 Authelia 配置合法authelia validate-config configuration.yml可检查 YAML 配置含 OIDC 客户端注册是否符合 schema。客户端配置的 schema 定义与校验逻辑位于 internal/configuration/schema 目录。触发登录流程在 engomo 中发起登录确认跳转到 Authelia 门户、完成 two_factor 认证后能正确重定向回https://engomo.example.com/auth。检查回调一致性若重定向时报 redirect_uri 不匹配错误请逐字符核对 engomo 实际回调地址与redirect_uris中的值——redirect_uri 是大小写敏感、必须完全一致的精确匹配。检查密钥一致性若 Token 端点认证失败invalid_client 类错误优先确认 engomo 侧使用的是明文 secret、Authelia 侧使用的是该 secret 的哈希且两端 client_id 完全一致。若确认无误仍报错参考 FAQ 中的编码问题说明检查凭据是否包含会被 URL 编码改变语义的特殊字符。小结将 engomo 接入 Authelia 的核心要点可概括为三件事在 Authelia 中注册一个authorization_codeform_postclient_secret_post的 confidential 客户端并填写两个回调 URI在 engomo 的 Web GUI 中填入 Issuer、Client ID 与明文 Client Secret生产环境务必用authelia crypto命令生成随机凭据并以 PBKDF2 哈希形式存储 secret。本指南同样适用于其他 OpenID Connect 1.0 Relying Party——只需替换redirect_uris、scopes与认证方法即可复用同一套配置方法论。更多客户端集成示例与协议细节可继续阅读 OpenID Connect 1.0 集成总览、Clients 配置参考 与 常见问题 FAQ。【免费下载链接】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），仅供参考