💬 ชาวเน็ตแห่แชร์: gitblog /article/details/ - สรุปดราม่าล่าสุด

Authelia 隐私政策（Privacy Policy）配置指南：启用链接展示与用户接受确认

【免费下载链接】authelia The Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready. 项目地址: https://gitcode.com/GitHub_Trending/au/authelia

导读

Authelia 内置了隐私政策展示能力，允许管理员通过配置一个全局的 privacy_policy 配置段，在前端界面显示隐私政策链接，并可强制用户在首次使用前于页面底部的抽屉式（Drawer）对话框中确认已阅读并接受政策。本文以官方文档 privacy-policy.md 为主体，结合仓库中对应的配置 Schema、启动期校验器与前端组件实现，完整讲解三个配置项的含义、约束、前后端行为链路以及 GDPR 合规场景下的注意事项，帮助读者在自建 Authelia 部署中正确启用该功能。

功能定位：Authelia 如何呈现隐私政策

从官方文档的定义看，privacy_policy 配置段用于控制两类前端行为：

显示隐私政策链接：在前端页面（如登录页、设置页）展示指向管理员隐私政策文档的链接；
强制用户接受：要求用户以浏览器为单位，在页面底部的 Dialog Drawer 中确认接受政策，接受状态记录并保存在浏览器的 localStorage 中；未接受前用户无法正常与 Authelia UI 交互。

该功能对需要遵守 GDPR）。

完整配置示例

官方文档给出的最小配置段如下（enabled 为 false 时的默认形态）：

privacy_policy:
  enabled: false
  require_user_acceptance: false
  policy_url: ''

启用后的推荐配置示例（假设域名为 example.com）：

privacy_policy:
  enabled: true
  policy_url: 'https://www.example.com/privacy-policy'

完整的注释版配置同样可以在 internal/configuration/config.template.yml 中找到，字段与官方文档一一对应。

配置选项详解

enabled

类型：boolean
默认值：false
是否必填：否

启用隐私政策链接的显示。当该选项为 true 时，前端会读取配置的 policy_url 并将链接渲染到界面中（具体实现见下文"前端行为链路"一节）。

require_user_acceptance

类型：boolean
默认值：false
是否必填：否

要求用户以**每浏览器（per-browser）**为单位接受隐私政策。接受行为通过页面底部的一个 Dialog Drawer 完成，用户点击"Accept"后，接受状态被写入浏览器 localStorage（键名为 privacy-policy.accepted，定义见 web/src/constants/LocalStorage.ts）。

官方文档明确说明了两点行为约束：

接受状态仅记录于浏览器本地，通过 localStorage 保存与检查，不写入 Authelia 服务端存储；
未接受政策前，用户不应能通过常规方式与 Authelia UI 交互。

提示：require_user_acceptance 依赖 enabled 生效，实际渲染条件为"启用隐私政策"且"要求接受"且"本地尚未接受"（见 web/src/components/PrivacyPolicyDrawer.tsx）。

policy_url

类型：string
是否必填：条件必填（当 enabled 为 true 时必须提供）

隐私政策文档的 URL。前端将其作为链接地址展示给用户，方便管理员引导用户查看自己部署的隐私政策全文。官方文档给出的使用约束非常严格：

必须是绝对 URL（absolute URL）；
scheme 必须为 https://；
当 enabled 为 true 时，该选项必须提供，否则配置校验失败。

启动期校验：源码级的强制约束

文档中"必须是绝对 URL、必须使用 https:// scheme、启用时必须提供"这三条规则，在仓库的配置校验器中得到了精确落实。

配置的 Schema 结构体定义在 internal/configuration/schema/privacy_policy.go，其中 PolicyURL 字段的类型为 *url.URL（Go 标准库的 net/url），这意味着配置解析阶段就会将字符串解析为 URL 结构，无法被解析为 URL 的字符串在更早的阶段就会被拒绝。

真正的业务校验逻辑位于 internal/configuration/validator/privacy_policy.go 的 ValidatePrivacyPolicy 函数，其核心逻辑为：

if !config.Enabled {
    return
}

switch config.PolicyURL {
case nil:
    validator.Push(errors.New(errPrivacyPolicyEnabledWithoutURL))
default:
    if config.PolicyURL.Scheme != schemeHTTPS {
        validator.Push(fmt.Errorf(errFmtPrivacyPolicyURLNotHTTPS, config.PolicyURL.Scheme))
    }
}

对应两条错误信息定义在 internal/configuration/validator/const.go：

privacy_policy: option 'policy_url' must be provided when the option 'enabled' is true（启用但未提供 URL）；
privacy_policy: option 'policy_url' must have the 'https' scheme but it's configured as '%s'（URL scheme 不是 https）。

