2026/9/12 4:50:08
FEATURED · 精选文章 
使用 Authelia OpenID Connect 1.0 为 BookLore 配置单点登录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本指南基于 Authelia 官方集成文档完整讲解如何将自托管的电子书管理应用 BookLore 接入 Authelia 的 OpenID Connect 1.0 提供商实现统一身份认证与单点登录。文中包含可直接复制的 Authelia 客户端配置 YAML、BookLore Web 管理界面逐步操作指引以及针对 BookLore 已知缺陷Claims Hydration的配置逃生舱Configuration Escape Hatch方案读者按步骤操作即可让 BookLore 用户通过 Authelia 完成登录并获得preferred_username、email、name等用户信息。测试版本与适用范围本集成指南在以下版本组合下经过官方验证Autheliav4.39.24BookLorev1.5.1Authelia 本身作为 OpenID Connect 1.0 提供商已通过 OpenID 认证Basic OP / Implicit OP / Hybrid OP / Form Post OP / Config OP 五个 Profile因此本集成属于OpenID 认证提供商 第三方依赖方Relying Party的标准对接场景。需要说明的是BookLore 对 OpenID Connect 1.0 的支持目前标记为Experimental实验性集成时请知悉这一前提。前置假设本示例基于以下假设展开实际操作时请替换为你的真实域名与地址项目假设值应用根 URLBookLorehttps://booklore.example.com/Authelia 根 URLIssuerhttps://auth.example.com/客户端 IDClient IDbooklore其中example.com为示例域名auth为 Authelia 使用的子域名。指南中出现的部分值会随文档变量自动替换请以你实际部署的域名为准。在 Authelia 中注册 BookLore 客户端完整客户端配置示例以下 YAML 是用于对接 BookLore 的 Authelia 客户端配置 示例可直接放入configuration.yml中identity_providers.oidc.clients列表identity_providers: oidc: ## OpenID Connect 1.0 提供商的其余必填配置项写在这里。 clients: - client_id: booklore client_name: BookLore public: true authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 redirect_uris: - https://booklore.example.com/api/oidc scopes: - openid - offline_access - profile - email response_types: - code grant_types: - authorization_code - refresh_token access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: none关键配置项逐项说明上述配置中每个字段都可以在 Authelia 官方 OpenID Connect 1.0 Clients 配置指南 中找到详细定义要点如下client_id必填客户端标识必须与 BookLore 中配置的 Client ID 完全一致。合法的 Client ID 需满足长度不超过 100 字符、仅包含 RFC3986 Unreserved Characters即字母、数字及-、.、_、~、在所有已注册客户端中全局唯一。client_name可选客户端在 Authelia 界面中展示的友好名称默认与 ID 相同此处设为BookLore。public: true将客户端声明为公共客户端Public Client。这适用于无法安全保管客户端凭据的应用如纯前端 SPA、CLI 工具见 RFC6749 Section 2.1。设置为公共客户端后client_secret必须留空同时按规范要求token_endpoint_auth_method必须为none。authorization_policy: two_factor该客户端的授权策略可选one_factor、two_factor或提供商级authorization_policies中自定义的策略。设为two_factor意味着访问 BookLore 前用户必须完成双因素认证。注意此策略仅作用于授权请求与 Authelia 的访问控制规则Access Control Rules是两套独立机制。require_pkce: true与pkce_challenge_method: S256强制该客户端使用 PKCEProof Key for Code ExchangeRFC7636。S256方法要求依赖方生成随机code_verifier经 SHA-256 摘要后再 Base64URL 编码为code_challenge随授权请求发送换取令牌时再回传原始code_verifier可有效缓解授权码拦截攻击。配置pkce_challenge_method会同时隐式启用require_pkce。S256是强烈推荐的挑战方法plain仅应在依赖方技术上无法支持S256时使用。redirect_uris允许的回调 URI 白名单BookLore 的 OIDC 回调地址为https://booklore.example.com/api/oidc。URI 区分大小写必须携带http或https协议头不在列表中的回调会被拒绝并报错。scopes允许该客户端申请的权限范围。openid是启用 OpenID Connect 1.0 语义如返回 ID Token的前提offline_access允许获取 Refresh Token 以实现会话保持profile、email提供用户画像与邮箱声明。完整范围与声明映射关系见 OpenID Connect 1.0 Claims 指南。response_types: [code]仅启用授权码流程Authorization Code Flow。官方安全建议除非确有必要只使用code这一响应类型其他类型安全性不如它。grant_types允许的授权类型。此处为authorization_code换取授权码流程令牌与refresh_token配合offline_access使用刷新令牌续期。access_token_signed_response_alg: none与userinfo_signed_response_alg: noneAccess Token 与 UserInfo 端点响应均不签名保持默认的 opaque 令牌与纯 JSON 响应。绝大多数客户端只支持none若设为其他算法UserInfo 端点返回的将是从 JSON 文档变为 JWT而 Access Token 则按 RFC9068 编码为 JWT Profile 令牌其验证语义与 ID Token 完全不同。token_endpoint_auth_method: none公共客户端在令牌端点的标准认证方式。规范要求公共客户端类型默认即为none机密客户端默认才是client_secret_basic。关于 Client ID 与 Client Secret 的通用注意事项根据 Authelia 集成文档的通用说明见 oidc-common 短代码无论对接哪个客户端都应遵守以下要点client_id必须是每个客户端唯一的值本指南中的booklore仅为便于阅读和演示生产环境不应直接使用该值建议使用 64 位随机字符生成方式参考 如何生成客户端标识或密钥 FAQ。若使用机密客户端client_secret可以明文存放在配置中但该行为已弃用不保证未来仍受支持强烈推荐在配置中使用哈希形式存储密钥。注意当密钥以哈希形式存储时过高的哈希成本可能导致客户端请求超时可参考 FAQ 中Tuning the work factors一节调整。上述示例只包含客户端注册部分你还必须按 OpenID Connect 1.0 提供商配置指南 完成identity_providers.oidc下的必填配置如issuer与密钥材料等并建议通读客户端配置指南了解全部可选参数及其影响。已知问题Claims Hydration 与配置逃生舱问题本质Authelia 官方在集成测试中发现BookLore 存在一个显著缺陷Known Significant Bug——Claims Hydration声明水合该客户端没有遵循 OpenID Connect 1.0 的规范流程去获取所需声明。按规范OpenID Connect Core 1.0 Section 5.4通过 Scope 申请的声明应通过使用 Access Token 访问 UserInfo 端点获取除不返回 Access Token 的 Implicit Flow 外或在授权请求中使用claims参数显式申请Section 5.5。而 BookLore 两者都没有正确实现。同时此类缺陷往往还伴随对声明稳定性要求Section 5.7 Claim Stability and Uniqueness的忽视——规范要求依赖方只能通过sub与iss这两个保证不变的声明来锚定本地账号而 BookLore 使用email、preferred_username等可变声明关联用户。这两点都表明该客户端并未完整、合规地支持 OpenID Connect 1.0官方建议鼓励应用开发者修复这些缺陷。逃生舱Escape Hatch配置由于某些项目年久失修或开发者无暇修复Authelia 为这类不完整支持 OIDC的客户端提供了逃生舱机制通过claims_policies将声明水合进 ID Token从而恢复其原有功能。针对 BookLore需要在上述配置之外追加如下配置identity_providers: oidc: claims_policies: booklore: id_token: [email, preferred_username, name] clients: - client_id: booklore claims_policy: booklore这段配置在 OpenID Connect 1.0 Claims 指南 中属于Restore Functionality Prior to Claims Parameter方案claims_policies下的键名此处为booklore是任意自定义值通过客户端的claims_policy选项引用id_token列表中列出的是在满足相应 scope 授予条件下除标准 ID Token 声明之外自动拷贝进 ID Token 的声明。该示例恢复的是 BookLore 实际依赖的email、preferred_username、name三个声明对应其 Username Claim、Email Claim、Display Name Claim 映射。安全警告必须强调claims_policies.id_token是官方标注为highly discouraged高度不推荐的逃生舱选项。它会将本不该出现在未加密 ID Token 中的个人身份信息PII水合进去而且通常意味着客户端未使用isssub锚定用户存在潜在的安全隐患。该选项仅以尽力而为best-effort的方式提供官方强烈建议优先推动客户端修复自身缺陷改为通过 Access Token 访问 UserInfo 端点获取声明这一标准流程更稳定也是未来的长期保证如确实必须使用逃生舱请精确甄别客户端真正需要的声明只列入最少必要集合而不要照搬示例中全部声明。此外sub声明在 Authelia 中采用 RFC4122 UUID v4 格式isssub的组合是规范唯一认可的账号关联方式preferred_username、email只应被用于新账号的初始化provisioning。在 BookLore 中配置 OIDCWeb GUIBookLore 目前只有一种配置方式通过其 Web 管理界面完成。步骤如下在 BookLore 界面右上角点击设置图标齿轮形状点击Authentication认证在OIDC Authentication (Experimental)OIDC 认证实验性区域配置以下选项OIDC Enabled切换到开启on位置Provider NameAutheliaClient IDbookloreIssuer URIhttps://auth.example.com即 Authelia 的根 URL也是 OIDC Issuer不包含末尾斜杠Scopeopenid profile email offline_accessUsername Claimpreferred_usernameEmail ClaimemailDisplay Name Claimname点击Save Settings保存设置。上图为 BookLore 的Authentication配置页实拍展示了 OIDC Enabled 开关、Provider Name、Client ID、Issuer URI、Scope 以及 Username/Email/Display Name 三个声明映射字段的具体填写效果。其中 Scope 中的offline_access与 Authelia 侧grant_types中的refresh_token配合使 BookLore 在用户初次授权后可以长期通过刷新令牌维持会话三个声明映射则与 Authelia 侧逃生舱水合进 ID Token 的声明一一对应。请注意 BookLore 的Internal Authentication内部认证默认启用且不可禁用OIDC 会与其共存二者并不冲突。配置核对与排障建议完成两侧配置后可按以下顺序核对确认 Client ID 一致Authelia 配置中的client_id与 BookLore 设置中的 Client ID 必须完全一致确认回调地址匹配BookLore 的回调地址为/api/oidc务必与 Autheliaredirect_uris中的条目完全一致区分大小写、协议一致确认 Issuer URI 可访问BookLore 会通过Issuer URI发现 Authelia 的/.well-known/openid-configuration元数据端点请确保该地址是 Authelia 根 URL例如https://auth.example.com且可从 BookLore 所在网络访问启用 PKCE 后行为由于客户端是公共客户端且启用了S256PKCE授权码交换时 BookLore 必须回传code_verifier请勿在 BookLore 侧关闭相关选项观察登录声明若登录后用户名、邮箱或显示名未正确填充请确认逃生舱的claims_policies配置已正确应用claims_policy: booklore并检查 Authelia 日志中是否存在 scope 相关告警。相关资源OpenID Connect 1.0 集成指南协议支持、端点、安全机制总览OpenID Connect 1.0 Claims 指南Scope 定义、声明映射与逃生舱详解OpenID Connect 1.0 客户端配置指南OpenID Connect 1.0 提供商配置指南OpenID Connect 集成常见问题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），仅供参考
使用 Authelia OpenID Connect 1.0 为 BookLore 配置单点登录（SSO）完整指南
使用 Authelia OpenID Connect 1.0 为 BookLore 配置单点登录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本指南基于 Authelia 官方集成文档完整讲解如何将自托管的电子书管理应用 BookLore 接入 Authelia 的 OpenID Connect 1.0 提供商实现统一身份认证与单点登录。文中包含可直接复制的 Authelia 客户端配置 YAML、BookLore Web 管理界面逐步操作指引以及针对 BookLore 已知缺陷Claims Hydration的配置逃生舱Configuration Escape Hatch方案读者按步骤操作即可让 BookLore 用户通过 Authelia 完成登录并获得preferred_username、email、name等用户信息。测试版本与适用范围本集成指南在以下版本组合下经过官方验证Autheliav4.39.24BookLorev1.5.1Authelia 本身作为 OpenID Connect 1.0 提供商已通过 OpenID 认证Basic OP / Implicit OP / Hybrid OP / Form Post OP / Config OP 五个 Profile因此本集成属于OpenID 认证提供商 第三方依赖方Relying Party的标准对接场景。需要说明的是BookLore 对 OpenID Connect 1.0 的支持目前标记为Experimental实验性集成时请知悉这一前提。前置假设本示例基于以下假设展开实际操作时请替换为你的真实域名与地址项目假设值应用根 URLBookLorehttps://booklore.example.com/Authelia 根 URLIssuerhttps://auth.example.com/客户端 IDClient IDbooklore其中example.com为示例域名auth为 Authelia 使用的子域名。指南中出现的部分值会随文档变量自动替换请以你实际部署的域名为准。在 Authelia 中注册 BookLore 客户端完整客户端配置示例以下 YAML 是用于对接 BookLore 的 Authelia 客户端配置 示例可直接放入configuration.yml中identity_providers.oidc.clients列表identity_providers: oidc: ## OpenID Connect 1.0 提供商的其余必填配置项写在这里。 clients: - client_id: booklore client_name: BookLore public: true authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 redirect_uris: - https://booklore.example.com/api/oidc scopes: - openid - offline_access - profile - email response_types: - code grant_types: - authorization_code - refresh_token access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: none关键配置项逐项说明上述配置中每个字段都可以在 Authelia 官方 OpenID Connect 1.0 Clients 配置指南 中找到详细定义要点如下client_id必填客户端标识必须与 BookLore 中配置的 Client ID 完全一致。合法的 Client ID 需满足长度不超过 100 字符、仅包含 RFC3986 Unreserved Characters即字母、数字及-、.、_、~、在所有已注册客户端中全局唯一。client_name可选客户端在 Authelia 界面中展示的友好名称默认与 ID 相同此处设为BookLore。public: true将客户端声明为公共客户端Public Client。这适用于无法安全保管客户端凭据的应用如纯前端 SPA、CLI 工具见 RFC6749 Section 2.1。设置为公共客户端后client_secret必须留空同时按规范要求token_endpoint_auth_method必须为none。authorization_policy: two_factor该客户端的授权策略可选one_factor、two_factor或提供商级authorization_policies中自定义的策略。设为two_factor意味着访问 BookLore 前用户必须完成双因素认证。注意此策略仅作用于授权请求与 Authelia 的访问控制规则Access Control Rules是两套独立机制。require_pkce: true与pkce_challenge_method: S256强制该客户端使用 PKCEProof Key for Code ExchangeRFC7636。S256方法要求依赖方生成随机code_verifier经 SHA-256 摘要后再 Base64URL 编码为code_challenge随授权请求发送换取令牌时再回传原始code_verifier可有效缓解授权码拦截攻击。配置pkce_challenge_method会同时隐式启用require_pkce。S256是强烈推荐的挑战方法plain仅应在依赖方技术上无法支持S256时使用。redirect_uris允许的回调 URI 白名单BookLore 的 OIDC 回调地址为https://booklore.example.com/api/oidc。URI 区分大小写必须携带http或https协议头不在列表中的回调会被拒绝并报错。scopes允许该客户端申请的权限范围。openid是启用 OpenID Connect 1.0 语义如返回 ID Token的前提offline_access允许获取 Refresh Token 以实现会话保持profile、email提供用户画像与邮箱声明。完整范围与声明映射关系见 OpenID Connect 1.0 Claims 指南。response_types: [code]仅启用授权码流程Authorization Code Flow。官方安全建议除非确有必要只使用code这一响应类型其他类型安全性不如它。grant_types允许的授权类型。此处为authorization_code换取授权码流程令牌与refresh_token配合offline_access使用刷新令牌续期。access_token_signed_response_alg: none与userinfo_signed_response_alg: noneAccess Token 与 UserInfo 端点响应均不签名保持默认的 opaque 令牌与纯 JSON 响应。绝大多数客户端只支持none若设为其他算法UserInfo 端点返回的将是从 JSON 文档变为 JWT而 Access Token 则按 RFC9068 编码为 JWT Profile 令牌其验证语义与 ID Token 完全不同。token_endpoint_auth_method: none公共客户端在令牌端点的标准认证方式。规范要求公共客户端类型默认即为none机密客户端默认才是client_secret_basic。关于 Client ID 与 Client Secret 的通用注意事项根据 Authelia 集成文档的通用说明见 oidc-common 短代码无论对接哪个客户端都应遵守以下要点client_id必须是每个客户端唯一的值本指南中的booklore仅为便于阅读和演示生产环境不应直接使用该值建议使用 64 位随机字符生成方式参考 如何生成客户端标识或密钥 FAQ。若使用机密客户端client_secret可以明文存放在配置中但该行为已弃用不保证未来仍受支持强烈推荐在配置中使用哈希形式存储密钥。注意当密钥以哈希形式存储时过高的哈希成本可能导致客户端请求超时可参考 FAQ 中Tuning the work factors一节调整。上述示例只包含客户端注册部分你还必须按 OpenID Connect 1.0 提供商配置指南 完成identity_providers.oidc下的必填配置如issuer与密钥材料等并建议通读客户端配置指南了解全部可选参数及其影响。已知问题Claims Hydration 与配置逃生舱问题本质Authelia 官方在集成测试中发现BookLore 存在一个显著缺陷Known Significant Bug——Claims Hydration声明水合该客户端没有遵循 OpenID Connect 1.0 的规范流程去获取所需声明。按规范OpenID Connect Core 1.0 Section 5.4通过 Scope 申请的声明应通过使用 Access Token 访问 UserInfo 端点获取除不返回 Access Token 的 Implicit Flow 外或在授权请求中使用claims参数显式申请Section 5.5。而 BookLore 两者都没有正确实现。同时此类缺陷往往还伴随对声明稳定性要求Section 5.7 Claim Stability and Uniqueness的忽视——规范要求依赖方只能通过sub与iss这两个保证不变的声明来锚定本地账号而 BookLore 使用email、preferred_username等可变声明关联用户。这两点都表明该客户端并未完整、合规地支持 OpenID Connect 1.0官方建议鼓励应用开发者修复这些缺陷。逃生舱Escape Hatch配置由于某些项目年久失修或开发者无暇修复Authelia 为这类不完整支持 OIDC的客户端提供了逃生舱机制通过claims_policies将声明水合进 ID Token从而恢复其原有功能。针对 BookLore需要在上述配置之外追加如下配置identity_providers: oidc: claims_policies: booklore: id_token: [email, preferred_username, name] clients: - client_id: booklore claims_policy: booklore这段配置在 OpenID Connect 1.0 Claims 指南 中属于Restore Functionality Prior to Claims Parameter方案claims_policies下的键名此处为booklore是任意自定义值通过客户端的claims_policy选项引用id_token列表中列出的是在满足相应 scope 授予条件下除标准 ID Token 声明之外自动拷贝进 ID Token 的声明。该示例恢复的是 BookLore 实际依赖的email、preferred_username、name三个声明对应其 Username Claim、Email Claim、Display Name Claim 映射。安全警告必须强调claims_policies.id_token是官方标注为highly discouraged高度不推荐的逃生舱选项。它会将本不该出现在未加密 ID Token 中的个人身份信息PII水合进去而且通常意味着客户端未使用isssub锚定用户存在潜在的安全隐患。该选项仅以尽力而为best-effort的方式提供官方强烈建议优先推动客户端修复自身缺陷改为通过 Access Token 访问 UserInfo 端点获取声明这一标准流程更稳定也是未来的长期保证如确实必须使用逃生舱请精确甄别客户端真正需要的声明只列入最少必要集合而不要照搬示例中全部声明。此外sub声明在 Authelia 中采用 RFC4122 UUID v4 格式isssub的组合是规范唯一认可的账号关联方式preferred_username、email只应被用于新账号的初始化provisioning。在 BookLore 中配置 OIDCWeb GUIBookLore 目前只有一种配置方式通过其 Web 管理界面完成。步骤如下在 BookLore 界面右上角点击设置图标齿轮形状点击Authentication认证在OIDC Authentication (Experimental)OIDC 认证实验性区域配置以下选项OIDC Enabled切换到开启on位置Provider NameAutheliaClient IDbookloreIssuer URIhttps://auth.example.com即 Authelia 的根 URL也是 OIDC Issuer不包含末尾斜杠Scopeopenid profile email offline_accessUsername Claimpreferred_usernameEmail ClaimemailDisplay Name Claimname点击Save Settings保存设置。上图为 BookLore 的Authentication配置页实拍展示了 OIDC Enabled 开关、Provider Name、Client ID、Issuer URI、Scope 以及 Username/Email/Display Name 三个声明映射字段的具体填写效果。其中 Scope 中的offline_access与 Authelia 侧grant_types中的refresh_token配合使 BookLore 在用户初次授权后可以长期通过刷新令牌维持会话三个声明映射则与 Authelia 侧逃生舱水合进 ID Token 的声明一一对应。请注意 BookLore 的Internal Authentication内部认证默认启用且不可禁用OIDC 会与其共存二者并不冲突。配置核对与排障建议完成两侧配置后可按以下顺序核对确认 Client ID 一致Authelia 配置中的client_id与 BookLore 设置中的 Client ID 必须完全一致确认回调地址匹配BookLore 的回调地址为/api/oidc务必与 Autheliaredirect_uris中的条目完全一致区分大小写、协议一致确认 Issuer URI 可访问BookLore 会通过Issuer URI发现 Authelia 的/.well-known/openid-configuration元数据端点请确保该地址是 Authelia 根 URL例如https://auth.example.com且可从 BookLore 所在网络访问启用 PKCE 后行为由于客户端是公共客户端且启用了S256PKCE授权码交换时 BookLore 必须回传code_verifier请勿在 BookLore 侧关闭相关选项观察登录声明若登录后用户名、邮箱或显示名未正确填充请确认逃生舱的claims_policies配置已正确应用claims_policy: booklore并检查 Authelia 日志中是否存在 scope 相关告警。相关资源OpenID Connect 1.0 集成指南协议支持、端点、安全机制总览OpenID Connect 1.0 Claims 指南Scope 定义、声明映射与逃生舱详解OpenID Connect 1.0 客户端配置指南OpenID Connect 1.0 提供商配置指南OpenID Connect 集成常见问题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），仅供参考 
)
