使用 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）等基础概念。

已测试版本

根据官方集成文档，本次集成基于以下版本验证：

• Authelia：v4.39.24（release tag 为v4.39.24）
• engomo：官方文档未标注具体版本号，请以你实际部署的版本为准

支持级别说明

该集成属于 community 级别，意味着：

• 集成文档与配置样例由社区贡献，并非 Authelia 官方认证的商业合作；
• 不同版本的 engomo 行为可能存在差异，若遇到兼容性问题，应从 engomo 侧与 Authelia 侧双向排查；
• Authelia 的核心 OpenID Connect 1.0 实现本身是 OpenID Certified™ 的，但具体应用的适配质量取决于该应用对协议的支持程度。

集成前置条件与假设

官方示例基于以下假设，配置前请将example.com、auth等占位值替换为你自己的域名：

注意：官方文档中example.com等值可通过文档站点提供的“Set Documentation Variables”功能自动替换为你的实际域名（对应 Hugo shortcodesitevar，见 docs/layouts/_shortcodes/sitevar.html）。auth是 Authelia 子域名的默认变量名，domain是你的主域名变量名。

集成前的必读事项

所有 Authelia OpenID Connect 客户端集成文档都要求读者在配置前注意以下几点（对应 oidc-common shortcode 中的 “Before You Begin” 部分）：

1. client_id 必须全局唯一：同一 Authelia 实例下所有客户端不能重复。本文使用engomo仅为了可读性与演示，生产环境应使用随机生成的长字符串（建议 64 个随机字符）。
2. client_id 字符集限制：只能包含 RFC3986 Unreserved Characters（即字母、数字以及-、.、_、~），且长度不能超过 100 字符，否则部分 Relying Party 在编码凭据时会出错。
3. client_secret 不应以明文长期存储：明文存储行为已被废弃，未来版本可能不再支持，强烈推荐使用哈希格式存储（详见下文“密钥生成与哈希存储”）。
4. 示例配置不完整：下方 Authelia 配置片段只包含客户端注册部分，你还必须配置 OpenID Connect 1.0 Provider 配置 中要求的其他强制元素（如 issuer、密钥、存储等）。
5. 示例配置只是子集：它只展示了客户端可用选项的一小部分，建议通读 OpenID Connect 1.0 Clients 完整配置指南 了解全部选项及其影响。

第一步：在 Authelia 中注册 engomo 客户端

以下 YAML 是官方文档给出的 Authelia 侧客户端配置示例，可直接放入你的configuration.yml：

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: '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（条件必填，string）：Authelia 与 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_policy（string，默认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_method（string，默认""）：强制使用指定的 PKCE challenge 方法，合法值为空字符串、plain、S256。设置此值会同时隐式启用require_pkce。示例为空字符串，即不强制；S256是强烈推荐值（只要 Relying Party 支持）。
• redirect_uris（必填，list(string)）：允许该客户端回调的 URI 白名单，大小写敏感，未列入的回调一律视为不安全。示例包含两个 URI：
  • https://engomo.example.com/auth：engomo Web 端的授权回调地址；
  • com.engomo.engomo://callback/：engomo 原生移动端 App 的自定义 URI scheme 回调（由此可推断 engomo 同时提供 Web 与原生客户端形态，这与 Authelia 对 OAuth 2.0 for Native Apps（RFC8252） 的完整支持相对应）。
• scopes（list(string)，默认openid,groups,profile,email）：允许该客户端请求的 scope 列表。示例仅开放openid、email、profile（未含groups），scope 定义可参考 Scope 定义文档。若配置了未定义的 scope，Authelia 会在日志中给出警告（除非客户端启用了client_credentials授权）。
• response_modes（list(string)，默认值取决于 response_types，code时含form_post与query）：允许的响应模式。示例仅允许form_post，即授权响应通过 HTML 表单 POST 方式回传给回调地址，这也是 engomo 所要求的模式。Authelia 完整支持form_post、query、fragment以及 JARM 系列（jwt、form_post.jwt、query.jwt、fragment.jwt）。
• response_types（list(string)，默认code）：允许的响应类型。示例仅允许code，即纯授权码流程（Authorization Code Flow）——这也是官方推荐的最安全响应类型，其余类型（implicit / hybrid）安全性较差。
• grant_types（list(string)，默认authorization_code）：允许该客户端使用的授权类型。示例仅authorization_code。注意文档建议：除非明确知道自己在做什么，否则不要配置此选项；refresh_token仅应授予拥有offline_accessscope 的客户端。
• access_token_signed_response_alg（string，默认none）：Access Token 的签名算法。none表示 Access Token 保持不透明（opaque）格式而非 JWT 格式——这是 Authelia 的默认与推荐行为，原因详见 FAQ：为什么 Access Token 不是 JSON Web Token？。若配置为其他值则启用 RFC9068 JWT Profile Access Token。
• userinfo_signed_response_alg（string，默认none）：UserInfo 端点响应的签名算法。none表示 UserInfo 端点返回普通 JSON 文档（application/json），而非签名的 JWT。多数客户端仅支持none，engomo 亦然。
• token_endpoint_auth_method（string，默认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 没有提供基于文件的配置入口。

