尧图网站建设 
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/authelia本篇技术指南以 Authelia 官方集成参考文档 time-based-one-time-password-apps.md 为主体系统梳理 Authelia 所支持的 TOTP 可调参数、已实测的 TOTP 客户端应用兼容性矩阵并结合仓库源码schema/totp.go、internal/totp/totp.go讲解从配置到密钥生成与校验的底层原理。读完本文你将能判断用户常用的验证器 App 是否与你的 TOTP 策略兼容并据此安全地调整 Authelia 的totp配置段。TOTP 在 Authelia 中的定位Authelia 所采用的 OTP 方法是基于时间的一次性密码算法TOTP[RFC6238]它是基于 HMAC 的一次性密码算法HOTP[RFC4226]的时间扩展。用户将 Authelia 生成的密钥录入任意 TOTP 验证器应用后在登录时输入当前时间窗口内生成的动态验证码即可完成第二因素2FA认证。与部分只支持固定参数的 2FA 方案不同Authelia 对 TOTP 提供了宽泛wide variety的可调设置空间算法SHA1/SHA256/SHA512、验证码位数6/8、时间周期、允许误差skew、密钥长度等均可配置。但宽泛的配置能力并不意味着每个客户端应用都支持这正是官方维护这份集成参考矩阵的核心原因。Authelia 的 TOTP 可调设置总览在 configuration.yml 中TOTP 相关的配置段为totp完整示例参见官方配置文档 time-based-one-time-password.mdtotp: 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各参数的含义与默认值如下表默认值来源于 schema/totp.go 中的DefaultTOTPConfiguration与 JSON Schema 注解一致配置项默认值可选值说明disablefalsetrue/false设为true时整体禁用 TOTP 第二因素功能issuerAuthelia任意字符串生成 TOTP 密钥时写入的发行方标识验证器应用通常用它区分用户注册的不同服务条目algorithmsha1sha1/sha256/sha512大小写不敏感生成 TOTP 密钥时使用的 HMAC 算法digits66/8用户认证时需要输入的验证码位数period30正整数TOTP 码的有效时间窗口秒skew1非负整数允许的时间窗口误差数量1表示前后各允许 1 个周期secret_size32最小值20生成密钥的字节长度allowed_algorithms[SHA1]SHA1/SHA256/SHA512除默认算法外允许用户选择的算法列表allowed_digits[6]6/8除默认位数外允许用户选择的位数列表allowed_periods[30]正整数除默认周期外允许用户选择的周期列表disable_reuse_security_policyfalsetrue/false是否禁用禁止重复使用同一验证码的安全策略从源码实现看schema/totp.go 将默认配置定义为var DefaultTOTPConfiguration TOTP{ Issuer: Authelia, DefaultAlgorithm: TOTPAlgorithmSHA1, DefaultDigits: 6, DefaultPeriod: 30, Skew: defaultTOTPSkew, SecretSize: TOTPSecretSizeDefault, AllowedAlgorithms: []string{TOTPAlgorithmSHA1}, AllowedDigits: []int{6}, AllowedPeriods: []int{30}, }相关常量定义在 const.go 中算法枚举为TOTPAlgorithmSHA1、TOTPAlgorithmSHA256、TOTPAlgorithmSHA512密钥大小默认值TOTPSecretSizeDefault 32最小值TOTPSecretSizeMinimum 20。兼容性矩阵已测试的 TOTP 应用官方参考文档 time-based-one-time-password-apps.md 的核心内容是一张应用 × 算法 × 位数的兼容性矩阵。该矩阵并非手工硬编码在文档里而是由数据文件 support.json 驱动、经 table-totp-support.html 短代码渲染生成的表格其中✓表示该应用支持对应选项✗表示不支持。完整兼容性矩阵应用SHA1SHA256SHA5126 位8 位Google Authenticator✓✗✗✓✗Bitwarden✓✓✓✓✓Yubico Authenticator✓✗✗✓✓Authenticator Plus✓✗✗✓✗1Password✓✓✗✓✗Ravio✓✓✗✓✗Authy✓✗✗✗✓Aegis✓✓✓✓✓Okta Verify✓✗✗✓✗逐应用解读Google Authenticator最普及的验证器之一仅支持 SHA1 算法与 6 位验证码不支持 SHA256/SHA512 和 8 位。若你的用户群体大量使用 Google Authenticator则不应更改默认算法与位数。Bitwarden兼容性最好的应用之一三种算法SHA1/SHA256/SHA512与两种位数6/8全部支持适合作为默认推荐应用。Yubico Authenticator算法上仅支持 SHA1但位数同时支持 6 位和 8 位。Authenticator Plus仅支持 SHA1 与 6 位。1Password支持 SHA1/SHA256不支持 SHA512位数仅支持 6 位。Ravio与 1Password 相同的算法支持范围SHA1/SHA256位数仅支持 6 位。Authy矩阵中较为特殊的一个——算法仅支持 SHA1且位数仅支持8 位而非常见的 6 位。这意味着使用 Authy 的用户可能无法使用默认的 6 位 TOTP 配置反之亦然。Aegis与 Bitwarden 一样算法与位数全部支持是功能覆盖最完整的开源验证器之一。Okta Verify仅支持 SHA1 与 6 位。矩阵的使用边界官方文档对这张矩阵给出了重要限定原文要点矩阵是已经过测试且可用tested that work的应用集合不应假设列表中某应用的信息对其当前版本仍然准确——应用可能已支持此前不支持的选项在少数情况下也可能支持得比以前更少因此在调整任何 TOTP 选项前务必以实际部署版本为准进行验证。为什么兼容性如此重要静默忽略选项问题Authelia 默认配置刻意选择兼容性优先的取值原因在配置文档 time-based-one-time-password.md 中表述得非常明确许多应用不支持 6 位以外的位数且很多只支持 SHA1。更关键的风险是部分 TOTP 应用允许用户成功添加密钥但在生成验证码时静默忽略密钥中声明的位数或算法导致能录入、不能认证的假成功现象。因此官方反复强调仅测试应用能否添加密钥是不够的必须完整走一遍认证流程确认应用生成并提交的验证码能被 Authelia 正确校验变更algorithm、digits、period等选项前应先确认你的用户实际使用的验证器应用并对它们逐一测试可以结合本文的兼容性矩阵time-based-one-time-password-apps.md圈定候选应用范围。源码级原理从配置到密钥生成与验证了解设置项如何影响实际行为有助于你做出正确的配置决策。Authelia 的 TOTP 能力集中在 internal/totp/totp.go 中底层基于github.com/authelia/otp库实现。配置到 Provider 的映射NewTimeBasedProvider将schema.TOTP配置转换为生产环境的TimeBasedProvidertotp.goprovider TimeBased{ opts: NewTOTPOptionsFromSchema(config), issuer: config.Issuer, algorithm: config.DefaultAlgorithm, digits: uint32(config.DefaultDigits), period: uint(config.DefaultPeriod), size: uint(config.SecretSize), } if config.Skew ! nil *config.Skew 0 { provider.skew uint(*config.Skew) } else { provider.skew 1 }可以看到skew的兜底逻辑当配置缺失或为负值时回退为1。同时NewTOTPOptionsFromSchema会把allowed_algorithms/allowed_digits/allowed_periods组装成model.TOTPOptions供注册流程中向用户展示可选范围。密钥生成Generate / GenerateCustomGenerate使用默认参数生成密钥GenerateCustom则支持逐项覆盖totp.go。关键实现细节若显式传入secret会先按Base32 无填充NoPadding标准解码校验解码失败即返回错误error decoding base32 string调用totp.Generate时注入Issuer、AccountName即用户名、Period、SecretSize、Digits、Algorithm并使用ctx.GetRandom()提供的加密安全随机源生成的model.TOTPConfiguration会记录CreatedAt、Username、Issuer、Algorithm、Digits、Secret、Period其中Secret为 Base32 编码的密钥文本。验证码校验ValidateValidate从已保存的配置中读取Period、Digits、Algorithm结合 Provider 的skew构造totp.ValidateOpts最终调用totp.ValidateCustomStep并以ctx.GetClock().Now().UTC()作为当前时间基准totp.go。这意味着校验时使用的是密钥登记时固化的算法、位数与周期而不是当前全局默认值——这正是更改默认值只影响新注册的密钥这一行为的来源skew决定允许的时间漂移窗口客户端与服务器时钟偏差较大时适当增大skew可减少认证失败但也会扩大暴力破解窗口。注册流程与仅影响新密钥的语义配置文档明确指出修改algorithm、digits、period、secret_size等选项仅影响新注册的 TOTP 密钥已存在的密钥配置在生成时即已固化于存储中。因此调整默认值不会破坏存量用户的认证但也不会自动升级他们的密钥安全强度——如需让存量用户享受新参数需要引导他们重新注册 TOTP。实操建议为你的用户群选择安全的 TOTP 策略结合兼容性矩阵与源码行为可以给出以下落地建议保持默认值起步sha1 6 位 30 秒周期 skew 1 是兼容性最优组合覆盖矩阵中全部 9 款已测试应用唯一例外是 Authy 仅支持 8 位。若用户使用 Authy需评估位数不匹配带来的影响。如要增强安全性优先考虑将算法提升为sha256。此时应确认用户应用支持矩阵显示只有 Bitwarden、1Password、Ravio、Aegis 支持 SHA256其中 Bitwarden 与 Aegis 还额外支持 SHA512 与 8 位可作为功能覆盖最完整的推荐应用。利用 allowed 列表引导选择通过allowed_algorithms、allowed_digits、allowed_periods限定用户在注册时可选的组合配合默认值既保留灵活性又限制不兼容选项。务必实测认证闭环更换任何 TOTP 参数前用你用户实际使用的验证器应用走一遍添加密钥 → 生成验证码 → 完成 Authelia 认证的完整流程警惕能录入但不能认证的静默忽略行为。关注密钥长度下限secret_size最小值是 20见 const.go默认 32。低于下限的配置会被校验拦截过短的密钥也会显著降低暴力破解成本。相关资源集成参考文档本文主体docs/content/reference/integrations/time-based-one-time-password-apps.md兼容性数据源docs/data/support.json表格渲染短代码docs/layouts/_shortcodes/table-totp-support.html完整配置指南docs/content/configuration/second-factor/time-based-one-time-password.md配置结构定义internal/configuration/schema/totp.go算法与密钥大小常量internal/configuration/schema/const.goTOTP 生成与校验实现internal/totp/totp.go【免费下载链接】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），仅供参考 Authelia 时间型一次性密码（TOTP）应用兼容性参考指南：算法、位数与客户端支持矩阵
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/authelia本篇技术指南以 Authelia 官方集成参考文档 time-based-one-time-password-apps.md 为主体系统梳理 Authelia 所支持的 TOTP 可调参数、已实测的 TOTP 客户端应用兼容性矩阵并结合仓库源码schema/totp.go、internal/totp/totp.go讲解从配置到密钥生成与校验的底层原理。读完本文你将能判断用户常用的验证器 App 是否与你的 TOTP 策略兼容并据此安全地调整 Authelia 的totp配置段。TOTP 在 Authelia 中的定位Authelia 所采用的 OTP 方法是基于时间的一次性密码算法TOTP[RFC6238]它是基于 HMAC 的一次性密码算法HOTP[RFC4226]的时间扩展。用户将 Authelia 生成的密钥录入任意 TOTP 验证器应用后在登录时输入当前时间窗口内生成的动态验证码即可完成第二因素2FA认证。与部分只支持固定参数的 2FA 方案不同Authelia 对 TOTP 提供了宽泛wide variety的可调设置空间算法SHA1/SHA256/SHA512、验证码位数6/8、时间周期、允许误差skew、密钥长度等均可配置。但宽泛的配置能力并不意味着每个客户端应用都支持这正是官方维护这份集成参考矩阵的核心原因。Authelia 的 TOTP 可调设置总览在 configuration.yml 中TOTP 相关的配置段为totp完整示例参见官方配置文档 time-based-one-time-password.mdtotp: 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各参数的含义与默认值如下表默认值来源于 schema/totp.go 中的DefaultTOTPConfiguration与 JSON Schema 注解一致配置项默认值可选值说明disablefalsetrue/false设为true时整体禁用 TOTP 第二因素功能issuerAuthelia任意字符串生成 TOTP 密钥时写入的发行方标识验证器应用通常用它区分用户注册的不同服务条目algorithmsha1sha1/sha256/sha512大小写不敏感生成 TOTP 密钥时使用的 HMAC 算法digits66/8用户认证时需要输入的验证码位数period30正整数TOTP 码的有效时间窗口秒skew1非负整数允许的时间窗口误差数量1表示前后各允许 1 个周期secret_size32最小值20生成密钥的字节长度allowed_algorithms[SHA1]SHA1/SHA256/SHA512除默认算法外允许用户选择的算法列表allowed_digits[6]6/8除默认位数外允许用户选择的位数列表allowed_periods[30]正整数除默认周期外允许用户选择的周期列表disable_reuse_security_policyfalsetrue/false是否禁用禁止重复使用同一验证码的安全策略从源码实现看schema/totp.go 将默认配置定义为var DefaultTOTPConfiguration TOTP{ Issuer: Authelia, DefaultAlgorithm: TOTPAlgorithmSHA1, DefaultDigits: 6, DefaultPeriod: 30, Skew: defaultTOTPSkew, SecretSize: TOTPSecretSizeDefault, AllowedAlgorithms: []string{TOTPAlgorithmSHA1}, AllowedDigits: []int{6}, AllowedPeriods: []int{30}, }相关常量定义在 const.go 中算法枚举为TOTPAlgorithmSHA1、TOTPAlgorithmSHA256、TOTPAlgorithmSHA512密钥大小默认值TOTPSecretSizeDefault 32最小值TOTPSecretSizeMinimum 20。兼容性矩阵已测试的 TOTP 应用官方参考文档 time-based-one-time-password-apps.md 的核心内容是一张应用 × 算法 × 位数的兼容性矩阵。该矩阵并非手工硬编码在文档里而是由数据文件 support.json 驱动、经 table-totp-support.html 短代码渲染生成的表格其中✓表示该应用支持对应选项✗表示不支持。完整兼容性矩阵应用SHA1SHA256SHA5126 位8 位Google Authenticator✓✗✗✓✗Bitwarden✓✓✓✓✓Yubico Authenticator✓✗✗✓✓Authenticator Plus✓✗✗✓✗1Password✓✓✗✓✗Ravio✓✓✗✓✗Authy✓✗✗✗✓Aegis✓✓✓✓✓Okta Verify✓✗✗✓✗逐应用解读Google Authenticator最普及的验证器之一仅支持 SHA1 算法与 6 位验证码不支持 SHA256/SHA512 和 8 位。若你的用户群体大量使用 Google Authenticator则不应更改默认算法与位数。Bitwarden兼容性最好的应用之一三种算法SHA1/SHA256/SHA512与两种位数6/8全部支持适合作为默认推荐应用。Yubico Authenticator算法上仅支持 SHA1但位数同时支持 6 位和 8 位。Authenticator Plus仅支持 SHA1 与 6 位。1Password支持 SHA1/SHA256不支持 SHA512位数仅支持 6 位。Ravio与 1Password 相同的算法支持范围SHA1/SHA256位数仅支持 6 位。Authy矩阵中较为特殊的一个——算法仅支持 SHA1且位数仅支持8 位而非常见的 6 位。这意味着使用 Authy 的用户可能无法使用默认的 6 位 TOTP 配置反之亦然。Aegis与 Bitwarden 一样算法与位数全部支持是功能覆盖最完整的开源验证器之一。Okta Verify仅支持 SHA1 与 6 位。矩阵的使用边界官方文档对这张矩阵给出了重要限定原文要点矩阵是已经过测试且可用tested that work的应用集合不应假设列表中某应用的信息对其当前版本仍然准确——应用可能已支持此前不支持的选项在少数情况下也可能支持得比以前更少因此在调整任何 TOTP 选项前务必以实际部署版本为准进行验证。为什么兼容性如此重要静默忽略选项问题Authelia 默认配置刻意选择兼容性优先的取值原因在配置文档 time-based-one-time-password.md 中表述得非常明确许多应用不支持 6 位以外的位数且很多只支持 SHA1。更关键的风险是部分 TOTP 应用允许用户成功添加密钥但在生成验证码时静默忽略密钥中声明的位数或算法导致能录入、不能认证的假成功现象。因此官方反复强调仅测试应用能否添加密钥是不够的必须完整走一遍认证流程确认应用生成并提交的验证码能被 Authelia 正确校验变更algorithm、digits、period等选项前应先确认你的用户实际使用的验证器应用并对它们逐一测试可以结合本文的兼容性矩阵time-based-one-time-password-apps.md圈定候选应用范围。源码级原理从配置到密钥生成与验证了解设置项如何影响实际行为有助于你做出正确的配置决策。Authelia 的 TOTP 能力集中在 internal/totp/totp.go 中底层基于github.com/authelia/otp库实现。配置到 Provider 的映射NewTimeBasedProvider将schema.TOTP配置转换为生产环境的TimeBasedProvidertotp.goprovider TimeBased{ opts: NewTOTPOptionsFromSchema(config), issuer: config.Issuer, algorithm: config.DefaultAlgorithm, digits: uint32(config.DefaultDigits), period: uint(config.DefaultPeriod), size: uint(config.SecretSize), } if config.Skew ! nil *config.Skew 0 { provider.skew uint(*config.Skew) } else { provider.skew 1 }可以看到skew的兜底逻辑当配置缺失或为负值时回退为1。同时NewTOTPOptionsFromSchema会把allowed_algorithms/allowed_digits/allowed_periods组装成model.TOTPOptions供注册流程中向用户展示可选范围。密钥生成Generate / GenerateCustomGenerate使用默认参数生成密钥GenerateCustom则支持逐项覆盖totp.go。关键实现细节若显式传入secret会先按Base32 无填充NoPadding标准解码校验解码失败即返回错误error decoding base32 string调用totp.Generate时注入Issuer、AccountName即用户名、Period、SecretSize、Digits、Algorithm并使用ctx.GetRandom()提供的加密安全随机源生成的model.TOTPConfiguration会记录CreatedAt、Username、Issuer、Algorithm、Digits、Secret、Period其中Secret为 Base32 编码的密钥文本。验证码校验ValidateValidate从已保存的配置中读取Period、Digits、Algorithm结合 Provider 的skew构造totp.ValidateOpts最终调用totp.ValidateCustomStep并以ctx.GetClock().Now().UTC()作为当前时间基准totp.go。这意味着校验时使用的是密钥登记时固化的算法、位数与周期而不是当前全局默认值——这正是更改默认值只影响新注册的密钥这一行为的来源skew决定允许的时间漂移窗口客户端与服务器时钟偏差较大时适当增大skew可减少认证失败但也会扩大暴力破解窗口。注册流程与仅影响新密钥的语义配置文档明确指出修改algorithm、digits、period、secret_size等选项仅影响新注册的 TOTP 密钥已存在的密钥配置在生成时即已固化于存储中。因此调整默认值不会破坏存量用户的认证但也不会自动升级他们的密钥安全强度——如需让存量用户享受新参数需要引导他们重新注册 TOTP。实操建议为你的用户群选择安全的 TOTP 策略结合兼容性矩阵与源码行为可以给出以下落地建议保持默认值起步sha1 6 位 30 秒周期 skew 1 是兼容性最优组合覆盖矩阵中全部 9 款已测试应用唯一例外是 Authy 仅支持 8 位。若用户使用 Authy需评估位数不匹配带来的影响。如要增强安全性优先考虑将算法提升为sha256。此时应确认用户应用支持矩阵显示只有 Bitwarden、1Password、Ravio、Aegis 支持 SHA256其中 Bitwarden 与 Aegis 还额外支持 SHA512 与 8 位可作为功能覆盖最完整的推荐应用。利用 allowed 列表引导选择通过allowed_algorithms、allowed_digits、allowed_periods限定用户在注册时可选的组合配合默认值既保留灵活性又限制不兼容选项。务必实测认证闭环更换任何 TOTP 参数前用你用户实际使用的验证器应用走一遍添加密钥 → 生成验证码 → 完成 Authelia 认证的完整流程警惕能录入但不能认证的静默忽略行为。关注密钥长度下限secret_size最小值是 20见 const.go默认 32。低于下限的配置会被校验拦截过短的密钥也会显著降低暴力破解成本。相关资源集成参考文档本文主体docs/content/reference/integrations/time-based-one-time-password-apps.md兼容性数据源docs/data/support.json表格渲染短代码docs/layouts/_shortcodes/table-totp-support.html完整配置指南docs/content/configuration/second-factor/time-based-one-time-password.md配置结构定义internal/configuration/schema/totp.go算法与密钥大小常量internal/configuration/schema/const.goTOTP 生成与校验实现internal/totp/totp.go【免费下载链接】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），仅供参考