Authelia 基于时间的一次性密码TOTP二次因素配置全指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 采用基于时间的一次性密码算法Time-Based One-Time Password AlgorithmTOTP[RFC6238]作为可选的二次认证2FA手段它是基于 HMAC 的一次性密码算法HOTP[RFC4226]的扩展。本文以官方配置文档为骨架结合当前仓库中的配置 Schema、校验器与处理器源码完整讲解totp配置段下的每一个参数、默认值与合法取值范围并深入剖析注册、校验、防重放、数据库加密等底层机制帮助你在生产环境中安全、兼容地部署 TOTP 二次因素。TOTP 在 Authelia 中的定位TOTP 属于 Authelia 第二因素Second Factor体系中的一种方法与 WebAuthnPasskey、Duo Push 并列。用户启用后登录流程变为先通过用户名密码完成第一因素认证再输入由 Authenticator 应用如 Google Authenticator、Bitwarden、1Password 等生成的 6 位动态验证码完成第二因素认证。Authelia 的默认配置参数是为了最大兼容性而选择的许多 Authenticator 应用只支持 6 位数字并且只支持 SHA1 算法。因此在调整任何与生成算法相关的参数前务必先确认你的用户群体所使用的应用是否支持对应选项。完整配置示例以下是一份完整的totp配置段位于主配置文件configuration.yml中包含了当前版本支持的全部配置项及其默认值totp: disable: false issuer: authelia.com algorithm: sha1 digits: 6 period: 30 skew: 1 secret_size: 32 allowed_algorithms: - SHA1 allowed_digits: - 6 allowed_periods: - 30 disable_reuse_security_policy: false其中issuer一项请替换为你自己的域名或服务标识。下面逐项说明每个配置选项的含义、默认值与校验规则。配置选项详解disable类型boolean默认值false是否必填否设置为true时完全禁用一次性密码TOTP二次因素功能。在源码层面当disable为true时配置校验器会直接跳过 TOTP 配置的校验与默认值填充见 internal/configuration/validator/totp.go 中的ValidateTOTP函数。issuer类型string默认值Authelia是否必填否生成一次性密码的 Authenticator 应用通常会显示一个 issuer签发者用于区分用户注册的多个不同服务。Authelia 允许自定义 issuer使 Authelia 创建的条目与其他应用区分开。从源码看issuer 会被写入生成的 otpauth URI 与二维码中并持久化到数据库。在 internal/totp/totp.go 的GenerateCustom方法中Issuer作为totp.GenerateOpts的一部分传入同时在 internal/configuration/schema/totp.go 的DefaultTOTPConfiguration中默认 issuer 为Authelia。algorithm类型string默认值sha1是否必填否合法取值不区分大小写sha1、sha256、sha512algorithm指定生成 TOTP 密钥所使用的 HMAC 哈希算法。需要注意重要提醒很多 TOTP 应用不支持该选项。强烈建议你先了解用户使用的应用并逐一测试后再修改此选项。仅仅验证应用能否添加密钥是不够的还必须验证它能否用 Authelia 完成实际认证——因为有些应用会静默忽略这些参数。已测试应用清单参见 TOTP 应用参考指南。修改该值只影响新注册的 TOTP 密钥详见下文 注册机制 一节。源码层面校验器会将该值统一转为大写并与SHA1/SHA256/SHA512白名单比对非法值会直接报错例如配置为sha3时会得到错误totp: option algorithm must be one of SHA1, SHA256, or SHA512 but its configured as SHA3参见 internal/configuration/validator/totp.go 与对应测试用例 internal/configuration/validator/totp_test.go。digits类型integer默认值6是否必填否合法取值6或8digits表示用户执行认证时需要输入的数字位数。一般不建议修改因为很多 TOTP 应用只支持 6 位更糟的是部分应用虽然允许添加密钥却不会按密钥指定的位数生成验证码。重要提醒部分 TOTP 应用不支持该选项修改前务必测试用户的常用应用能否真正完成认证参见 TOTP 应用参考指南。校验器对digits有严格限制只接受6或8配置为其他值如20会得到错误totp: option digits must be 6 or 8 but its configured as 20参见 internal/configuration/validator/totp.go。period类型integer默认值30是否必填否最小值15period是两次密钥轮换之间的时间间隔秒即 TOTP 算法中的时间步长time step。它与skew共同决定验证码的有效时长相互作用关系见下文 输入校验 一节。官方建议保持30秒最小值为15。校验器会在period 15时报错totp: option period option must be 15 or more but its configured as 5。注意修改period只影响新注册的密钥。skew类型integer默认值1是否必填否skew表示当前有效验证码前后各多少个时间步长内的验证码也一并视为有效。默认值1意味着有 3 个验证码同时有效当前步长前后各 1 个设置为2则同时有效 5 个。以默认period30计算分别对应 90 秒和 150 秒的有效窗口。与前面几个参数不同修改skew会影响所有 TOTP 校验而不仅仅是新注册的密钥。在源码中skew 被保存在 provider 实例上而非数据库中的密钥配置里见 internal/totp/totp.go 与 internal/totp/totp.go 的Validate方法——校验时Skew直接取自运行时的 provider 配置。secret_size类型integer默认值32是否必填否最小值20secret_size是生成的共享密钥shared secret的字节长度。最小值是 20 字节160 位默认 32 字节256 位。大多数场景下 32 字节已经足够不过有些 Authenticator 对超过最小值的密钥可能存在兼容性问题。说明RFC4226HOTP推荐的最小值是 20 字节而规范在技术层面允许低至 16 字节128 位。Authelia 选择了更保守的 20 字节作为下限参见 internal/configuration/schema/totp.go 中SecretSize的minimum20约束以及 internal/configuration/validator/totp.go 中对小于 20 的配置直接报错的逻辑。allowed_algorithms类型list(string)默认值SHA1是否必填否与algorithm类似但该选项的作用是允许用户在注册 TOTP 设备时从该列表中自行选择算法在 Web 界面注册流程中。该列表始终会包含algorithm选项配置的值——即使你未在列表中显式写出校验器也会自动追加见 internal/configuration/validator/totp.go。allowed_digits类型list(integer)默认值6是否必填否与digits类似允许用户在注册时从列表中自行选择位数6或8。列表始终会包含digits配置的值校验器会保证默认值一定在允许列表中见 internal/configuration/validator/totp.go。allowed_periods类型list(integer)默认值30是否必填否与period类似允许用户在注册时从列表中自行选择时间步长每个值必须 ≥ 15。列表始终会包含period配置的值。disable_reuse_security_policy类型boolean默认值false是否必填否设置为true时禁用防止 TOTP 验证码重放的安全策略。该策略是一项额外的安全措施在验证码的有效窗口期内同一个验证码即同一个时间步长 step不允许被使用两次。源码中该策略在登录处理器中落地在 internal/handlers/handler_sign_totp.go 处调用ctx.Providers.TOTP.Validate完成密码学校验后若发现同一 step 已被使用过会依据ctx.Configuration.TOTP.DisableReuseSecurityPolicy决定是仅记录警告还是直接拒绝认证internal/handlers/handler_sign_totp.go。配合 internal/model/totp_configuration.go 中的UpdateSignInInfo方法更新最近使用时间从而实现防重放。该策略只会影响在有效期内被使用超过一次的验证码正常的一次性使用不受影响一般无需关闭。注册机制Registration当用户首次注册 TOTP 设备时Authelia 会使用当前的issuer、algorithm、digits、period等配置生成 TOTP 链接otpauth URI和二维码并将这些值一并保存到数据库中供后续校验使用。这意味着之后即使修改了配置项已注册用户的密钥也不会失效、无需重新注册。该功能自 4.33.0 版本起生效在此之前的版本中修改配置会导致旧密钥校验失败。如果你希望强制某用户重新注册设备无论是否修改了配置都可以使用以下命令删除该用户的旧设备authelia storage user totp delete username从源码看注册流程由 internal/handlers/handler_register_totp.go 中的两个处理器实现TOTPRegisterGET返回当前允许的注册选项算法、位数、时间步长的可选列表数据来自ctx.Providers.TOTP.Options()internal/handlers/handler_register_totp.go对应 internal/totp/totp.go 的Options方法其内部即NewTOTPOptionsFromSchema从配置映射出的TOTPOptionsinternal/totp/totp.go。TOTPRegisterPUT接收用户在允许列表中选定的参数调用GenerateCustom生成新的 TOTP 配置并入库。GenerateCustominternal/totp/totp.go内部通过totp.Generate生成密钥秘密字节使用secret_size指定长度、经 Base32 无填充编码连同Issuer、AccountName用户名、Period、Digits、Algorithm一起构成 otpauth URI 与二维码。输入校验Input Validationperiod与skew两个参数会互相影响共同决定验证码的有效时长。默认值组合为period30、skew1官方强烈建议不要修改这两个参数除非你确实想将skew设为0。它们通过改变验证码的有效时间窗来影响安全性。有效时长的计算公式为有效时长 period (period × skew × 2)例如periodskew有效时长同时有效的验证码数30190 秒3302150 秒5需要说明的是虽然增大skew可以缓解客户端与服务端之间的时间偏差问题但同时也拉长了验证码的可重放窗口安全性随之下降。这也是默认skew1且建议不要随意调大的原因。系统时间准确性System Time AccuracyTOTP 是基于时间的算法因此服务器与客户端两侧的时间准确性都至关重要如果服务器系统时间不够精确客户端生成的验证码将看起来永远不正确反之亦然客户端时间偏差同样会导致校验失败。Authelia 默认在启动时会将系统时间与 NTP 服务器 进行比对相关配置见ntp配置段帮助规避服务器侧的时间同步问题。但对于客户端目前没有有效且可靠的手段进行检查——这也是skew参数存在的意义之一在合理范围内容忍轻微的时钟偏差。加密与密钥导出Encryption自4.33.0版本起TOTP 密钥在数据库中以加密形式存储加密密钥相关说明见 存储层介绍。这样即使攻击者获得了数据库的完全访问权限也无法轻易破解你的二次认证机制。但加密存储也给将 TOTP 密钥从 Authelia 迁移导出到其他服务带来了不便。为此 Authelia 提供了专门的 TOTP 导出命令这些命令要求提供完整配置或至少包含存储后端连接信息与加密密钥的最小配置# 导出为 YAML 文件默认文件名 authelia.export.totp.yml authelia storage user totp export --file example.yml # 导出为 CSV authelia storage user totp export csv --file users.csv # 导出为 otpauth URI 列表 authelia storage user totp export uri # 导出为二维码 PNG 图片输出到指定目录 authelia storage user totp export png --directory example/dir对应的命令实现与更多示例位于 internal/commands/storage.go 以及 internal/commands/const.go。完整的 CLI 文档参见 authelia storage user totp export。此外命令还支持为指定用户生成TOTP 密钥可用于预置用户或测试authelia storage user totp generate john authelia storage user totp generate john --period 90 authelia storage user totp generate john --digits 8 authelia storage user totp generate john --algorithm SHA512 --config config.yml authelia storage user totp generate john --algorithm SHA512 --config config.yml --path john.png以及导入已导出的 TOTP 配置authelia storage user totp import authelia.export.totp.yml authelia storage user totp import --config config.yml authelia.export.totp.yml导出/导入的数据结构定义在 internal/model/totp_configuration.goTOTPConfigurationDataExport以totp_configurations为顶层键承载配置列表每条配置包含算法、位数、周期、issuer、用户名、Base32 密钥等字段。校验流程与 Provider 实现综合来看TOTP 的运行时核心是 internal/totp/totp.go 中的TimeBased结构体它实现了 internal/totp/provider.go 定义的Provider接口Generate、GenerateCustom、Validate、Options初始化NewTimeBasedProvider从配置构造 provider读取 issuer、默认算法、默认位数、默认周期、secret_size并在skew 0时采用配置值、否则回退为1internal/totp/totp.go。生成Generate/GenerateCustom依据用户选择或默认的算法、位数、周期生成密钥与 URI。校验Validate使用数据库中保存的Period、Digits、Algorithm而非当前配置执行totp.ValidateCustomStepskew 则取运行时配置internal/totp/totp.go。这正是修改算法/位数/周期不影响已注册密钥、而修改 skew 影响所有校验这一行为差异的根源。配置层则遵循Schema 定义默认值 → 校验器填充与纠错的两段式处理默认配置定义在 internal/configuration/schema/totp.go校验与归一化逻辑见 internal/configuration/validator/totp.go覆盖算法大写归一化、period 最小值、digits 合法值、secret_size 下限、allowed 列表自动包含默认值等规则并通过 internal/configuration/validator/totp_test.go 中的表驱动测试逐一验证。最佳实践小结保持默认参数algorithm: sha1、digits: 6、period: 30、skew: 1是为了最大兼容性而选择的默认值绝大多数 Authenticator 应用都支持该组合。修改生成参数前先测试如果必须修改算法或位数务必确认用户使用的应用能真正完成认证而非仅仅能添加密钥参考已测试应用清单 TOTP 应用参考指南。保持系统时间准确启用 NTP 同步避免服务器时钟漂移导致验证码大面积失效相关配置见 NTP 文档。不要轻易关闭防重放策略disable_reuse_security_policy保持默认false以阻止验证码在有效窗口内被重放。善用导出命令需要迁移或备份 TOTP 密钥时使用authelia storage user totp export系列命令并妥善保管加密密钥。【免费下载链接】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），仅供参考