使用 Authelia OpenID Connect 1.0 为 Papra 配置单点登录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 官方文档库中的 Papra 集成文档 展开完整演示如何将自托管的 Papra 文档/文件管理应用接入 Authelia 的 OpenID Connect 1.0 Provider实现统一身份认证与多因素认证2FA登录。读完本文你将掌握 Authelia 侧 OIDC 客户端的完整注册方式、Papra 侧AUTH_PROVIDERS_CUSTOMS环境变量的两种配置方法.env与 Docker Compose以及客户端密钥哈希、作用域、回调地址等关键参数的底层含义与排障思路。测试版本与适用范围原文档记录的测试版本如下组件版本Autheliav4.39.24Paprav26.1.0Papra 是社区维护的自托管文档管理与发布平台本集成属于community社区级别支持意味着该配置由社区验证并提供示例并不代表 Papra 官方与 Authelia 存在联合保障。在将示例投入生产前建议在目标版本上重新验证。开始之前注册客户端的通用须知本指南嵌入的{{% oidc-common %}}通用片段其模板实现位于 docs/layouts/_shortcodes/oidc-common.html强调了几条适用于所有OpenID Connect 1.0 客户端注册的关键约束配置前务必阅读client_id必须全局唯一。示例中的papra仅为可读性而设生产环境应使用随机生成的值长度建议 64 个随机字符不得超过 100 字符且只能包含 RFC3986 Unreserved Characters大小写字母、数字以及-、.、_、~。client_secret必须与 Papra 中配置的明文值完全一致。Authelia 配置文件中强烈建议存储该密钥的哈希值而非明文明文存储已被正式弃用。同时要注意哈希计算的工作因子过高可能导致客户端请求超时相关调优方法见 常见问题文档。下方的 Authelia 配置示例只包含客户端注册片段你还必须按照 OpenID Connect 1.0 Provider 配置 文档补齐identity_providers.oidc下的issuer_private_keys即jwks其中至少需要一个 RS256 密钥、hmac_secret等必需项这些必选项同样体现在 config.template.yml 的模板注释中。示例仅展示了客户端可用配置项的一小部分完整选项清单请查阅 OpenID Connect 1.0 Clients 配置。如何生成安全的 Client ID 与 Client Secret参考 How do I generate a client identifier or client secret?可使用 Authelia 自带的 CLI 命令生成随机值并直接产出 PBKDF2 哈希# 生成 72 字符的随机 Client IDDocker 部署时加 docker run --rm authelia/authelia:latest 前缀 authelia crypto rand --length 72 --charset rfc3986 # 生成随机 Client Secret 并输出可用于配置文件client_secret 字段的 PBKDF2-SHA512 哈希 authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986该命令同时会输出 URL 编码后的版本以规避部分客户端在client_secret_basic/client_secret_post认证时未按规范进行 URL 转义的问题。部署假设本示例基于以下假设文档中的{{ sitevar }}变量默认值即example.com实际部署请替换为你的真实域名项值Papra 应用根 URLhttps://papra.example.com/Authelia 根 URLhttps://auth.example.com/Client IDpapraClient Secretinsecure_secret提示文档站点支持通过 sitevar 变量自动替换域名占位符阅读在线版文档时可启用该功能下文直接以example.com展示。在 Authelia 中注册 Papra 客户端完整配置示例将以下片段加入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: papra client_name: Papra 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://papra.example.com/api/auth/oauth2/callback/authelia 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_post关键参数逐项解读以下参数的行为均可在 OpenID Connect 1.0 Clients 配置 中找到完整规范这里结合 Papra 场景给出针对性说明client_id必填papra。必须与 Papra 端AUTH_PROVIDERS_CUSTOMS中的clientId完全一致且全局唯一、不超过 100 字符、仅含 RFC3986 非保留字符。client_name可选默认同client_idPapra用于在 Authelia 的授权/同意页面等 UI 中展示的友好名称。client_secret机密型客户端必填上例中的$pbkdf2-sha512$...是明文insecure_secret的 PBKDF2-SHA512 哈希310000 次迭代。Authelia 在收到客户端请求时会执行哈希运算进行比对因此哈希值存储不会影响客户端使用明文密钥。不推荐在配置中写明文$plaintext$前缀形式已被弃用。public默认falsePapra 属于服务端应用能够安全保管客户端凭据因此使用机密型客户端confidential设置为false且必须提供client_secret。authorization_policy默认two_factor控制该客户端发起的授权请求所需的认证强度可选one_factor、two_factor或 provider 级 authorization_policies 中自定义的策略名。示例使用two_factor即用户必须完成第二因素认证才能登录 Papra。注意该选项与 访问控制规则 是两套独立机制。require_pkce/pkce_challenge_method示例均为默认值false/ 空字符串即不强制 PKCE。若希望为 Papra 强制 PKCE可将require_pkce设为truepkce_challenge_method可强制指定plain或S256强烈推荐S256。设置该方法会同时隐式启用require_pkce。Papra 的 Docker Compose 示例中额外携带了pkce: true两端如需启用应保持一致。redirect_uris必填https://papra.example.com/api/auth/oauth2/callback/authelia。这是 Papra 的 OAuth2 回调地址大小写敏感且必须与 Papra 实际配置完全一致未在列表中注册的回调地址会被 Authelia 判定为不安全并拒绝授权。scopesopenid、profile、email。各作用域对应的默认声明位置ID Token 还是 UserInfo 端点可参考 OpenID Connect 1.0 Claims 与作用域定义。openid是 OIDC 必需作用域profile提供用户名等资料声明email提供邮箱声明三者与 Papra 端scopes数组一一对应。response_typescode即标准的授权码流程Authorization Code Flow是官方推荐的最安全响应类型对应 OAuth 2.0 授权码授权。grant_typesauthorization_code与response_types: [code]配套。默认即为该值未配置其他授权类型时可不显式声明。access_token_signed_response_alg/userinfo_signed_response_alg默认nonenone表示 Access Token 与 UserInfo 响应均以不透明/JSON 形式返回不启用 RFC9068 JWT Profile 或 JWT 签名的 UserInfo。绝大多数客户端默认仅支持none。token_endpoint_auth_methodclient_secret_post即客户端在 Token 端点通过 POST 表单体提交client_id与client_secret完成认证另一种常用方式是client_secret_basic通过 HTTP Basic 头携带。Papra 端采用client_secret_post与其匹配。在 Papra 中配置 Authelia 作为自定义 OIDC 提供方Papra 的配置方式只有一种环境变量。核心变量为AUTH_PROVIDERS_CUSTOMS它是一个 JSON 数组字符串用于声明自定义 OAuth2/OIDC 提供方列表。标准.env方式AUTH_PROVIDERS_CUSTOMS[{providerId: authelia,providerName: Authelia,providerIconUrl: https://www.authelia.com/images/branding/logo-cropped.png,clientId: papra,clientSecret: insecure_secret,type: oidc,discoveryUrl: https://auth.example.com/.well-known/openid-configuration,scopes: [openid, profile, email]}]Docker Compose 方式services: papra: environment: AUTH_PROVIDERS_CUSTOMS: [{providerId: authelia,providerName: Authelia,providerIconUrl: https://www.authelia.com/images/branding/logo-cropped.png,clientId: papra,clientSecret: insecure_secret,pkce: true,type: oidc,discoveryUrl: https://auth.example.com/.well-known/openid-configuration,scopes: [openid, profile, email]}]JSON 字段含义字段示例值说明providerIdauthelia提供方唯一标识用于 Papra 内部区分登录入口。providerNameAuthelia登录页面上展示的提供方名称。providerIconUrlhttps://www.authelia.com/images/branding/logo-cropped.png登录按钮图标地址。clientIdpapra必须与 Authelia 侧client_id完全一致。clientSecretinsecure_secret必须与 Authelia 侧client_secret的明文一致Authelia 侧存哈希Papra 侧用明文。pkcetrueCompose 示例是否启用 PKCE。Compose 示例启用了 PKCE而 Authelia 示例配置中require_pkce: false两端应保持一致的策略若启用建议同时将 Authelia 侧require_pkce设为true或设置pkce_challenge_method: S256。typeoidc提供方协议类型。discoveryUrlhttps://auth.example.com/.well-known/openid-configurationAuthelia 的 OpenID Connect Discovery 端点Papra 通过它自动发现授权、Token、UserInfo、JWKS 等端点。scopes[openid, profile, email]请求的作用域与 Authelia 侧scopes对应。注意两个示例的差异Docker Compose 版本显式加入了pkce: true而.env版本未包含该字段。是否启用 PKCE 属于安全加固项建议统一为启用状态并与 Authelia 侧配置对齐。Discovery 端点说明Authelia 作为 OpenID Connect 1.0 Provider实现了 OpenID Connect Discovery 1.0其发现端点路径为https://auth.example.com/.well-known/openid-configurationhttps://auth.example.com/.well-known/oauth-authorization-serverOAuth 2.0 Authorization Server MetadataRFC8414这两个端点会返回授权端点/api/oidc/authorization、Token 端点/api/oidc/token、UserInfo 端点/api/oidc/userinfo、jwks_uri等元数据具体端点清单见 OpenID Connect 1.0 集成介绍。在 Authelia 源码中发现与元数据端点的处理实现位于 internal/handlers/handler_oauth2_oidc_wellknown.go 与 internal/handlers/handler_oauth2_wellknown.go。建议无论使用哪个版本都让 Papra 通过 Discovery 端点自动获取端点地址以保证 URL 始终正确。配置核对与常见问题完成两端配置并重启服务后可通过以下要点核对集成是否正常回调地址精确匹配Papra 的回调地址https://papra.example.com/api/auth/oauth2/callback/authelia必须逐字符出现在 Authelia 的redirect_uris中大小写敏感、scheme 必须为http或https。否则授权请求会直接失败。密钥一致性与哈希工作因子Authelia 侧client_secret存的是明文insecure_secret的 PBKDF2 哈希Papra 侧必须填写明文。若客户端请求频繁超时可能是哈希工作因子迭代次数过高所致可通过time authelia crypto hash generate pbkdf2 --variant sha512 --iterations 310000 --password insecure_password评估耗时并适当调低详见 常见问题文档。凭据转义client_secret_post认证要求客户端 ID 与密钥按规范进行 URL 编码若你自定义的 ID/密钥包含特殊字符而 Papra 未正确转义会出现“凭据正确却认证失败”的现象建议直接使用--charset rfc3986生成的随机值规避。Provider 必填项identity_providers.oidc下的hmac_secret、jwks至少一个 RS256 密钥等全局配置缺失时整个 OIDC 模块无法工作配置结构可对照 config.template.yml 检查。认证强度示例将authorization_policy设为two_factor用户登录 Papra 时将被要求完成第二因素认证如需放行内部网络可改用自定义 authorization policy 实现差异化策略。相关文档Papra 集成文档本文依据OpenID Connect 1.0 Clients 配置参考OpenID Connect 1.0 Provider 配置参考OpenID Connect 1.0 集成介绍与端点清单OpenID Connect 1.0 常见问题密钥生成与调优OpenID Connect 1.0 Claims 与作用域定义通用 OIDC 客户端注册须知oidc-common 模板源码【免费下载链接】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），仅供参考