Authelia 文件型第一因素认证后端File Authentication Backend完整配置指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 支持基于文件的用户数据库作为第一因素First Factor认证后端适合在没有 LDAP 目录服务器的场景下管理用户。本文以官方配置文档docs/content/configuration/first-factor/file.md为核心完整讲解authentication_backend.file的每一个配置项包括用户数据库路径、热加载监听、用户名/邮箱搜索、扩展属性以及五种密码哈希算法的参数调优并结合仓库源码internal/authentication、internal/configuration等说明底层实现与校验规则。读完本文你将能够从零配置一个可用的文件型认证后端并用authelia crypto hash generate命令生成安全合规的密码哈希。概述文件型认证后端在 Authelia 中的位置在 Authelia 的配置中第一因素认证后端通过authentication_backend顶级配置键指定它只允许配置两种后端之一file文件型或ldapLDAP 目录服务器。文件型后端将用户列表保存在一个本地 YAML 文件中适合中小规模部署、测试环境或不想维护 LDAP 服务器的场景。从配置结构看internal/configuration/schema/authentication.goauthentication_backend包含file、ldap两个互斥的子配置块同时还有password_reset、password_change、refresh_interval等全局选项。文件型后端的核心实现位于 internal/authentication/file_user_provider.go 与 internal/authentication/file_user_provider_database.go前者负责认证逻辑校验密码、更新密码等后者负责用户数据库的加载、保存与别名索引。完整配置示例以下配置完整展示了authentication_backend.file的全部可用选项复制自官方文档可直接作为configuration.yml的参考模板authentication_backend: file: path: /config/users.yml watch: false search: email: false case_insensitive: false extra_attributes: extra_example: multi_valued: false value_type: string password: algorithm: argon2 argon2: variant: argon2id iterations: 3 memory: 65536 parallelism: 4 key_length: 32 salt_length: 16 scrypt: variant: scrypt iterations: 16 block_size: 8 parallelism: 1 key_length: 32 salt_length: 16 pbkdf2: variant: sha512 iterations: 310000 salt_length: 16 sha2crypt: variant: sha512 iterations: 50000 salt_length: 16 bcrypt: variant: standard cost: 12下面按path、watch、search、extra_attributes、password五组分别讲解每个选项的含义、默认值与底层实现。path用户数据库文件路径必填属性说明类型string必填是path指定存放用户明细列表的文件路径。当前支持的格式为 YAML 文件具体格式说明见 Passwords 参考指南的 YAML Format 一节。在启动阶段Authelia 会执行StartupCheck见 file_user_provider.go其中的checkDatabase函数会检查该路径是否存在如果文件不存在Authelia 会以0600权限自动生成一份模板文件内容来自 internal/authentication/users_database.template.yml含一个默认的authelia测试用户并在日志中提示数据库已被生成然后要求你补充真实用户后再重启。关于该文件的权限需要特别注意它必须允许 Authelia 进程读写。因为当用户通过 Authelia 自助重置密码或修改密码时新哈希会被写回该文件见下方UpdatePassword/ChangePassword实现。watch监听文件变更并热重载属性类型默认值必填watchbooleanfalse否启用后Authelia 会监听该文件的变化并在文件被外部修改时动态重载用户数据库无需重启服务。从源码看这一功能由文件监视服务实现internal/service/file_watcher.go服务启动时会断言当前UserProvider是*authentication.FileUserProvider类型然后基于config.AuthenticationBackend.File.Path创建FileWatcher当文件内容发生变化时触发provider.Reload()重新解析 YAML 并重建用户索引。同时在配置校验阶段internal/configuration/validator/authentication.go存在一个联动逻辑当启用watch时refresh_interval会被自动设置为always始终刷新即用户信息始终以文件内容为准。Reload()内部实现了冷却cooldown机制两次重载之间至少间隔 500 毫秒防止文件抖动导致频繁重载此外如果文件被清空内容为空重载会被拒绝并返回ErrWatcherNoContent避免错误清空内存中的用户数据见 file_user_provider.go。search用户名搜索选项实验性功能search子配置控制登录时的用户查找方式。重要提示search下的选项目前属于实验性功能使用时请评估风险。email属性类型默认值必填emailbooleanfalse否启用后用户既可以使用用户名登录也可以使用配置的邮箱地址登录。启用该功能需要满足两个约束违反时加载数据库会直接报错两个用户不能配置相同的邮箱地址重复邮箱会被拒绝任何用户名不能是一个邮箱地址即用户名中不能包含形式的邮箱字符串。注意无论是否开启大小写不敏感邮箱地址的查找始终按大小写不敏感方式处理。case_insensitive属性类型默认值必填case_insensitivebooleanfalse否启用后用户可以用任意大小写组合的用户名登录例如注册为John登录时输入john或JOHN均可。启用该功能要求数据库中所有用户名必须是小写否则加载数据库时会报错。注意邮箱地址的查找始终按大小写不敏感方式处理。底层实现别名Alias索引机制这两个搜索选项的底层逻辑在 file_user_provider_database.go 的LoadAliases、loadAlias、loadAliasEmail与GetUserDetails中数据库加载完成后会根据SearchEmail/SearchCI构建两个索引映射Emails小写邮箱 → 用户名和Aliases小写用户名 → 原始用户名加载过程中会执行严格的唯一性校验邮箱重复、用户名是邮箱、用户名非小写等都会导致加载失败并给出包含具体用户名的错误信息登录查找时GetUserDetails会依次尝试邮箱索引、大小写不敏感别名索引、精确用户名匹配三种方式。extra_attributes扩展用户属性属性类型必填extra_attributesdictionary(object)否extra_attributes用于从用户数据库加载额外的自定义属性。这些属性可以在 Authelia 的其他模块中使用典型场景是 OpenID Connect 1.0 身份提供者见 OpenID Connect Provider 配置也推荐阅读 Attributes 参考指南 了解属性体系的整体设计。配置中的键key代表后端属性名。数据库加载时会根据multi_valued与value_type配置对每个用户的对应属性进行校验。例如下面的配置把用户数据库中的example_file_attribute属性加载为 Authelia 属性将其视为单值且底层类型为整数authentication_backend: file: extra_attributes: example_file_attribute: multi_valued: false value_type: integer提示除了直接加载的扩展属性外你还可以基于已有属性的值通过 Definitions 配置的 user-attributes 一节 定义派生出的自定义属性。value_type属性类型必填value_typestring是定义该属性的底层类型合法值为string、integer、boolean。只要配置了某个扩展属性value_type就是必填项常量定义见 internal/authentication/const.go。配置校验阶段validator/authentication.go还会检查value_type缺失或取值非法时报错且属性名不能与 Authelia 内置保留属性冲突通过expression.IsReservedAttribute判定。multi_valued属性类型必填multi_valuedboolean否指示该属性是否可以包含多个值。数据库加载时ValidateExtra见 file_user_provider_database.go会对每个用户的extra字段做严格校验单值属性的每个值必须与value_type匹配多值属性的值必须是数组且数组内每个元素类型都要匹配未在配置中定义的属性名、类型不匹配的值都会导致整个数据库加载失败并给出具体到用户和属性名的错误。密码选项Password Optionsauthentication_backend.file.password控制 Authelia 在用户自行修改密码例如通过自助服务重置密码、修改密码时新密码使用的哈希算法与参数。它不影响对已有密码哈希的验证——Authelia 会根据已有哈希的前缀自动识别其算法识别表见下方算法识别一节。关于如何为不同算法选择合适的参数官方提供了一份专门的参考指南docs/content/reference/guides/passwords.md其中包含用户/密码文件格式、哈希生成命令、成本Cost评估方法以及各算法的推荐参数建议结合本文一起阅读。algorithm哈希算法选择属性类型默认值必填algorithmstringargon2否控制新密码的哈希算法取值必须是以下之一argon2使用 Argon2 算法默认scrypt使用 Scrypt 算法pbkdf2使用 PBKDF2 算法sha2crypt使用 SHA2Crypt 算法bcrypt使用 Bcrypt 算法。配置校验逻辑见 validator/authentication.go算法未配置时回退到默认值argon2非法取值会报错随后会分别校验五个算法的子参数。注意 schema 中还保留了一组标记为deprecated的顶层参数iterations、memory、parallelism、key_length、salt_length用于兼容旧版配置新版配置应使用各算法子块中的显式参数迁移逻辑见validateFileAuthenticationBackendPasswordConfigLegacy。argon2Argon2Argon2 是少数几种纯粹为密码哈希而设计的算法之一RFC 9106也是当前安全性最好的密码哈希算法之一。它同时支持 CPU 与内存两类成本扩展是默认且最受推荐的算法。参数类型默认值取值范围源码 jsonschema 约束说明variantstringargon2idargon2id/argon2i/argon2d算法变体推荐argon2iditerationsinteger3最小值 1迭代次数参数 tmemoryinteger65536最小值 8最大值 4294967295内存用量单位kibibytesKiB即 65536 64 MiBparallelisminteger4最小值 1最大值 16777215并行度参数 pkey_lengthinteger32最小值 4输出密钥长度参数 k单位字节salt_lengthinteger16最小值 1盐长度单位字节取值范围来自 internal/configuration/schema/authentication.go 的 jsonschema 约束运行时校验见 validator/authentication.go。校验器还会检查一个 Argon2 特有的约束memory必须不小于parallelism * 8MemoryMinParallelismMultiplier否则会提示内存相对并行度不足见 validator/authentication.go。推荐的 Argon2 参数组合来自 Passwords 参考指南场景变体迭代次数 (t)并行度 (p)内存 (m)盐长度密钥长度低内存环境argon2id34655361632推荐配置argon2id1420971521632scryptScryptScrypt 是另一种同时具备内存与 CPU 成本的算法可视为仅次于 Argon2 的选择。参数类型默认值说明variantstringscrypt合法值scrypt/yescryptiterationsinteger16迭代次数成本参数 N 的对数即2^Nblock_sizeinteger8块大小参数 rparallelisminteger1并行度参数 pkey_lengthinteger32输出密钥长度单位字节salt_lengthinteger16盐长度单位字节一个值得注意的约束当variant为yescrypt时parallelism必须为 1否则配置校验会报错见 validator/authentication.go。pbkdf2PBKDF2PBKDF2 是 FIPS 140 合规场景下事实上的唯一选择详见 Passwords 参考指南。参数类型默认值说明variantstringsha512支持sha1/sha224/sha256/sha384/sha512iterationsinteger取决于 variant见下表迭代次数salt_lengthinteger16盐长度单位字节PBKDF2 的iterations默认值基于 variant 而定见 internal/configuration/schema/authentication.go这些值略高于 FIPS 140 的建议值以面向未来留有余量Variant默认迭代次数sha11600000sha224900000sha256700000sha384280000sha512310000sha2cryptSHA2CryptSHA2 Crypt 主要用于向后兼容官方文档指出它只支持扩展 CPU 成本随着硬件提升被暴力破解的风险相对更高。参数类型默认值说明variantstringsha512合法值sha256/sha512推荐sha512iterationsinteger50000轮数rounds最小值 1000salt_lengthinteger16盐长度最大值 16bcryptBcryptBcrypt 仅在需要与遗留系统互操作时才推荐使用见 Passwords 参考指南。参数类型默认值说明variantstringstandard合法值standard/sha256推荐standardcostinteger12哈希成本最小值 10最大值 31重要提示sha256变体是 Passlib 设计的一种特殊变体它将密码先经过一次 SHA256 HMAC 再交给 Bcrypt从而绕开 Bcrypt 默认 72 字节的密码截断限制。但该变体不被很多其他系统支持使用前需确认互操作性。算法识别哈希前缀对照Authelia 在验证已有密码时并不依赖配置的algorithm而是通过哈希字符串的前缀自动识别算法。下表整理自 Passwords 参考指南算法变体前缀Argon2argon2id$argon2id$Argon2argon2i$argon2i$Argon2argon2d$argon2d$Scryptscrypt$scrypt$Scryptyescrypt$y$PBKDF2sha1$pbkdf2$PBKDF2sha224$pbkdf2-sha224$PBKDF2sha256$pbkdf2-sha256$PBKDF2sha384$pbkdf2-sha384$PBKDF2sha512$pbkdf2-sha512$SHA2 CryptSHA256$5$SHA2 CryptSHA512$6$Bcryptstandard$2b$Bcryptsha256$bcrypt-sha256$在代码层面internal/authentication/file_user_provider_database.go 使用crypt.Decode解析数据库中的密码哈希NewFileCryptoHashFromConfigfile_user_provider.go则根据配置的algorithm构造对应的哈希器用于生成新密码的哈希。用户数据库文件格式与密码哈希生成YAML 用户数据库格式path指向的文件是一个 YAML 文件顶层为users字典每个用户键下可配置以下字段完整示例见 Passwords 参考指南users: john: disabled: false displayname: John Doe password: $argon2id$v19$m65536,t3,p2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSsiM email: john.doeauthelia.com groups: - admins - dev bob: disabled: false displayname: Bob Dylan password: $argon2id$v19$m65536,t3,p2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSsiM email: bob.dylanauthelia.com groups: - dev given_name: Robert family_name: Zimmerman nickname: Bob gender: male birthdate: 1941-05-24 zoneinfo: America/Chicago locale: en-US phone_number: 1 (425) 555-1212 address: street_address: 2-3 Kitanomarukoen locality: Chiyoda City region: Tokyo postal_code: 102-8321 country: Japan extra: example: value文件中存储的password字段是哈希后的密文而非明文。所有字段包括extra扩展属性在加载时都会被校验扩展属性未在配置中声明会直接导致加载失败。仓库自带的模板文件见 internal/authentication/users_database.template.yml其中还演示了disabled: true的用法禁用用户无法登录。使用 authelia crypto hash generate 生成哈希Authelia 提供了专门的 CLI 命令authelia crypto hash generate来生成密码哈希其实现位于 internal/commands/crypto_hash.go。该命令支持多种算法运行authelia crypto hash generate --help可查看全部算法查看某个算法的可调参数则在算法子命令后加--help例如authelia crypto hash generate argon2 --help。生成 Argon2 哈希交互式输入密码authelia crypto hash generate argon2使用--password参数免交互生成密码含特殊字符时务必使用单引号防止 shell 参数替换authelia crypto hash generate argon2 --password password输出示例Digest: $argon2id$v19$m65536,t3,p4$Hjc8e7WYcBFcJmEDUOsS9A$ozM7RyZR1EyDR8cuyVpDDfmLrGPGFgo5E2NNqRumui4还可以通过--config指定现有配置文件此时将使用配置中password段定义的算法与参数来生成哈希authelia crypto hash generate --config /configuration.yml成本建议选择哈希参数时最重要的指标是成本。官方建议在你的硬件上单次哈希耗时约 500 毫秒旧硬件可适当提高高端硬件、用户量大时可略降低。对于 Argon2、Scrypt 这类内存型算法还要注意 Go 在哈希完成后会释放内存但操作系统可能延迟回收表现为 Authelia 占用内存偏高属正常现象。认证与密码更新流程源码视角理解文件型后端的工作流程有助于排障与二次开发。核心实现都在 internal/authentication/file_user_provider.go启动校验StartupCheck先检查数据库文件是否存在不存在则生成模板再根据password配置构造哈希器最后加载数据库。登录校验CheckUserPassword按用户名或启用的邮箱/大小写不敏感搜索从数据库取出用户详情若用户被标记为disabled直接视为不存在否则用哈希匹配密码MatchAdvanced。获取用户信息GetDetails/GetDetailsExtended返回用户的显示名、邮箱、组以及扩展属性这些信息可供访问控制规则、OIDC 等模块使用。修改密码ChangePassword校验旧密码正确、新密码非空且与旧密码不同后用配置的哈希器生成新哈希并写回数据库文件Save。重置密码UpdatePassword同样生成新哈希并持久化到文件。由于修改密码会写回 YAML 文件因此path指向的文件必须对运行 Authelia 的进程开放读写权限同时这也解释了为什么启用watch后外部对文件的修改会被自动重载——文件是内存数据库的唯一持久化来源。【免费下载链接】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），仅供参考 
长河君 · 2026/9/10 13:13:20 · 阅读 1.2k Authelia 文件型第一因素认证后端（File Authentication Backend）完整配置指南
Authelia 文件型第一因素认证后端File Authentication Backend完整配置指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 支持基于文件的用户数据库作为第一因素First Factor认证后端适合在没有 LDAP 目录服务器的场景下管理用户。本文以官方配置文档docs/content/configuration/first-factor/file.md为核心完整讲解authentication_backend.file的每一个配置项包括用户数据库路径、热加载监听、用户名/邮箱搜索、扩展属性以及五种密码哈希算法的参数调优并结合仓库源码internal/authentication、internal/configuration等说明底层实现与校验规则。读完本文你将能够从零配置一个可用的文件型认证后端并用authelia crypto hash generate命令生成安全合规的密码哈希。概述文件型认证后端在 Authelia 中的位置在 Authelia 的配置中第一因素认证后端通过authentication_backend顶级配置键指定它只允许配置两种后端之一file文件型或ldapLDAP 目录服务器。文件型后端将用户列表保存在一个本地 YAML 文件中适合中小规模部署、测试环境或不想维护 LDAP 服务器的场景。从配置结构看internal/configuration/schema/authentication.goauthentication_backend包含file、ldap两个互斥的子配置块同时还有password_reset、password_change、refresh_interval等全局选项。文件型后端的核心实现位于 internal/authentication/file_user_provider.go 与 internal/authentication/file_user_provider_database.go前者负责认证逻辑校验密码、更新密码等后者负责用户数据库的加载、保存与别名索引。完整配置示例以下配置完整展示了authentication_backend.file的全部可用选项复制自官方文档可直接作为configuration.yml的参考模板authentication_backend: file: path: /config/users.yml watch: false search: email: false case_insensitive: false extra_attributes: extra_example: multi_valued: false value_type: string password: algorithm: argon2 argon2: variant: argon2id iterations: 3 memory: 65536 parallelism: 4 key_length: 32 salt_length: 16 scrypt: variant: scrypt iterations: 16 block_size: 8 parallelism: 1 key_length: 32 salt_length: 16 pbkdf2: variant: sha512 iterations: 310000 salt_length: 16 sha2crypt: variant: sha512 iterations: 50000 salt_length: 16 bcrypt: variant: standard cost: 12下面按path、watch、search、extra_attributes、password五组分别讲解每个选项的含义、默认值与底层实现。path用户数据库文件路径必填属性说明类型string必填是path指定存放用户明细列表的文件路径。当前支持的格式为 YAML 文件具体格式说明见 Passwords 参考指南的 YAML Format 一节。在启动阶段Authelia 会执行StartupCheck见 file_user_provider.go其中的checkDatabase函数会检查该路径是否存在如果文件不存在Authelia 会以0600权限自动生成一份模板文件内容来自 internal/authentication/users_database.template.yml含一个默认的authelia测试用户并在日志中提示数据库已被生成然后要求你补充真实用户后再重启。关于该文件的权限需要特别注意它必须允许 Authelia 进程读写。因为当用户通过 Authelia 自助重置密码或修改密码时新哈希会被写回该文件见下方UpdatePassword/ChangePassword实现。watch监听文件变更并热重载属性类型默认值必填watchbooleanfalse否启用后Authelia 会监听该文件的变化并在文件被外部修改时动态重载用户数据库无需重启服务。从源码看这一功能由文件监视服务实现internal/service/file_watcher.go服务启动时会断言当前UserProvider是*authentication.FileUserProvider类型然后基于config.AuthenticationBackend.File.Path创建FileWatcher当文件内容发生变化时触发provider.Reload()重新解析 YAML 并重建用户索引。同时在配置校验阶段internal/configuration/validator/authentication.go存在一个联动逻辑当启用watch时refresh_interval会被自动设置为always始终刷新即用户信息始终以文件内容为准。Reload()内部实现了冷却cooldown机制两次重载之间至少间隔 500 毫秒防止文件抖动导致频繁重载此外如果文件被清空内容为空重载会被拒绝并返回ErrWatcherNoContent避免错误清空内存中的用户数据见 file_user_provider.go。search用户名搜索选项实验性功能search子配置控制登录时的用户查找方式。重要提示search下的选项目前属于实验性功能使用时请评估风险。email属性类型默认值必填emailbooleanfalse否启用后用户既可以使用用户名登录也可以使用配置的邮箱地址登录。启用该功能需要满足两个约束违反时加载数据库会直接报错两个用户不能配置相同的邮箱地址重复邮箱会被拒绝任何用户名不能是一个邮箱地址即用户名中不能包含形式的邮箱字符串。注意无论是否开启大小写不敏感邮箱地址的查找始终按大小写不敏感方式处理。case_insensitive属性类型默认值必填case_insensitivebooleanfalse否启用后用户可以用任意大小写组合的用户名登录例如注册为John登录时输入john或JOHN均可。启用该功能要求数据库中所有用户名必须是小写否则加载数据库时会报错。注意邮箱地址的查找始终按大小写不敏感方式处理。底层实现别名Alias索引机制这两个搜索选项的底层逻辑在 file_user_provider_database.go 的LoadAliases、loadAlias、loadAliasEmail与GetUserDetails中数据库加载完成后会根据SearchEmail/SearchCI构建两个索引映射Emails小写邮箱 → 用户名和Aliases小写用户名 → 原始用户名加载过程中会执行严格的唯一性校验邮箱重复、用户名是邮箱、用户名非小写等都会导致加载失败并给出包含具体用户名的错误信息登录查找时GetUserDetails会依次尝试邮箱索引、大小写不敏感别名索引、精确用户名匹配三种方式。extra_attributes扩展用户属性属性类型必填extra_attributesdictionary(object)否extra_attributes用于从用户数据库加载额外的自定义属性。这些属性可以在 Authelia 的其他模块中使用典型场景是 OpenID Connect 1.0 身份提供者见 OpenID Connect Provider 配置也推荐阅读 Attributes 参考指南 了解属性体系的整体设计。配置中的键key代表后端属性名。数据库加载时会根据multi_valued与value_type配置对每个用户的对应属性进行校验。例如下面的配置把用户数据库中的example_file_attribute属性加载为 Authelia 属性将其视为单值且底层类型为整数authentication_backend: file: extra_attributes: example_file_attribute: multi_valued: false value_type: integer提示除了直接加载的扩展属性外你还可以基于已有属性的值通过 Definitions 配置的 user-attributes 一节 定义派生出的自定义属性。value_type属性类型必填value_typestring是定义该属性的底层类型合法值为string、integer、boolean。只要配置了某个扩展属性value_type就是必填项常量定义见 internal/authentication/const.go。配置校验阶段validator/authentication.go还会检查value_type缺失或取值非法时报错且属性名不能与 Authelia 内置保留属性冲突通过expression.IsReservedAttribute判定。multi_valued属性类型必填multi_valuedboolean否指示该属性是否可以包含多个值。数据库加载时ValidateExtra见 file_user_provider_database.go会对每个用户的extra字段做严格校验单值属性的每个值必须与value_type匹配多值属性的值必须是数组且数组内每个元素类型都要匹配未在配置中定义的属性名、类型不匹配的值都会导致整个数据库加载失败并给出具体到用户和属性名的错误。密码选项Password Optionsauthentication_backend.file.password控制 Authelia 在用户自行修改密码例如通过自助服务重置密码、修改密码时新密码使用的哈希算法与参数。它不影响对已有密码哈希的验证——Authelia 会根据已有哈希的前缀自动识别其算法识别表见下方算法识别一节。关于如何为不同算法选择合适的参数官方提供了一份专门的参考指南docs/content/reference/guides/passwords.md其中包含用户/密码文件格式、哈希生成命令、成本Cost评估方法以及各算法的推荐参数建议结合本文一起阅读。algorithm哈希算法选择属性类型默认值必填algorithmstringargon2否控制新密码的哈希算法取值必须是以下之一argon2使用 Argon2 算法默认scrypt使用 Scrypt 算法pbkdf2使用 PBKDF2 算法sha2crypt使用 SHA2Crypt 算法bcrypt使用 Bcrypt 算法。配置校验逻辑见 validator/authentication.go算法未配置时回退到默认值argon2非法取值会报错随后会分别校验五个算法的子参数。注意 schema 中还保留了一组标记为deprecated的顶层参数iterations、memory、parallelism、key_length、salt_length用于兼容旧版配置新版配置应使用各算法子块中的显式参数迁移逻辑见validateFileAuthenticationBackendPasswordConfigLegacy。argon2Argon2Argon2 是少数几种纯粹为密码哈希而设计的算法之一RFC 9106也是当前安全性最好的密码哈希算法之一。它同时支持 CPU 与内存两类成本扩展是默认且最受推荐的算法。参数类型默认值取值范围源码 jsonschema 约束说明variantstringargon2idargon2id/argon2i/argon2d算法变体推荐argon2iditerationsinteger3最小值 1迭代次数参数 tmemoryinteger65536最小值 8最大值 4294967295内存用量单位kibibytesKiB即 65536 64 MiBparallelisminteger4最小值 1最大值 16777215并行度参数 pkey_lengthinteger32最小值 4输出密钥长度参数 k单位字节salt_lengthinteger16最小值 1盐长度单位字节取值范围来自 internal/configuration/schema/authentication.go 的 jsonschema 约束运行时校验见 validator/authentication.go。校验器还会检查一个 Argon2 特有的约束memory必须不小于parallelism * 8MemoryMinParallelismMultiplier否则会提示内存相对并行度不足见 validator/authentication.go。推荐的 Argon2 参数组合来自 Passwords 参考指南场景变体迭代次数 (t)并行度 (p)内存 (m)盐长度密钥长度低内存环境argon2id34655361632推荐配置argon2id1420971521632scryptScryptScrypt 是另一种同时具备内存与 CPU 成本的算法可视为仅次于 Argon2 的选择。参数类型默认值说明variantstringscrypt合法值scrypt/yescryptiterationsinteger16迭代次数成本参数 N 的对数即2^Nblock_sizeinteger8块大小参数 rparallelisminteger1并行度参数 pkey_lengthinteger32输出密钥长度单位字节salt_lengthinteger16盐长度单位字节一个值得注意的约束当variant为yescrypt时parallelism必须为 1否则配置校验会报错见 validator/authentication.go。pbkdf2PBKDF2PBKDF2 是 FIPS 140 合规场景下事实上的唯一选择详见 Passwords 参考指南。参数类型默认值说明variantstringsha512支持sha1/sha224/sha256/sha384/sha512iterationsinteger取决于 variant见下表迭代次数salt_lengthinteger16盐长度单位字节PBKDF2 的iterations默认值基于 variant 而定见 internal/configuration/schema/authentication.go这些值略高于 FIPS 140 的建议值以面向未来留有余量Variant默认迭代次数sha11600000sha224900000sha256700000sha384280000sha512310000sha2cryptSHA2CryptSHA2 Crypt 主要用于向后兼容官方文档指出它只支持扩展 CPU 成本随着硬件提升被暴力破解的风险相对更高。参数类型默认值说明variantstringsha512合法值sha256/sha512推荐sha512iterationsinteger50000轮数rounds最小值 1000salt_lengthinteger16盐长度最大值 16bcryptBcryptBcrypt 仅在需要与遗留系统互操作时才推荐使用见 Passwords 参考指南。参数类型默认值说明variantstringstandard合法值standard/sha256推荐standardcostinteger12哈希成本最小值 10最大值 31重要提示sha256变体是 Passlib 设计的一种特殊变体它将密码先经过一次 SHA256 HMAC 再交给 Bcrypt从而绕开 Bcrypt 默认 72 字节的密码截断限制。但该变体不被很多其他系统支持使用前需确认互操作性。算法识别哈希前缀对照Authelia 在验证已有密码时并不依赖配置的algorithm而是通过哈希字符串的前缀自动识别算法。下表整理自 Passwords 参考指南算法变体前缀Argon2argon2id$argon2id$Argon2argon2i$argon2i$Argon2argon2d$argon2d$Scryptscrypt$scrypt$Scryptyescrypt$y$PBKDF2sha1$pbkdf2$PBKDF2sha224$pbkdf2-sha224$PBKDF2sha256$pbkdf2-sha256$PBKDF2sha384$pbkdf2-sha384$PBKDF2sha512$pbkdf2-sha512$SHA2 CryptSHA256$5$SHA2 CryptSHA512$6$Bcryptstandard$2b$Bcryptsha256$bcrypt-sha256$在代码层面internal/authentication/file_user_provider_database.go 使用crypt.Decode解析数据库中的密码哈希NewFileCryptoHashFromConfigfile_user_provider.go则根据配置的algorithm构造对应的哈希器用于生成新密码的哈希。用户数据库文件格式与密码哈希生成YAML 用户数据库格式path指向的文件是一个 YAML 文件顶层为users字典每个用户键下可配置以下字段完整示例见 Passwords 参考指南users: john: disabled: false displayname: John Doe password: $argon2id$v19$m65536,t3,p2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSsiM email: john.doeauthelia.com groups: - admins - dev bob: disabled: false displayname: Bob Dylan password: $argon2id$v19$m65536,t3,p2$BpLnfgDsc2WD8F2q$o/vzA4myCqZZ36bUGsDY//8mKUYNZZaR0t4MFFSsiM email: bob.dylanauthelia.com groups: - dev given_name: Robert family_name: Zimmerman nickname: Bob gender: male birthdate: 1941-05-24 zoneinfo: America/Chicago locale: en-US phone_number: 1 (425) 555-1212 address: street_address: 2-3 Kitanomarukoen locality: Chiyoda City region: Tokyo postal_code: 102-8321 country: Japan extra: example: value文件中存储的password字段是哈希后的密文而非明文。所有字段包括extra扩展属性在加载时都会被校验扩展属性未在配置中声明会直接导致加载失败。仓库自带的模板文件见 internal/authentication/users_database.template.yml其中还演示了disabled: true的用法禁用用户无法登录。使用 authelia crypto hash generate 生成哈希Authelia 提供了专门的 CLI 命令authelia crypto hash generate来生成密码哈希其实现位于 internal/commands/crypto_hash.go。该命令支持多种算法运行authelia crypto hash generate --help可查看全部算法查看某个算法的可调参数则在算法子命令后加--help例如authelia crypto hash generate argon2 --help。生成 Argon2 哈希交互式输入密码authelia crypto hash generate argon2使用--password参数免交互生成密码含特殊字符时务必使用单引号防止 shell 参数替换authelia crypto hash generate argon2 --password password输出示例Digest: $argon2id$v19$m65536,t3,p4$Hjc8e7WYcBFcJmEDUOsS9A$ozM7RyZR1EyDR8cuyVpDDfmLrGPGFgo5E2NNqRumui4还可以通过--config指定现有配置文件此时将使用配置中password段定义的算法与参数来生成哈希authelia crypto hash generate --config /configuration.yml成本建议选择哈希参数时最重要的指标是成本。官方建议在你的硬件上单次哈希耗时约 500 毫秒旧硬件可适当提高高端硬件、用户量大时可略降低。对于 Argon2、Scrypt 这类内存型算法还要注意 Go 在哈希完成后会释放内存但操作系统可能延迟回收表现为 Authelia 占用内存偏高属正常现象。认证与密码更新流程源码视角理解文件型后端的工作流程有助于排障与二次开发。核心实现都在 internal/authentication/file_user_provider.go启动校验StartupCheck先检查数据库文件是否存在不存在则生成模板再根据password配置构造哈希器最后加载数据库。登录校验CheckUserPassword按用户名或启用的邮箱/大小写不敏感搜索从数据库取出用户详情若用户被标记为disabled直接视为不存在否则用哈希匹配密码MatchAdvanced。获取用户信息GetDetails/GetDetailsExtended返回用户的显示名、邮箱、组以及扩展属性这些信息可供访问控制规则、OIDC 等模块使用。修改密码ChangePassword校验旧密码正确、新密码非空且与旧密码不同后用配置的哈希器生成新哈希并写回数据库文件Save。重置密码UpdatePassword同样生成新哈希并持久化到文件。由于修改密码会写回 YAML 文件因此path指向的文件必须对运行 Authelia 的进程开放读写权限同时这也解释了为什么启用watch后外部对文件的修改会被自动重载——文件是内存数据库的唯一持久化来源。【免费下载链接】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），仅供参考