企业官网建设流程全解析

使用 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），以及客户端密钥哈希、作用域、回调地址等关键参数的底层含义与排障思路。

测试版本与适用范围

原文档记录的测试版本如下：

Papra 是社区维护的自托管文档管理与发布平台，本集成属于community（社区）级别支持，意味着该配置由社区验证并提供示例，并不代表 Papra 官方与 Authelia 存在联合保障。在将示例投入生产前，建议在目标版本上重新验证。

开始之前：注册客户端的通用须知

本指南嵌入的{{% oidc-common %}}通用片段（其模板实现位于 docs/layouts/_shortcodes/oidc-common.html）强调了几条适用于所有OpenID Connect 1.0 客户端注册的关键约束，配置前务必阅读：

1. client_id必须全局唯一。示例中的papra仅为可读性而设，生产环境应使用随机生成的值，长度建议 64 个随机字符（不得超过 100 字符），且只能包含 RFC3986 Unreserved Characters（大小写字母、数字以及-、.、_、~）。
2. client_secret必须与 Papra 中配置的明文值完全一致。Authelia 配置文件中强烈建议存储该密钥的哈希值而非明文（明文存储已被正式弃用）。同时要注意：哈希计算的工作因子过高可能导致客户端请求超时，相关调优方法见 常见问题文档。
3. 下方的 Authelia 配置示例只包含客户端注册片段，你还必须按照 OpenID Connect 1.0 Provider 配置 文档补齐identity_providers.oidc下的issuer_private_keys（即jwks，其中至少需要一个 RS256 密钥）、hmac_secret等必需项；这些必选项同样体现在 config.template.yml 的模板注释中。
4. 示例仅展示了客户端可用配置项的一小部分，完整选项清单请查阅 OpenID Connect 1.0 Clients 配置。

如何生成安全的 Client ID 与 Client Secret

参考 How do I generate a client identifier or client secret?，可使用 Authelia 自带的 CLI 命令生成随机值并直接产出 PBKDF2 哈希：

# 生成 72 字符的随机 Client ID（Docker 部署时加 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，实际部署请替换为你的真实域名）：

提示：文档站点支持通过 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_id）：Papra，用于在 Authelia 的授权/同意页面等 UI 中展示的友好名称。
• client_secret（机密型客户端必填）：上例中的$pbkdf2-sha512$...是明文insecure_secret的 PBKDF2-SHA512 哈希（310000 次迭代）。Authelia 在收到客户端请求时会执行哈希运算进行比对，因此哈希值存储不会影响客户端使用明文密钥。不推荐在配置中写明文（$plaintext$前缀形式已被弃用）。
• public（默认false）：Papra 属于服务端应用，能够安全保管客户端凭据，因此使用机密型客户端（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设为true；pkce_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 判定为不安全并拒绝授权。
• scopes：openid、profile、email。各作用域对应的默认声明位置（ID Token 还是 UserInfo 端点）可参考 OpenID Connect 1.0 Claims 与作用域定义。openid是 OIDC 必需作用域，profile提供用户名等资料声明，email提供邮箱声明，三者与 Papra 端scopes数组一一对应。
• response_types：code，即标准的授权码流程（Authorization Code Flow），是官方推荐的最安全响应类型，对应 OAuth 2.0 授权码授权。
• grant_types：authorization_code，与response_types: ['code']配套。默认即为该值，未配置其他授权类型时可不显式声明。
• access_token_signed_response_alg/userinfo_signed_response_alg（默认none）：none表示 Access Token 与 UserInfo 响应均以不透明/JSON 形式返回，不启用 RFC9068 JWT Profile 或 JWT 签名的 UserInfo。绝大多数客户端默认仅支持none。
• token_endpoint_auth_method：client_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 字段含义

注意两个示例的差异：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-configuration
• https://auth.example.com/.well-known/oauth-authorization-server（OAuth 2.0 Authorization Server Metadata，RFC8414）

这两个端点会返回授权端点/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 始终正确。

配置核对与常见问题

完成两端配置并重启服务后，可通过以下要点核对集成是否正常：

1. 回调地址精确匹配：Papra 的回调地址https://papra.example.com/api/auth/oauth2/callback/authelia必须逐字符出现在 Authelia 的redirect_uris中（大小写敏感、scheme 必须为http或https）。否则授权请求会直接失败。
2. 密钥一致性与哈希工作因子：Authelia 侧client_secret存的是明文insecure_secret的 PBKDF2 哈希，Papra 侧必须填写明文。若客户端请求频繁超时，可能是哈希工作因子（迭代次数）过高所致，可通过time authelia crypto hash generate pbkdf2 --variant sha512 --iterations 310000 --password insecure_password评估耗时并适当调低（详见 常见问题文档）。
3. 凭据转义：client_secret_post认证要求客户端 ID 与密钥按规范进行 URL 编码；若你自定义的 ID/密钥包含特殊字符而 Papra 未正确转义，会出现“凭据正确却认证失败”的现象，建议直接使用--charset rfc3986生成的随机值规避。
4. Provider 必填项：identity_providers.oidc下的hmac_secret、jwks（至少一个 RS256 密钥）等全局配置缺失时，整个 OIDC 模块无法工作，配置结构可对照 config.template.yml 检查。
5. 认证强度：示例将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