操作步骤如下：

1. 以管理员身份登录你的 engomo composer（设计器/管理端）。
2. 选择Server（服务器）。
3. 选择Authentication（认证）。
4. 点击+以新增一种认证方法。
5. 将Name（名称）设置为Authelia。
6. 在Type（类型）中选择OpenID Connect。
7. 点击Create（创建）。
8. 填写以下三个关键字段：

Issuer 必须与 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 章节。

9. 点击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_id（72 字符的 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 侧配置的是明文secret；Authelia 侧配置的是该明文 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.go，Token 端点实现位于 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 为不透明字符串（非 JWT），engomo 如需校验 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。PKCE（RFC7636）通过绑定code_verifier缓解授权码拦截攻击，且对使用自定义 URI scheme（如com.engomo.engomo://callback/）的原生移动端尤为重要——原生回调 URI 比 Web 回调更容易受到拦截，PKCE 是 RFC8252（OAuth 2.0 for Native Apps） 的核心要求。Authelia 对 PKCE 的实现与S256/plain两种 challenge 方法的语义说明见 集成总览的 Proof Key for Code Exchange 章节。

其他可选的加固手段

• Pushed Authorization Requests（PAR）：可在客户端级（require_pushed_authorization_requests）或 Provider 级（enforce）强制使用，显著提升授权流程对钓鱼攻击的抵抗力，但多数客户端不支持（Authelia 完整支持 RFC9126，端点位于/api/oidc/pushed-authorization-request）；
• Issuer Identification（RFC9207）与JARM：允许 Relying Party 校验授权响应确由预期 Issuer 返回且未被篡改，Authelia 均已完整实现，是否启用取决于 engomo 的支持情况；
• Consent（同意）：可通过consent_mode与pre_configured_consent_duration调整用户授权确认的交互方式，相关行为细节见 FAQ：为什么 Authelia 总是要求同意。

验证与排障

配置完成后，可按以下顺序验证集成是否生效：

1. 验证 Discovery 端点可达：浏览器访问https://auth.example.com/.well-known/openid-configuration，确认返回的issuer与 engomo 侧填写的 Issuer 完全一致，且authorization_endpoint、token_endpoint、userinfo_endpoint、jwks_uri指向正确的 Authelia 路径（路径清单见 集成总览的 Endpoint Implementations 章节）。
2. 验证 Authelia 配置合法：authelia validate-config configuration.yml可检查 YAML 配置（含 OIDC 客户端注册）是否符合 schema。客户端配置的 schema 定义与校验逻辑位于 internal/configuration/schema 目录。
3. 触发登录流程：在 engomo 中发起登录，确认跳转到 Authelia 门户、完成 two_factor 认证后能正确重定向回https://engomo.example.com/auth。
4. 检查回调一致性：若重定向时报 redirect_uri 不匹配错误，请逐字符核对 engomo 实际回调地址与redirect_uris中的值——redirect_uri 是大小写敏感、必须完全一致的精确匹配。
5. 检查密钥一致性：若 Token 端点认证失败（invalid_client 类错误），优先确认 engomo 侧使用的是明文 secret、Authelia 侧使用的是该 secret 的哈希，且两端 client_id 完全一致。若确认无误仍报错，参考 FAQ 中的编码问题说明，检查凭据是否包含会被 URL 编码改变语义的特殊字符。

小结

将 engomo 接入 Authelia 的核心要点可概括为三件事：在 Authelia 中注册一个authorization_code+form_post+client_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