Authelia OpenID Connect 1.0 集成 Paperless-ngx环境变量配置与授权码流程实战指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaPaperless-ngx 是目前流行的文档管理系统DMS而 Authelia 是面向 Web 应用的单点登录与多因素认证门户。本文基于 Authelia 官方集成指南docs/content/integration/openid-connect/clients/paperless/index.md完整讲解如何将 Paperless-ngx 作为 OpenID Connect 1.0 Relying Party 接入 Authelia 的 OpenID Connect 1.0 Provider。读完本文你将掌握在 Authelia 中注册paperless客户端的关键参数语义、通过PAPERLESS_SOCIALACCOUNT_PROVIDERS环境变量含 Docker Compose 场景完成 Paperless 端配置的完整方法以及授权码Authorization Code PKCE 流程在该组合中的底层运行原理。开始之前必读注意事项官方所有 OpenID Connect 客户端集成指南共用一个oidc-common短代码定义于 docs/layouts/_shortcodes/oidc-common.html其中包含配置前必须理解的三类通用约束1.client_id约束每个客户端必须使用全局唯一的client_id指南中使用的paperless仅为便于阅读演示生产环境不应直接使用应参考 How Do I Generate a Client Identifier or Client Secret? 生成随机值官方推荐 64 位随机字符满足其余条件即可只能包含 RFC3986 Unreserved Characters 字符长度不得超过 100 个字符。2.client_secret约束指南中的insecure_secret仅作演示生产环境绝对不要使用该字符串可以明文存储于 Authelia 配置中但此行为已被弃用不保证未来版本继续支持强烈推荐存储为哈希形式下文 Authelia 配置示例中即是$pbkdf2-sha512$...格式的摘要。若哈希工作因子过高可能导致客户端请求超时可参考 FAQ 中的 Tuning the work factors 进行调优。3. 配置示例范围示例仅包含客户端注册片段必须同时配置 OpenID Connect 1.0 Provider 配置 中要求的其余必填项示例只展示了一小部分可用选项建议完整阅读 OpenID Connect 1.0 Clients 配置指南 了解每个选项的作用。测试版本本文所述集成方案在以下版本组合上验证通过组件版本Autheliav4.39.20Paperless-ngxv3.0.5假设前提本指南的示例基于以下前提文中出现的example.com等域名可替换为你的实际域名应用根 URLhttps://paperless.example.com/Authelia 根 URLhttps://auth.example.com/即 OpenID Connect 1.0 IssuerClient IDpaperlessClient Secretinsecure_secret配置 Authelia注册 Paperless 客户端以下 YAML 是适用于 Paperless 的 Authelia 客户端注册示例需放置在configuration.yml的identity_providers.oidc.clients列表中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: paperless client_name: Paperless client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # The digest of insecure_secret. public: false authorization_policy: two_factor require_pkce: true pkce_challenge_method: S256 redirect_uris: - https://paperless.example.com/accounts/oidc/authelia/login/callback/ scopes: - openid - profile - email - groups 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 Clients 配置指南 中的完整选项说明client_id必填客户端唯一标识必须与 Paperless 侧配置的client_id完全一致。client_name可选在 Authelia 界面上展示的友好名称缺省时与client_id相同。client_secret按情况必填Authelia 与应用共享的密钥。此处以 PBKDF2-SHA512 哈希形式存储其明文为insecure_secret配置在应用侧的secret字段必须与之匹配。可使用 Authelia 的authelia crypto hash generate pbkdf2 --variant sha512类命令生成自己的哈希。public: false声明为机密confidential客户端类型对应 RFC6749 Section 2.1。此类客户端能安全保管凭据因此可以使用client_secret_basic等需要密钥的认证方式。若设为true公开客户端则client_secret必须为空字符串。authorization_policy: two_factor该客户端发起授权请求时要求用户完成两步验证。可选one_factor、two_factor或 provider 级authorization_policies中自定义的策略名。注意它与 访问控制规则 是两套独立的机制。require_pkce: true与pkce_challenge_method: S256强制该客户端启用 PKCE并强制使用S256质询方法。pkce_challenge_method的合法值为空字符串、plain或S256强烈推荐S256设置该方法会自动隐式启用require_pkce。redirect_uris必填合法的回调 URI 列表大小写敏感必须包含http或httpsscheme。Paperless 的 OIDC 回调地址固定为https://paperless.example.com/accounts/oidc/authelia/login/callback/——注意中间路径中的authelia来自 Paperless 侧provider_id下文详述。未列入此列表的回调将被 Authelia 判定为不安全而拒绝。scopes允许该客户端消费的授权范围列表。此处申请了openid、profile、email、groups其声明映射定义可参考 Scope Definitions。openid是 OIDC 的必选范围profile、email提供用户基础资料与邮箱groups提供用户组信息可用于 Paperless 内部的权限判定。response_types: [code]仅使用授权码Authorization Code响应类型这是最安全的流程Authelia 官方也建议只用code其余响应类型安全性不及它。grant_types: [authorization_code]仅允许授权码授权类型。access_token_signed_response_alg: none与userinfo_signed_response_alg: noneAccess Token 与 UserInfo 端点响应均不以 JWT 签名返回返回普通 JSON这是大多数依赖方的兼容选择。若改为其他算法如RS256则需在jwks或jwks_uri中配置对应密钥。token_endpoint_auth_method: client_secret_basic客户端在 Token 端点通过 HTTP Basic 认证方式RFC6749 规定的凭据编码规则提交client_id/client_secret。机密客户端缺省即为该值Paperless 侧通过token_auth_method: client_secret_basic与之对应。配置 Paperless环境变量方式Paperless 官方仅提供一种 OIDC 配置方式——环境变量基于 django-allauth 的openid_connect社交账号 Provider。下面先给出未压缩的 JSON 参考格式再给出可直接使用的环境变量形式。参考未压缩 JSON 格式以下 JSON 是PAPERLESS_SOCIALACCOUNT_PROVIDERS环境变量在展开后的完整形态便于理解每个字段的含义{ openid_connect: { SCOPE: [openid, profile, email], OAUTH_PKCE_ENABLED: true, APPS: [ { provider_id: authelia, name: Authelia, client_id: paperless, secret: insecure_secret, settings: { server_url: https://auth.example.com, token_auth_method: client_secret_basic } } ] } }字段对应关系如下SCOPEPaperless 请求的 OIDC 范围与 Authelia 客户端配置的scopes对齐此处为openid、profile、email未申请groups也不影响基本登录。OAUTH_PKCE_ENABLED: true启用 PKCE与 Authelia 侧的require_pkce/pkce_challenge_method: S256配合。APPS[].provider_idProvider 标识符值authelia决定了回调 URI 中的/accounts/oidc/authelia/login/callback/路径片段必须与 Authelia 侧redirect_uris中的路径保持一致。APPS[].name登录页面上显示的名称。APPS[].client_id/APPS[].secret与 Authelia 注册的client_id及client_secret明文一一对应。APPS[].settings.server_urlAuthelia 的 OpenID Connect 1.0 Issuer 根 URL即https://auth.example.comPaperless 据此自动发现/.well-known/openid-configuration及授权、Token、UserInfo 等端点。APPS[].settings.token_auth_methodToken 端点认证方式client_secret_basic与 Authelia 侧token_endpoint_auth_method匹配。标准 .env 形式PAPERLESS_APPSallauth.socialaccount.providers.openid_connect PAPERLESS_SOCIALACCOUNT_PROVIDERS{openid_connect:{SCOPE:[openid,profile,email],OAUTH_PKCE_ENABLED:true,APPS:[{provider_id:authelia,name:Authelia,client_id:paperless,secret:insecure_secret,settings:{server_url:https://auth.example.com,token_auth_method:client_secret_basic}}]}}其中PAPERLESS_APPS用于启用 django-allauth 的openid_connectProviderdjango-allauth 是 Paperless 处理社交账号/OIDC 登录的底层框架PAPERLESS_SOCIALACCOUNT_PROVIDERS即上文的压缩 JSON。Docker Compose 形式services: paperless: environment: PAPERLESS_APPS: allauth.socialaccount.providers.openid_connect PAPERLESS_SOCIALACCOUNT_PROVIDERS: {openid_connect:{SCOPE:[openid,profile,email],OAUTH_PKCE_ENABLED:true,APPS:[{provider_id:authelia,name:Authelia,client_id:paperless,secret:insecure_secret,settings:{server_url:https://auth.example.com,token_auth_method:client_secret_basic}}]}}配置完成后重启 Paperless 容器登录页即会出现 Authelia 社交登录入口。认证流程原理授权码 PKCE client_secret_basic从源码结构看该组合的完整登录流程为标准的 Authorization Code Flow用户点击 Paperless 登录页的 AutheliaPaperless 生成code_verifier随机不透明值并计算 SHA-256 摘要的 Base64URL 编码作为code_challenge连同code_challenge_methodS256一起重定向到 Authelia 的授权端点/api/oidc/authorization用户完成 Authelia 侧认证因authorization_policy: two_factor需通过第二因素随后进入授权同意流程Authelia 校验redirect_uri与已注册的redirect_uris完全匹配后携带授权码重定向回 Paperless 回调地址Paperless 以client_secret_basicHTTP Basic 携带client_id/client_secret向 Authelia 的 Token 端点/api/oidc/token换取令牌同时提交code_verifierAuthelia 校验 PKCE证明授权码的持有者并验证客户端凭据后返回 ID Token 与 Access TokenPaperless 再从 UserInfo 端点/api/oidc/userinfo拉取profile/email等声明完成本地用户建立或绑定。PKCE 的价值在于即使授权码被第三方截获由于S256模式下赎回授权码必须出示对应的code_verifier也能有效缓解授权码拦截攻击同时它也是公开客户端无法在 Token 端点认证时的重要补充保护参见 集成指南中的 PKCE 章节。验证与故障排查配置完成后可从以下几方面验证集成是否生效发现端点可达性浏览器访问https://auth.example.com/.well-known/openid-configuration确认能返回包含authorization_endpoint、token_endpoint、userinfo_endpoint等字段的 JSON 文档回调路径一致性确认 Autheliaredirect_uris中的完整路径与 Paperless 实际重定向地址逐字符一致大小写敏感。若使用不同的provider_id请同步修改回调路径中的对应片段日志观察出现问题时查看 Authelia 日志中的 OIDC 相关告警例如请求了未定义的 scope 会输出警告以及 Paperless 容器的 django-allauth 报错日志凭据匹配确认 Authelia 侧client_secret哈希对应的明文与 Paperless 侧secret字段完全一致且未混入多余空格或换行。延伸阅读OpenID Connect 1.0 客户端配置指南完整参数表OpenID Connect 1.0 Provider 配置指南OpenID Connect 1.0 集成总览端点、算法、响应类型OpenID Connect 1.0 范围与声明定义OpenID Connect 1.0 常见问题客户端标识/密钥生成、哈希与明文更多第三方客户端集成示例见 docs/content/integration/openid-connect/clients/ 目录含 Bitwarden、Nextcloud、Grafana 等上百个应用的官方集成指南【免费下载链接】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），仅供参考