Authelia 集成 FreshRSSOpenID 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/autheliaFreshRSS 是一款自托管的 RSS/Atom 聚合阅读器支持通过 OpenID Connect 1.0 对接外部身份提供商OP。本文以 Authelia 作为 OpenID Connect 1.0 Provider完整演示如何在 Authelia 中注册 FreshRSS 客户端、通过环境变量让 FreshRSS 接入 Authelia并给出源码层面的参数依据与排错思路。读完本文你将能够在自托管环境中为 FreshRSS 启用基于 Authelia 的双因素认证2FA单点登录并理解端口匹配、作用域与令牌签名等关键配置的来龙去脉。测试版本与适用范围本文示例基于以下版本验证见 FreshRSS 集成文档Autheliav4.38.0或更新版本FreshRSSv1.23.1需要说明的是Authelia 的 OpenID Connect 1.0 Provider 属于持续演进的功能不同版本之间的默认值与可用参数可能存在差异具体以你实际部署的 Authelia 版本为准。关于 Provider 的整体能力与协议支持范围可参考 OpenID Connect 1.0 集成介绍其中说明 Authelia 已通过 OpenID Certified™ 认证Basic OP / Implicit OP / Hybrid OP / Form Post OP / Config OP 等配置档并支持 Discovery、PKCE、Pushed Authorization Requests、Token Introspection 与 Revocation 等协议能力。配置前提假设本指南中的示例基于以下假设值中的example.com与auth子域可根据你的实际域名替换配置项假设值FreshRSS 应用根 URLhttps://freshrss.example.com/Authelia 根 URLhttps://auth.example.com/Client IDfreshrssClient Secretinsecure_secretFreshRSS 对外服务端口443其中「端口」一项需要特别强调它指的是 FreshRSS 对外提供 HTTP 服务的端口通常 HTTP 为 80、HTTPS 为 443不是 FreshRSS 容器的内部端口。这一区分直接关系到下文即将讨论的redirect_uri端口匹配问题。关键注意事项1. redirect_uri 必须包含端口FreshRSS 的实现总会在其请求的redirect_uri中包含端口。而 Authelia 严格遵循 OpenID Connect 1.0 规范进行redirect_uri匹配即精确字符串匹配因此客户端注册中的redirect_uris条目必须同样包含端口否则授权请求会被拒绝。反例若 FreshRSS 实际请求的redirect_uri为https://freshrss.example.com:443/i/oidc/而你注册的redirect_uris只写了https://freshrss.example.com/i/oidc/省略:443则二者无法匹配。从源码可以看到 Authelia 对redirect_uris的校验逻辑internal/configuration/validator/identity_providers.go配置加载时会逐个解析每个redirect_uri要求其必须是绝对 URL且不允许重复条目运行时对授权请求中携带的redirect_uri与注册列表进行严格比对。这正是「必须包含端口」这一注意事项的底层原因。2. 通用注意事项根据 Authelia 官方 OIDC 集成文档通用的 oidc-common 短代码模板 中的「Common Notes」以下要点对所有客户端含 FreshRSS均适用client_id必须在所有客户端中唯一本指南中的freshrss仅用于演示可读性生产环境建议生成 64 位随机字符且只能包含 RFC3986 Unreserved Characters长度不超过 100 字符。client_secret同样仅用于演示生产环境务必使用 Authelia 官方工具生成高强度随机值推荐以哈希形式存储在配置中本文示例即使用了 PBKDF2-SHA512 摘要明文存储虽仍被支持但已标记为弃用行为。示例中的客户端配置只包含部分可用选项完整的可用参数与各自效果请参考 OpenID Connect 1.0 客户端配置。在 Authelia 中注册 FreshRSS 客户端客户端配置示例在 Authelia 的configuration.yml中于identity_providers.oidc.clients下新增如下客户端条目示例中client_secret是insecure_secret的 PBKDF2-SHA512 摘要与上文假设保持一致identity_providers: oidc: ## 此处省略 OpenID Connect 1.0 Provider 的其余必填配置。 ## 参见: https://www.authelia.com/c/oidc clients: - client_id: freshrss client_name: FreshRSS client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # insecure_secret 的摘要。 public: false authorization_policy: two_factor require_pkce: false pkce_challenge_method: redirect_uris: - https://freshrss.example.com:443/i/oidc/ scopes: - openid - groups - email - profile 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 客户端配置 以及 客户端配置结构体定义 一一对应结合源码注释给出语义与默认值参数值说明client_idfreshrss客户端唯一标识必填且全局唯一。client_nameFreshRSS展示给终端用户的客户端名称。client_secretPBKDF2-SHA512 摘要用于客户端认证的机密。推荐使用哈希存储public: false时必填。publicfalse声明为机密型confidential客户端即 FreshRSS 持有并可使用 client_secret 在令牌端点完成认证。authorization_policytwo_factor该客户端适用的授权策略默认即为two_factor意味着登录需通过双因素认证。require_pkcefalse是否强制要求 PKCEProof Key for Code Exchange。FreshRSS 的 OIDC 实现不发送 PKCE 相关参数故此处关闭。pkce_challenge_method空客户端被强制使用的 PKCE challenge 方法合法值plain、S256。与require_pkce: false配套留空。redirect_urishttps://freshrss.example.com:443/i/oidc/允许回调的 URI 白名单。必须包含端口443原因见上文。scopesopenid groups email profile允许该客户端请求并授予的作用域。FreshRSS 需要这些作用域来获取用户身份与组信息。response_typescode授权码流程Authorization Code Flow。grant_typesauthorization_code允许使用的授权类型。access_token_signed_response_algnoneAccess Token 的 JWS 签名算法。FreshRSS 依赖 UserInfo 端点获取声明故设为none不签名这也是客户端配置的默认值。userinfo_signed_response_algnoneUserInfo 响应的签名算法默认none即返回普通 JSON。token_endpoint_auth_methodclient_secret_basic令牌端点客户端认证方式通过 HTTP Basic 认证携带 client_id/client_secret这也是默认值。源码层面的默认值佐证在 internal/configuration/schema/identity_providers.go 中DefaultOpenIDConnectClientConfiguration定义了客户端的默认行为AuthorizationPolicy: policyTwoFactor, Scopes: []string{openid, groups, profile, email}, ResponseTypes: []string{code}, ResponseModes: []string{form_post}, AccessTokenSignedResponseAlg: none, UserinfoSignedResponseAlg: none, ConsentMode: auto,可见示例配置中显式写出的authorization_policy: two_factor、scopesopenid/groups/profile/email、response_types: code、access_token_signed_response_alg: none、userinfo_signed_response_alg: none均与默认值一致——显式写出有助于配置自文档化。需要留意的是默认的ResponseModes为form_post若你修改了response_types默认响应模式也会相应变化详见 OpenID Connect 1.0 集成介绍 中的「Response Types」与「Response Modes」小节。另外需要强调示例只给出了客户端注册部分的配置你必须同时完成 OpenID Connect 1.0 Provider 的其余必填配置如issuer_private_keys等参见 OpenID Connect 1.0 Provider 配置。在 FreshRSS 中配置 OpenID ConnectFreshRSS 侧只有一种配置方法环境变量。Authelia 侧则无需修改 FreshRSS 数据库或源码。重要提醒下面的示例使用了insecure_crypto_key作为占位值。该值应按照 FreshRSS 官方建议配置至少应当是一个足够长的随机字符串切勿在生产环境直接沿用示例值。标准环境变量.env在 FreshRSS 的.env文件中加入以下变量OIDC_ENABLED1 OIDC_PROVIDER_METADATA_URLhttps://auth.example.com/.well-known/openid-configuration OIDC_CLIENT_IDfreshrss OIDC_CLIENT_SECRETinsecure_secret OIDC_CLIENT_CRYPTO_KEYinsecure_crypto_key OIDC_REMOTE_USER_CLAIMpreferred_username OIDC_SCOPESopenid groups email profile OIDC_X_FORWARDED_HEADERSX-Forwarded-Host X-Forwarded-Port X-Forwarded-Proto各变量含义OIDC_ENABLED设为1启用 OIDC 登录。OIDC_PROVIDER_METADATA_URLAuthelia 的 OpenID Connect Discovery 元数据端点即https://auth.example.com/.well-known/openid-configuration。FreshRSS 通过该端点自动发现授权端点、令牌端点、JWKS 等信息。该路径属于 IANA well-known 注册路径也是 集成介绍 中「Well Known Discovery Endpoints」一节的官方路径。OIDC_CLIENT_ID/OIDC_CLIENT_SECRET与 Authelia 客户端注册中的client_id/client_secret保持一致。注意此处是明文 secret而 Authelia 配置中存储的是其哈希摘要两者对应同一个值。OIDC_CLIENT_CRYPTO_KEYFreshRSS 用于加密/签名其 OIDC 会话数据的密钥请使用高强度随机字符串。OIDC_REMOTE_USER_CLAIMFreshRSS 用于映射本地用户的声明示例使用preferred_username。OIDC_SCOPESFreshRSS 向 Authelia 请求的作用域必须包含在 Authelia 客户端注册的scopes白名单内此处为openid groups email profile。OIDC_X_FORWARDED_HEADERS当 FreshRSS 位于反向代理之后时用于正确识别 Host、Port 与协议保证回调 URL 与redirect_uri生成正确。Docker Compose 方式若 FreshRSS 通过 Docker Compose 部署将上述变量放入services.freshrss.environment即可services: freshrss: environment: OIDC_ENABLED: 1 OIDC_PROVIDER_METADATA_URL: https://auth.example.com/.well-known/openid-configuration OIDC_CLIENT_ID: freshrss OIDC_CLIENT_SECRET: insecure_secret OIDC_CLIENT_CRYPTO_KEY: insecure_crypto_key OIDC_REMOTE_USER_CLAIM: preferred_username OIDC_SCOPES: openid groups email profile OIDC_X_FORWARDED_HEADERS: X-Forwarded-Host X-Forwarded-Port X-Forwarded-Proto初始化与登录配置完成后可能还需要执行以下步骤打开新部署的 FreshRSS 实例在初始配置创建用户时选择HTTP作为用户认证方式即交由 Authelia 这类外部身份提供商认证。之后用户在 FreshRSS 登录页选择 OIDC/HTTP 登录即会被重定向到 Autheliahttps://auth.example.com按authorization_policy要求完成密码 双因素认证后回跳 FreshRSS。登录流程与底层依据结合 OpenID Connect 1.0 集成介绍 中「Endpoint Implementations」一节整个登录链路如下用户在 FreshRSS 点击登录FreshRSS 作为 Relying Party 向 Authelia 的授权端点https://auth.example.com/api/oidc/authorization发起授权码请求携带client_idfreshrss、redirect_urihttps://freshrss.example.com:443/i/oidc/、response_typecode与请求的作用域Authelia 校验redirect_uri与注册列表严格匹配对未认证用户引导至登录页并按authorization_policy: two_factor要求完成双因素认证认证通过后Authelia 将授权码回跳到 FreshRSS 的回调地址FreshRSS 携带 client_secret 访问令牌端点https://auth.example.com/api/oidc/token认证方式为client_secret_basic换取 Access Token 与 ID TokenFreshRSS 通过UserInfo 端点https://auth.example.com/api/oidc/userinfo获取preferred_username等声明因userinfo_signed_response_alg: none响应为普通 JSON完成本地用户映射与登录。其中授权码流程对应的response_types: code与grant_types: authorization_code的合法取值可分别在 集成介绍 的「Response Types」与「Grant Types」表格中查到client_secret_basic属于该文档「Client Authentication Method」一节列出的机密型客户端认证方式之一。常见问题与排错建议授权请求被拒绝 / 回跳失败优先检查redirect_uri是否精确包含端口如:443并与 FreshRSS 实际发起的回调地址逐字符比对。令牌交换 401确认 FreshRSS 侧的OIDC_CLIENT_ID/OIDC_CLIENT_SECRET与 Authelia 注册的client_id及client_secret对应明文一致FreshRSS 使用client_secret_basic即 HTTP Basic 认证。登录后无法映射用户检查OIDC_REMOTE_USER_CLAIM指定的声明默认preferred_username是否在已授予的作用域内profile作用域通常提供该声明并确认 Authelia 侧scopes白名单包含 FreshRSS 请求的所有作用域。反向代理场景下回调地址错误确认OIDC_X_FORWARDED_HEADERS已配置且代理正确透传X-Forwarded-Host、X-Forwarded-Port、X-Forwarded-Proto头。配置加载报错可在启动 Authelia 前通过authelia validate-config类命令校验配置见 internal/commands 中的配置校验实现redirect_uris必须是绝对 URL 且不能重复。延伸阅读OpenID Connect 1.0 客户端配置客户端全部可选参数的完整说明。OpenID Connect 1.0 Provider 配置Provider 侧必填配置与高级选项。OpenID Connect 1.0 集成介绍协议能力、端点清单、授权类型与响应模式总览。FreshRSS OIDC 文档FreshRSS 官方的 OpenID Connect 管理员指南。【免费下载链接】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），仅供参考