这些规则同样被单元测试覆盖（见 internal/configuration/validator/privacy_policy_test.go），测试用例包括：默认空配置合法、启用且 URL 合法、启用且要求接受且 URL 合法、http scheme 报错、启用但缺失 URL 报错。其中 http://example.com/privacy 会触发 scheme 错误，Enabled: true 而无 URL 会触发缺失错误——与文档描述完全一致。

前端行为链路：链接与接受抽屉的实现

当配置生效后，前端通过服务端注入的页面内嵌变量（embedded variable）读取配置值。读取函数位于 web/src/utils/Configuration.ts：

getPrivacyPolicyEnabled()：判断 privacypolicyurl 内嵌变量非空；
getPrivacyPolicyURL()：返回 privacypolicyurl 内嵌变量；
getPrivacyPolicyRequireAccept()：判断 privacypolicyaccept 内嵌变量是否为 "true"。

由此可以看出，enabled 本质上是"policy_url 是否非空"在前端的等价表达，服务端会在渲染页面时将配置值注入到 data-* 属性中。

链接组件 PrivacyPolicyLink

web/src/components/PrivacyPolicyLink.tsx 是一个简单的 <a> 链接组件，读取配置的 policy_url 并渲染为"Privacy Policy"文本，同时设置了 target="_blank" 与 rel="noopener noreferrer"，确保隐私政策在新标签页打开且不泄露 window.opener 引用。

接受抽屉 PrivacyPolicyDrawer

web/src/components/PrivacyPolicyDrawer.tsx 实现了文档所述的 Dialog Drawer：当 privacyEnabled && privacyRequireAccept && !accepted 时，从页面底部弹出一个 Sheet（side="bottom"），展示文案"You must view and accept the Privacy Policy before using Authelia"（其中隐私政策一词渲染为可点击链接），并提供一个"Accept"按钮。点击 Accept 后通过 usePersistentStorageValue 将 privacy-policy.accepted 写入 localStorage，抽屉随之关闭。该组件挂在最小化布局（MinimalLayout）等页面布局上，与文档"记录并检查于浏览器 localStorage"的描述一一对应。

GDPR 合规注意事项：implicit 授权模式的风险

官方文档对需要遵守 GDPR 或其他隐私法律的管理员给出了明确的警示，这是本配置章节中最需要理解的部分：

若 OpenID Connect 1.0 客户端（见 OpenID Connect 提供方文档）配置了 implicit 授权模式（consent mode），且用户已经通过认证，那么用户可能不会经过 Authelia UI 的展示流程，从而不会触发隐私政策接受抽屉；
项目方明确表示不会为 implicit 模式添加此类检查：一方面该模式本身就不太可能满足 GDPR 等法律要求，另一方面该模式也并非严格符合 OpenID Connect 1.0 规范；
因此官方建议：如果启用了 require_user_acceptance，管理员应避免使用 implicit 授权模式，或自行承担相应风险。

这一警示提醒我们：隐私政策接受机制只覆盖"经过 Authelia 前端 UI"的流程，无法覆盖所有认证路径，合规工作不能仅依赖该配置项。

实操建议与配置检查清单

结合文档与源码，给出启用该功能的完整检查清单：

准备隐私政策页面：托管一份隐私政策文档，记录绝对 HTTPS 地址，例如 https://www.example.com/privacy-policy；
配置 privacy_policy 段：将 enabled 设为 true 并填写 policy_url；若需强制接受，再设置 require_user_acceptance: true；
检查启动日志：若 enabled 为 true 但缺少 policy_url，或 policy_url 不是 https:// scheme，Authelia 会在启动期报出校验错误并拒绝启动（错误信息见上文"启动期校验"一节），请据此修正配置；
验证前端表现：以全新浏览器（或清除 localStorage 后）访问 Authelia 页面，确认底部出现隐私政策接受抽屉，点击链接可跳转至政策页，点击 Accept 后抽屉消失且可正常使用 UI；
审计 OIDC 客户端：若部署了 OIDC 且启用 require_user_acceptance，逐项检查各客户端的授权模式，避免使用 implicit 模式造成合规缺口。

关键参考文件

官方配置文档：docs/content/configuration/miscellaneous/privacy-policy.md
配置模板（含注释版字段说明）：internal/configuration/config.template.yml
Schema 定义：internal/configuration/schema/privacy_policy.go
启动期校验器：internal/configuration/validator/privacy_policy.go
校验器测试：internal/configuration/validator/privacy_policy_test.go
前端接受抽屉组件：web/src/components/PrivacyPolicyDrawer.tsx
前端链接组件：web/src/components/PrivacyPolicyLink.tsx
localStorage 键名定义：web/src/constants/LocalStorage.ts
前端配置读取函数：web/src/utils/Configuration.ts

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考