使用 Authelia OpenID Connect 1.0 为 Karakeep 启用单点登录客户端注册与环境变量配置实战【免费下载链接】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 官方集成文档Karakeep原 Hoarder撰写完整演示如何将开源书签/稍后阅读应用 Karakeep 接入 Authelia 的 OpenID Connect 1.0 Provider实现统一身份认证。你将掌握 Authelia 侧 OpenID Connect 客户端的完整注册配置含哈希密钥、授权策略、重定向 URI、作用域与令牌签名算法以及 Karakeep 侧基于环境变量的 OIDC 对接方法同时会理解该客户端存在的 claims hydration 缺陷及 Authelia 提供的配置逃生舱Escape Hatch解决方案可直接应用于生产环境的 SSO 部署。集成概览Karakeep此前名为 Hoarder是一款自托管的书签与稍后阅读应用。它原生支持通过 [OpenID Connect 1.0] 协议对接外部身份提供者IdP因此可以借助 Authelia 作为认证后端实现一次登录、处处访问的集中式单点登录体验。集成链路为Authelia扮演 [OpenID Connect 1.0] ProviderOP / 授权服务器负责用户认证、会话管理与令牌签发Karakeep扮演 Relying PartyRP / 客户端应用通过标准授权码流程Authorization Code Flow从 Authelia 获取身份信息。测试版本官方集成指南针对以下版本进行了验证参见 karakeep/index.md组件测试版本Autheliav4.39.24Karakeep原 Hoarderv0.26.0注意这是社区维护的集成示例support.level: community不同版本的客户端或 Authelia 行为可能存在差异请以你实际部署的版本为准。工作原理当用户访问 Karakeep 并点击登录时Karakeep 会读取配置的OAUTH_WELLKNOWN_URLAuthelia 的 OpenID Connect Discovery 端点将用户重定向到 Authelia 的授权端点携带client_id、redirect_uri、response_typecode、scopeopenid profile email等参数用户在 Authelia 门户完成认证按策略可能要求两步验证Authelia 将授权码回调到 Karakeep 的redirect_uriKarakeep 通过令牌端点用client_secret_basic方式换取令牌并从 UserInfo 端点获取email等声明完成本地会话建立。Authelia 作为 OpenID Certified™ 的 Provider认证至 Basic OP / Implicit OP / Hybrid OP / Form Post OP / Config OP 多个 profile端点实现与协议细节可参考 OpenID Connect 1.0 集成介绍 与 OpenID Connect 1.0 Provider 配置。已知缺陷Claims Hydration 问题在开始配置之前必须了解一个重要的兼容性事实Karakeep 对 OpenID Connect 1.0 的支持存在显著缺陷。官方集成指南在 Known Bugs 部分明确标注了claims-hydration问题渲染逻辑见 oidc-common.htmlClaims Hydration该客户端完全不支持 OpenID Connect 1.0因为它没有按照协议预期的流程去获取它所需的声明claims。具体来说符合规范的 RP 应当基于授权时授予的作用域scope通过UserInfo Endpoint获取profile、email等作用域对应的声明参见 OpenID Connect Core 1.0 规范第 5.4 节 Requesting Claims using Scope Values或在必要时通过claims请求参数显式请求。而 Karakeep 绕过了这一流程导致它在无法正确水合hydrate声明时拿不到email等关键字段。针对这一问题Authelia 提供了一种配置逃生舱Configuration Escape Hatch可以在 Authelia 侧将所需声明直接注入 ID Token 中以适配该客户端详见下文配置逃生舱章节。需要留意的是这类缺陷通常也意味着客户端忽略了 OpenID Connect 规范中声明稳定性Claim Stability的要求——规范只允许客户端使用sub与iss这两个保证不变的声明来锚定本地账户而 Karakeep 依赖email这类可变声明进行账户绑定。这两个现象都是客户端未完全符合 OpenID Connect 1.0 规范的明确信号详见 oidc-escape-hatch-claims-hydration.html。配置前提假设官方示例基于以下前提均为演示值生产环境请替换为实际域名与密钥配置项值Application Root URLhttps://karakeep.example.com/Authelia Root URLhttps://auth.example.com/Client IDkarakeepClient Secretinsecure_secret相应地Karakeep 的 OIDC 回调地址为https://karakeep.example.com/api/auth/callback/custom文档中的域名等变量可通过 Authelia 文档站点的变量替换功能自动填入见 sitevar-preferences.html。下文示例统一使用example.com与auth子域。Authelia 侧配置注册 OIDC 客户端在 Authelia 的configuration.yml中于identity_providers.oidc.clients列表下注册 Karakeep 客户端。官方推荐的完整配置如下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: karakeep client_name: Karakeep 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://karakeep.example.com/api/auth/callback/custom scopes: - openid - profile - email 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 Provider 级别的必填配置如issuer_private_key、签名密钥、生命周期等完整说明参见 OpenID Connect 1.0 Provider 配置 与 OpenID Connect 1.0 Clients 配置。关键参数逐项解析以下结合 identity_providers.go 中的客户端配置结构体说明每个参数的作用参数示例值说明client_idkarakeep客户端唯一标识。必须在 Provider 中全局唯一且仅能包含 RFC3986 非保留字符长度不超过 100 字符。文档中的值仅为可读性演示生产环境建议使用 64 位随机字符。client_nameKarakeep客户端显示名称用于在 Authelia 门户的同意页面等处展示。client_secret$pbkdf2-sha512$...客户端机密。示例中给出的是明文insecure_secret的PBKDF2-SHA512 哈希迭代 310000 次强烈推荐以哈希形式存储而非明文明文存储已弃用。publicfalse客户端类型。false表示机密型confidential客户端可在令牌端点进行身份认证。authorization_policytwo_factor该客户端适用的授权策略。two_factor要求用户通过两步验证才能完成授权此外还支持one_factor、deny以及自定义策略见IdentityProvidersOpenIDConnectPolicy结构支持按 subject/network 细化规则定义见 identity_providers.go。require_pkcefalse是否强制要求 PKCEProof Key for Code Exchange。Karakeep 当前未启用。定义见 identity_providers.go。pkce_challenge_method空强制使用的 PKCE 挑战方法可取、plain、S256。空值表示不强制。定义见 identity_providers.go。redirect_urishttps://karakeep.example.com/api/auth/callback/custom允许的回调地址白名单。必须与 Karakeep 配置的回调路径完全一致否则授权失败。scopesopenid,profile,email允许该客户端请求的作用域。Karakeep 需要email用于账户标识。schema 中声明的合法枚举值包括openid、offline_access、profile、email、address、phone、groups等见 identity_providers.go。response_typescode允许的响应类型对应授权码流程。合法值包括code、id_token、token及其组合见 identity_providers.go。grant_typesauthorization_code允许的授权类型。合法值包括authorization_code、implicit、refresh_token、client_credentials及设备码授权等见 identity_providers.go。access_token_signed_response_algnone访问令牌签名算法。none表示返回不签名的透明访问令牌Authelia 默认即返回不透明令牌。合法算法枚举HS/RS/ES/PS/Ed25519/ML-DSA 系列见 identity_providers.go。userinfo_signed_response_algnoneUserInfo 端点响应的签名算法。none表示以纯 JSON 返回application/json。完整算法列表见 identity_providers.go。token_endpoint_auth_methodclient_secret_basic客户端在令牌端点Token Endpoint的认证方式。client_secret_basic表示通过 HTTP Basic Auth 携带客户端凭证。合法值还包括client_secret_post、client_secret_jwt、private_key_jwt、none见 identity_providers.go。关于各签名算法与响应类型的完整支持矩阵可参考 OpenID Connect 1.0 集成介绍 中的 Signing and Content Encryption Algorithms 与 Response Types 章节。配置逃生舱Configuration Escape Hatch由于 Karakeep 存在 claims hydration 缺陷需要启用 Authelia 的逃生舱配置将客户端需要的声明直接注入 ID Token。官方建议的适配方案如下针对karakeep客户端注入email声明identity_providers: oidc: claims_policies: karakeep: id_token: [email] clients: - client_id: karakeep claims_policy: karakeep配置要点claims_policies是 Provider 级的声明策略字典IdentityProvidersOpenIDConnectClaimsPolicy见 identity_providers.go每个策略可通过id_token/access_token字段声明要注入 ID Token 或访问令牌的额外声明客户端通过claims_policy字段引用对应策略见 identity_providers.go该方案的模板渲染逻辑见 oidc-escape-hatch-claims-hydration.html更完整的理论说明为何该问题通常伴随账户锚定缺陷参见 OpenID Connect 1.0 Claims 指南 中关于claims参数之前恢复功能的章节。Karakeep 侧配置环境变量Karakeep 通过环境变量方式对接 Authelia官方提供了两种写法。方式一.env文件标准OAUTH_WELLKNOWN_URLhttps://auth.example.com/.well-known/openid-configuration OAUTH_CLIENT_IDkarakeep OAUTH_CLIENT_SECRETinsecure_secret OAUTH_PROVIDER_NAMEAuthelia方式二Docker Composecompose.ymlservices: karakeep: environment: OAUTH_WELLKNOWN_URL: https://auth.example.com/.well-known/openid-configuration OAUTH_CLIENT_ID: karakeep OAUTH_CLIENT_SECRET: insecure_secret OAUTH_PROVIDER_NAME: Authelia环境变量说明环境变量值作用OAUTH_WELLKNOWN_URLhttps://auth.example.com/.well-known/openid-configurationAuthelia 的 OpenID Connect Discovery 端点。Karakeep 据此自动发现授权端点、令牌端点、UserInfo 端点与 JWKS 等元数据。该路径是 OpenID Connect Discovery 1.0 的 IANA 标准 well-known 路径详见 OpenID Connect 1.0 集成介绍 的 Well Known Discovery Endpoints 章节。OAUTH_CLIENT_IDkarakeep必须与 Authelia 客户端配置中的client_id完全一致。OAUTH_CLIENT_SECRETinsecure_secret必须与 Authelia 配置中的客户端机密对应。注意此处填写的是明文与 Authelia 配置中存储的哈希值对应生产环境务必使用强随机值。OAUTH_PROVIDER_NAMEAuthelia登录界面展示的 Provider 名称可按需自定义。配置完成后重启 Karakeep 容器访问其登录页即可看到通过 Authelia 进行 OIDC 登录的入口。通用安全注意事项无论对接何种客户端以下来自官方集成文档的通用规范都适用详见 oidc-common.htmlclient_id必须全局唯一、仅含 RFC3986 非保留字符、长度不超过 100 字符。指南中的karakeep仅为演示生产环境应使用至少 64 位随机字符的标识。client_secret指南中的insecure_secret仅用于演示绝对不要在生产环境使用明文存储已弃用应使用 PBKDF2 等算法哈希后存储可使用authelia crypto hash generate pbkdf2 --variant sha512等命令生成参见 crypto_hash.go 相关实现若哈希迭代成本work factor过高可能导致客户端请求超时必要时需调整工作因子参见 Frequently Asked Questions 中 Tuning the work factors 章节。Provider 级配置客户端注册示例只覆盖客户端部分identity_providers.oidc下的 Provider 必填项必须另行完整配置。完整选项客户端可用选项远不止示例中的这些如consent_mode、lifespan、require_pushed_authorization_requests、各类端点的认证方式与签名算法、jwks等完整清单见 clients.md建议熟悉全部选项后再按需调整。参考与延伸阅读Karakeep OIDC 集成指南本文档源OpenID Connect 1.0 Clients 配置OpenID Connect 1.0 Provider 配置OpenID Connect 1.0 集成介绍OpenID Connect 1.0 Claims 指南OpenID Connect Frequently Asked Questions客户端配置结构体源码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），仅供参考
