Authelia 第一因子认证First Factor配置指南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认证方式本指南基于官方配置文档 docs/content/configuration/first-factor/introduction.md系统讲解authentication_backend配置块的完整结构与每个选项的语义并深入 File 与 LDAP 两种后端实现细节。读完本文你将能够独立完成第一因子认证的配置、密码哈希算法的选型与调优以及 LDAP 属性映射与过滤器的高级定制。一、两种认证后端File 与 LDAPAuthelia 与认证后端有两种集成方式LDAP用户存储在远程目录服务器中如 OpenLDAP、OpenDJ、FreeIPA、Microsoft Active DirectoryFile用户存储在一个 YAML 文件中密码以哈希形式保存。在源码层面这一抽象体现在 internal/configuration/schema/authentication.go 的AuthenticationBackend结构体中File与LDAP字段均为指针类型配置时二选一即可。与之对应internal/authentication 目录下分别实现了file_user_provider.go文件后端与ldap_user_provider.goLDAP 后端两者共同实现UserProvider接口见 internal/authentication/user_provider.go上层认证流程无需关心后端差异。二、全局配置示例与顶层选项所有第一因子相关配置都位于authentication_backend键下authentication_backend: refresh_interval: 5m password_reset: disable: false custom_url: password_change: disable: falserefresh_interval类型string,integer语法为 duration时长默认值5 minutes必填否该选项控制从后端刷新用户详情的间隔。按重要性排序刷新的详情包括组groups、邮箱地址email、显示名display name。这在以下场景尤为关键File Provider当启用了 watch 文件监听时LDAP Provider一般场景下都建议配置因为用户的组、禁用状态等变化需要及时同步。除标准时长外该选项还接受两个特殊值always始终刷新用户档案disable永不刷新用户档案。需要注意使用 File Provider 时该值的默认行为是always因为文件场景下刷新成本几乎可忽略但用户仍可显式覆盖该设置。从源码看这个特殊类型在 internal/configuration/schema/types.go 中定义为RefreshIntervalDuration它内部通过always、never两个布尔标志区分三种语义并提供Always()、Never()、Update()等查询方法。字符串与整数的解析由 internal/configuration/decode_hooks.go 中的ToRefreshIntervalDurationHookFunc完成它会将always/disable分别转换为NewRefreshIntervalDurationAlways()与NewRefreshIntervalDurationNever()。校验逻辑位于 internal/configuration/validator/authentication.go当值非法时若使用 File 后端则回退为always否则回退为默认的 5 分钟校验错误信息可见 internal/configuration/validator/const.go。password_reset控制用户是否可以通过 Web 前端重置密码。disable类型boolean默认值false必填否设置为true时用户将无法从 Web 前端重置密码。custom_url类型string必填否自定义密码重置 URL。一旦配置为任何非空字符串Authelia 将禁用内置的密码重置功能及其端点并把用户重定向到该自定义 URL。在源码中对应AuthenticationBackendPasswordReset结构体的CustomURL url.URL字段internal/configuration/schema/authentication.go。password_changedisable类型boolean默认值false必填否控制用户是否可以在 Web 前端修改密码区别于重置密码修改密码需要用户已登录。file 与 ldapfile文件认证后端详见 File 配置文档ldapLDAP 认证后端详见 LDAP 配置文档。三、File 后端YAML 用户数据库与哈希参数File 后端的完整配置示例节选自 docs/content/configuration/first-factor/file.mdauthentication_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: 12path类型string必填是指向用户列表文件的路径支持的格式为 YAML参见 Passwords 参考指南 中的 YAML 格式一节。watch类型boolean默认值false必填否启用后Authelia 会监听文件变化并动态重新加载用户数据库无需重启即可应用外部修改。search实验性功能用户搜索选项。注意此功能目前是实验性的。email类型boolean默认值false必填否允许用户使用邮箱地址登录。启用后两个用户不能有相同的邮箱且用户名不能是邮箱格式。邮箱始终使用不区分大小写的方式查找。case_insensitive类型boolean默认值false必填否启用后允许用户以任意大小写组合的用户名登录。启用时用户名的存储必须全部为小写。extra_attributes类型dictionary(object)必填否从目录服务器加载的额外属性。这些属性可用于 Authelia 的其他模块例如 OpenID Connect 1.0 提供方也建议查阅 Attributes 参考指南。此外还可以基于已有属性定义自定义属性见 Definitions: user-attributes。键代表后端属性名数据库将根据multi_valued和value_type配置进行校验。以下示例把目录服务器属性example_file_attribute加载为 Authelia 属性作为单值、底层类型为integer处理authentication_backend: file: extra_attributes: example_file_attribute: multi_valued: false value_type: integervalue_type类型string必填配置了额外属性时必填定义属性的底层类型合法值为string、integer、boolean。multi_valued类型boolean必填否指示底层类型是否可以拥有多个值。源码对应 internal/configuration/schema/authentication.go 的AuthenticationBackendExtraAttribute其ValueType字段的 JSON Schema 枚举值正是boolean、integer、string与文档完全一致。Password Options哈希算法选型关于哈希参数的详细选型建议请参阅专门的 Passwords 参考指南其中包含用户/密码文件的示例。algorithm决定新密码哈希时使用的算法可选值argon2Argon2 算法scryptScrypt 算法pbkdf2PBKDF2 算法sha2cryptSHA2Crypt 算法bcryptBcrypt 算法各算法的参数含义与默认值汇总如下默认值同时可在 internal/configuration/schema/authentication.go 的DefaultPasswordConfig中确认argon2默认算法Argon2 是少数专为密码哈希设计的算法之一也是目前安全性最好的算法之一。默认变体argon2id是最佳实践。参数默认值含义variantargon2id变体合法值argon2id、argon2i、argon2diterations3迭代次数参数 tmemory65536内存用量单位 KiB参数 mparallelism4并行度参数 pkey_length32输出密钥长度salt_length16盐长度scrypt参数默认值含义variantscrypt变体合法值scrypt、yescryptiterations16迭代次数block_size8块大小parallelism1并行度key_length32输出密钥长度salt_length16盐长度pbkdf2variant默认sha512支持sha1、sha224、sha256、sha384、sha512源码枚举见 internal/configuration/schema/authentication.go。不同变体的迭代次数默认值各不相同定义于 internal/configuration/schema/authentication.go整体略高于 NIST FIPS 140 的推荐值以面向未来sha512为 310000、sha384为 280000、sha256为 700000、sha224为 900000、sha1为 1600000。salt_length默认 16。sha2cryptvariant默认sha512推荐sha512合法值sha256、sha512iterations默认50000salt_length默认16bcryptvariant默认standard推荐standard合法值standard、sha256cost默认12注意sha256变体是 Passlib 设计的特殊变体它将密码先通过 SHA256 HMAC 处理再交给 Bcrypt从而绕开 Bcrypt 72 字节的密码截断限制但很多其他系统并不支持该变体。四、LDAP 后端连接、过滤与属性映射LDAP 后端的完整配置示例节选自 docs/content/configuration/first-factor/ldap.md变量如example.com可按需替换authentication_backend: ldap: address: ldap://127.0.0.1 implementation: custom timeout: 5s start_tls: false tls: server_name: ldap.example.com skip_verify: false minimum_version: TLS1.2 maximum_version: TLS1.3 certificate_chain: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- private_key: | -----BEGIN PRIVATE KEY----- ... -----END PRIVATE KEY----- pooling: enable: false count: 5 retries: 2 timeout: 10 seconds base_dn: DCexample,DCcom additional_users_dn: OUusers users_filter: (({username_attribute}{input})(objectClassperson)) additional_groups_dn: OUgroups groups_filter: ((member{dn})(objectClassgroupOfNames)) group_search_mode: filter permit_referrals: false permit_unauthenticated_bind: false permit_feature_detection_failure: false user: CNadmin,DCexample,DCcom password: password attributes: distinguished_name: distinguishedName username: uid display_name: displayName family_name: sn given_name: givenName middle_name: middleName nickname: gender: birthdate: website: wWWHomePage profile: picture: zoneinfo: locale: phone_number: telephoneNumber phone_extension: street_address: streetAddress locality: l region: st postal_code: postalCode country: c mail: mail member_of: memberOf group_name: cn extra: extra_example: name: multi_valued: false value_type: string连接参数address类型string语法为 address必填是LDAP URL格式为[scheme://]hostname[:port]。合法 scheme 为ldap、ldaps、ldapiUnix 域套接字。若路径是绝对路径默认 scheme 为ldapi否则为ldaps。使用ldapi时必须跟随一个 Authelia 进程有权限访问的绝对路径套接字例如ldapi:///var/run/slapd.sock。示例authentication_backend: ldap: address: ldaps://dc1.example.comauthentication_backend: ldap: address: ldap://[fd00:1111:2222:3333::1]implementation类型string默认值custom必填否配置 Authelia 使用的 LDAP 实现主要用于决定过滤器与属性的默认值。可选值见源码 internal/configuration/schema/authentication.go 的枚举custom、activedirectory、rfc2307bis、freeipa、lldap、glauth。各实现的具体默认值定义于同一文件的DefaultLDAPAuthenticationBackendConfigurationImplementation*系列变量中L265-L387例如activedirectory默认用户过滤器会排除禁用账户userAccountControl的ACCOUNTDISABLE位、未设置密码的账户与过期账户并允许用户名或邮箱登录rfc2307bis用户过滤器匹配inetOrgPerson/organizationalPerson组过滤器同时匹配member与uniqueMemberfreeipa过滤器包含nsAccountLock与 Kerberos 密码/主体过期检查lldap预置OUpeople、OUgroups等默认 DN 与过滤器glauth使用posixAccount/posixGroup对象类并排除accountStatusinactive的账户。各实现的详细说明见 LDAP 集成指南。timeout类型string,integer语法为 duration默认值5 seconds必填否拨号建立 LDAP 连接的超时时间。start_tls类型boolean默认值false必填否启用 LDAP StartTLS 流程不常用仅在确实需要时配置。初始连接为明文Authelia 会尝试向 LDAP 服务器升级为 TLS。LDAPS URL 相对更安全。tls类型structure结构为 tls必填否控制与 LDAP 服务器 TLS 连接验证参数。默认情况下 Authelia 使用系统证书信任库验证 TLS 证书可通过全局选项 certificates_directory 扩充信任来源。pooling连接池配置enableboolean默认false启用连接池功能countinteger默认5池中任意时刻保持的打开连接数retriesinteger默认2在超时时间内尝试获取空闲连接的次数相当于把超时时间切分timeoutduration默认20 seconds等待连接变为空闲的最长时间超时则报错。注意文档示例中timeout写为10 seconds而源码默认值为 10 秒internal/configuration/schema/authentication.goLDAP 文档正文中描述为 20 秒实际生效以你的配置为准。搜索范围与过滤器base_dn类型string必填视情况而定situational所有 LDAP 查询的基础 distinguished name 容器。若 LDAP 域为example.com通常为DCexample,DCcom也可以更精确地限定到某个 OU如OUauthelia,DCexample,DCcom。用户搜索时前缀additional_users_dn组搜索时前缀additional_groups_dn。additional_users_dn类型string必填否追加到base_dn之后的额外 LDAP 路径用于限制从哪个 OU 获取用户出于安全或性能考虑。例如base_dn为DCexample,DCcom时设置为OUusers,OUpeople则用户搜索发生在OUusers,OUpeople,DCexample,DCcom。users_filter类型string必填视情况而定用于缩小有效用户范围的 LDAP 过滤器必须正确设置以排除已禁用用户。该选项技术上必填但implementation可隐式设置默认值从而免除该要求见各实现的过滤器默认值。默认值依赖implementation。additional_groups_dn类型string必填否与additional_users_dn类似但作用于组搜索。groups_filter类型string必填视情况而定与users_filter类似但作用于组搜索。若要包含用户非直接所属、而是通过嵌套组间接所属的组递归组可尝试以下过滤器目前仅在 Microsoft Active Directory 上测试过((member:1.2.840.113556.1.4.1941:{dn})(objectClassgroup)(objectCategorygroup))group_search_mode类型string默认值filter必填否控制用户组的发现方式。默认值filter直接使用过滤器确定结果memberof实验性模式则执行一次额外的特殊过滤搜索。两种模式详见 LDAP 集成文档filter 模式默认模式一般推荐memberof 模式特殊搜索模式一般不建议使用目前为实验性。它利用目录服务器提供的memberOf属性来确定组成员关系搜索在配置的 base 下以子树范围执行组过滤器必须包含{memberof:*}系列替换符搜索结果中的 distinguished name 与用户memberOf属性做不区分大小写的比较。使用前提包括组必须在配置的搜索 base 内memberOf属性必须包含组的 DN使用{memberof:dn}时 DN 必须可被目录服务器搜索。permit_referrals类型boolean默认值false必填否允许跟随 LDAP 引用referrals。如果架构中存在只读服务器执行写操作时可能需要跟随引用。permit_unauthenticated_bind类型boolean默认值false必填否强烈不建议启用建议禁用 LDAP 服务器的匿名绑定并使用服务账户。启用后允许不带密码绑定服务器前提是password配置为空且 password_reset 的 disable 为true。绑定凭证user类型string必填是用于绑定执行查找与密码修改操作的用户 distinguished name与password配对。password类型string敏感值必填是与user配对的绑定密码。强烈建议使用 64 位及以上长度的随机字母数字字符串参见 生成安全值指南并把该服务账户的密码修改为此值。attributes目录属性映射以下选项配置目录服务器属性与 Authelia 内部字段的映射。建议同时查阅 Attributes 参考指南。distinguished_namesituational包含 distinguished name 的属性主要用于过滤搜索。注意区分对象实际的 DN与表示 DN 的属性并非所有目录都有可搜索的 DN 属性目前已知仅 Active Directory 支持。usernamesituational映射到 Authelia 用户名的目录属性该属性的映射值必须包含{username_attribute}占位符。display_namesituational登录后显示在 Web UI 上的用户显示名。family_name/given_name/middle_name姓氏、名、中间名。nickname/gender/birthdate昵称、性别、出生日期。website/profile/picture网站 URL、个人主页 URL、头像 URL。zoneinfo用户时区值来自 IANA 时区数据库。locale用户区域设置采用 RFC5646 BCP 47 格式。phone_number/phone_extension电话号码与分机。street_address/locality/region/postal_code/country街道地址、城市、省/州、邮政编码、国家。mailsituational用户邮箱属性。对设备注册和密码重置流程至关重要——用户必须有邮箱Authelia 才能在其尝试重置密码或注册第二因子设备时执行身份验证。member_ofsituational用户所属组的属性目前仅用于memberof组搜索模式。group_namesituationalAuthelia 用于确定组名的目录属性。以上多数必填标注为 situational 的选项均可由implementation隐式设置默认值而免除显式配置。extra扩展属性类型dictionary(object)必填否从目录服务器加载的额外属性可用于 OpenID Connect 1.0 等场景。键代表后端属性名默认同时也是 Authelia 内部属性名。以下示例把目录服务器属性exampleServerAttribute加载为 Authelia 属性example_authelia_attribute按单值、底层类型integer处理authentication_backend: ldap: attributes: extra: exampleServerAttribute: name: example_authelia_attribute multi_valued: false value_type: integernamestring非必填更改 Authelia 内部引用的属性名不改变从 LDAP 服务器查询的属性value_typestring必填定义属性底层类型合法值为string、integer、boolean使用integer/boolean时目录属性必须可解析multi_valuedboolean非必填指示属性是否可为多值。五、刷新间隔与 LDAP 安全建议刷新间隔建议建议使用默认的 refresh_interval 或将其配置为足够低的值以便及时刷新用户组和状态删除、禁用等充分保障环境安全。唯一标识约束用户必须由某个属性唯一标识该属性必须为单值且由管理员保证唯一。若多个用户拥有相同值Authelia 将直接拒绝该用户认证并在日志中显示错误。为避免此类问题强烈建议遵循 RFC2307Active Directory 使用sAMAccountName其他实现使用uid作为用户唯一标识属性。六、过滤器占位符Placeholder机制LDAP 用户与组过滤器中支持多种占位符替换详见 LDAP 集成文档。替换分为**启动阶段startup与搜索阶段search**两类前者在建立连接前替换一次后者在每次 LDAP 搜索时替换——这种划分是为了优化性能避免在每次搜索时执行所有可能的替换。通用占位符占位符阶段替换内容{distinguished_name_attribute}startup配置的 distinguished name 属性{username_attribute}startup配置的用户名属性{mail_attribute}startup配置的邮箱属性{display_name_attribute}startup配置的显示名属性{member_of_attribute}startup配置的 member of 属性{input}search用户名输入框的输入值用户过滤器占位符占位符阶段替换内容{date-time:generalized}search当前 UTC 时间LDAP generalized time 格式20060102150405.0Z{date-time:unix}search当前时间Unix 时间戳{date-time:microsoft-nt}search当前时间Microsoft NT 纪元某些 Active Directory 属性使用组过滤器占位符占位符阶段替换内容{username}search从用户名属性获得的用户名{dn}search从档案查询获得的 distinguished name{memberof:dn}search详见下文{memberof:rdn}search仅限memberof搜索模式包含用户每条memberOf条目的第一个相对 DN括号包裹其中{memberof:rdn}会把用户memberOf的每个值拆分出第一个相对 DN 并用括号包裹拼接例如用户拥有CNabc,OUgroups,DCexample,DCcom与CNxyz,OUgroups,DCexample,DCcom时替换结果为(CNabc)(CNxyz)配合建议的(|{memberof:rdn})模式即构成(|(CNabc)(CNxyz))用于匹配任何CN为abc或xyz的组。{memberof:dn}的启用前提必须使用memberof搜索模式、必须配置 distinguished name 属性、且目录服务器必须支持按 DN 属性搜索许多目录服务没有DN 属性需注意。七、源码视角认证链与测试验证从实现层面理解第一因子认证的完整链路有助于排查配置问题配置结构AuthenticationBackend及其子结构体完整定义了本文所有选项的默认值与 JSON Schema 约束internal/configuration/schema/authentication.go包括各哈希算法的参数取值范围如 Argon2memory最小 8、iterations默认 3 等。默认配置DefaultPasswordConfig与各DefaultLDAPAuthenticationBackendConfigurationImplementation*变量集中定义了 File 与 LDAP 后端的出厂默认值DefaultCIPasswordConfig则提供了 CI 场景下降低资源消耗的替代默认值internal/configuration/schema/authentication.go。凭据缓存LDAP 场景下密码校验性能开销较大internal/authentication/cached.go 中的CredentialCacheHMAC实现了基于 HMAC 的内存凭据缓存配合singleflight合并并发请求缓存条目带过期时间从侧面解释了为什么 LDAP 后端的refresh_interval需要谨慎权衡安全与性能。测试佐证refresh_interval的解析与默认值逻辑有完整单元测试覆盖例如 internal/configuration/decode_hooks_test.go 验证了各种时长字符串、always/disable的转换与非法值报错internal/configuration/validator/authentication_test.go 则验证了 File 后端默认回退为always、LDAP 后端默认 5 分钟等行为。八、总结第一因子认证是 Authelia 多因子体系的基础其核心配置决策可归纳为三点后端选型中小规模或想快速上手选择 File 后端YAML 用户文件 哈希密码已有目录服务器Active Directory、FreeIPA、OpenLDAP 等选择 LDAP 后端并善用implementation预设哈希与刷新策略File 后端默认使用 Argon2id 提供强密码哈希无论哪种后端都应根据安全要求配置refresh_interval及时同步用户组与禁用状态LDAP 细节正确配置base_dn、用户/组过滤器善用占位符与递归组过滤器、属性映射尤其是mail与唯一标识属性遵循 RFC2307 保证用户唯一性。继续深入可阅读LDAP 集成指南、Passwords 参考指南、Attributes 参考指南以及源码 internal/authentication 与 internal/configuration 目录下的对应实现。【免费下载链接】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），仅供参考