Authelia WebAuthn 参考指南推荐配置、Passkey 登录与 FIDO 元数据状态【免费下载链接】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 官方参考文档docs/content/reference/guides/webauthn.md展开系统梳理 WebAuthn 的推荐安全配置含 NIST 合规的 Passkey 方案以及 FIDO Metadata ServiceMDS3状态值的完整语义并结合仓库源码说明这些配置在注册、认证与校验链路上的实际作用。读完本文你将能够为 Authelia 配置一套可信、可审计的 WebAuthn/Passkey 二因素方案并理解 AAGUID、attestation、authenticator status 等概念在源码中的落地方式。为什么需要 WebAuthn 参考指南Authelia 在引入 WebAuthn 之初配置项非常基础随着版本演进官方加入了大量面向安全与信任的选项attestation 偏好、AAGUID 过滤、备份资格限制、MDS3 元数据校验等用于充分利用现代浏览器与 FIDO 认证器提供的能力。参考指南正是为这些高级能力给出的权威说明其核心内容分为两块推荐配置Recommended Configurations针对 Passkey 场景给出符合 NIST 建议的完整 YAML 配置。元数据状态Metadata Status列出 MDS3 blob 中可用于过滤认证器的全部状态值及其安全含义。这两块内容与官方 WebAuthn 配置文档互为补充参考指南回答应该怎么配与这些状态值代表什么配置文档回答每个参数是什么。推荐配置Passkey 与 NIST 合规基线指南开篇强调随着时间推移 Authelia 增加了大量安全与信任导向security and trust focused的选项以便充分利用可用技术。以下配置即官方给出的、符合 NIST 建议的 Passkey 配置# yaml-language-server: $schemahttps://www.authelia.com/schemas/latest/json-schema/configuration.json webauthn: enable_passkey_login: true attestation_conveyance_preference: direct filtering: prohibit_backup_eligibility: true metadata: enabled: true validate_trust_anchor: true validate_entry: true validate_status: true validate_entry_permit_zero_aaguid: false这份配置在源码层面有清晰的对应关系。配置结构体定义在 internal/configuration/schema/webauthn.go 的WebAuthn、WebAuthnMetadata、WebAuthnFiltering等类型中其默认值与文档一致例如attestation_conveyance_preference默认为indirect、timeout默认为 60 秒、metadata.enabled默认为false见 DefaultWebAuthnConfiguration。逐项解读推荐配置的含义配置项推荐值作用enable_passkey_logintrue允许用户使用 Passkey 代替用户名 密码登录此登录只算单因素若请求需要多因素认证用户仍会被提示输入密码attestation_conveyance_preferencedirect要求认证器直接签名生成 attestation statement从而能够收集 AAGUID 等认证器模型信息供元数据校验使用filtering.prohibit_backup_eligibilitytrue禁止注册具备凭证导出能力的认证器backup eligible从而大概率阻止同步凭证如跨设备云同步的 Passkey注册metadata.enabledtrue开启 MDS3 元数据服务校验下载约 5MB 的 metadata blob 存入存储后端metadata.validate_trust_anchortrue校验 attestation 证书链是否可追溯到 MDS3 blob 中已认可的 CA 证书推荐保持默认metadata.validate_entrytrue校验认证器的 AAGUID 是否在 MDS3 中有登记条目这是验证认证器真实性的前提metadata.validate_statustrue校验认证器条目的状态默认会拒绝已被判定为失陷/吊销的认证器metadata.validate_entry_permit_zero_aaguidfalse不允许空 AAGUID 的认证器通过部分未做 FIDO 认证的厂商可能返回空 AAGUID需要时才打开配置提示enable_passkey_login与remember_me的联动行为请参阅会话配置说明中关于remember_me的说明开启 Passkey 登录后的常见疑问如同步凭证、跨设备行为见安全密钥 FAQ。校验器对推荐配置的约束配置校验逻辑位于 internal/configuration/validator/webauthn.go。从源码看以下组合会被拒绝enable_passkey_login: true与disable: true冲突错误信息errFmtWebAuthnBoolean两个实验性选项experimental_enable_passkey_uv_two_factors、experimental_enable_passkey_upgrade都要求enable_passkey_login先开启filtering.permitted_aaguids与filtering.prohibited_aaguids互斥不能同时设置metadata.cache_policy只能是strict或relaxed。此外attestation_conveyance_preference的合法值限定为none、indirect、direct见 const.go 中validWebAuthnConveyancePreferencesuser_verification、attachment、discoverability也都有各自的枚举约束。配置项全景从参考指南到配置文档参考指南提到的能力在WebAuthn 配置文档中有完整参数级说明。以下按功能域分组与源码中的结构体一一对应基础开关与外观disableboolean默认false设为true时整体禁用 WebAuthn。enable_passkey_loginboolean默认false启用 Passkey 单因素登录。该选项映射到源码结构体字段WebAuthn.EnablePasskeyLogin。experimental_enable_passkey_uv_two_factorsboolean默认false实验性选项允许强制执行用户验证PIN、生物识别等且上报已执行 user verification 的认证器满足访问控制规则中的two_factor策略。官方在配置文档中标注为不受支持、完全实验性未来会被细粒度授权路线图中定义的 custom policy flows 取代该功能上线后此选项会导致启动失败。experimental_enable_passkey_upgradeboolean默认false实验性选项。部分认证器/浏览器无法正确上报新注册凭证是否为 Passkey规范要求此时按非 Passkey处理但会造成用户困惑开启后 Authelia 会尝试自动把这类凭证升级为 Passkey。官方明确该选项未来会被移除可能变为 UI 内的明确流程、自动流程或彻底删除。display_namestring默认Authelia发送给客户端展示的依赖方显示名具体展示方式由浏览器/操作系统决定。timeoutduration默认60 secondsWebAuthn 交互的超时时间源码默认值见 DefaultWebAuthnConfigurationtime.Second * 60。attestation_conveyance_preference控制 attestation 的传达conveyancing偏好。传达允许收集认证器的 attestation statement如 AAGUID用于标识认证器型号。合法值值说明none指示客户端不进行 attestation 传达indirect指示客户端进行传达但允许客户端自行选择方式包括使用第三方匿名 CAdirect指示客户端传达由认证器直接签名的 attestation statement推荐配置采用此值源码类型为protocol.ConveyancePreference合法枚举定义在 const.govalidWebAuthnConveyancePreferences。filtering注册期过滤permitted_aaguidslist of UUID仅允许列表中的 AAGUID 注册适合公司强制使用指定型号认证器的策略。与prohibited_aaguids互斥。prohibited_aaguidslist of UUID禁止列表中的 AAGUID 注册适合公司禁止特定型号认证器的策略。与permitted_aaguids互斥。prohibit_backup_eligibilityboolean默认false设为true时声称具备凭证导出能力backup eligible的认证器无法注册通常会阻止同步凭证注册。上述过滤在注册流程中的实际执行位于 internal/webauthn/credential.go 的VerifyCredential它依次检查 attestation 是否存在、通过 MDS 验证凭证、设置AttestationType随后判断BackupEligible对应IsProhibitedBackupEligibility并在PermittedAAGUIDs/ProhibitedAAGUIDs列表中匹配 AAGUID对应IsProhibitedAAGUID。校验失败时注册接口会返回 403见 handler_register_webauthn.go 中WebAuthnRegistrationPOST调用iwebauthn.ValidateCredentialAllowed的逻辑。selection_criteria认证器选择偏好attachment默认空新建凭证的附着偏好。空值表示展示可用认证器让用户自行选择cross-platform表示可跨设备移动的物理安全密钥platform表示平台内置认证器Windows Hello、Apple ID 等。discoverability默认preferred可发现性偏好可能影响 Passkey 的创建。discouraged表示尽量不可发现preferred倾向可发现但不可发现时不报错required强制可发现、不可发现时报错。源码类型为protocol.ResidentKeyRequirement。user_verification默认preferred用户验证偏好。discouraged倾向不要求验证preferred在认证器支持时要求验证required强制验证、不支持则失败。源码类型为protocol.UserVerificationRequirement。metadataMDS3 元数据服务enabledboolean默认false开启认证器与凭证的元数据服务校验。需要下载 metadata service blob约占用存储后端 5MB 数据。官方建议用户花时间配置此项。cache_policy默认strict元数据缓存的运行模式。strict在启动时尝试下载新副本失败则报错relaxed同样尝试下载但若已有未过期的缓存版本遇到元数据服务返回429 Too Many Requests时只记录错误日志。对应常量定义在 internal/webauthn/const.goCachePolicyStrict/CachePolicyRelaxed。validate_trust_anchorboolean默认true校验 attestation 证书是否可追溯到已验证 MDS3 blob 中的 CA 证书。官方强烈建议保持默认。validate_entryboolean默认true校验认证器在 MDS3 blob 中是否有条目。注意这可能会排除没有 FIDO 合规认证或未向 MDS3 登记的认证器官方建议保持默认因为缺少该校验就无法验证认证器的真实性。validate_entry_permit_zero_aaguidboolean默认false允许提供了空 AAGUID 的认证器。部分未取得 FIDO 合规认证的认证器可能需要开启。validate_statusboolean默认true校验 attestation 条目状态。一般没有理由关闭因为默认被排除的认证器大概率已失陷。validate_status_permittedlist of string认证器通过校验所必须处于的状态列表白名单。合法值见下文元数据状态。validate_status_prohibitedlist of string禁止注册的认证器状态列表黑名单。官方强烈建议不要修改默认值。默认配置为REVOKED、USER_KEY_PHYSICAL_COMPROMISE、USER_KEY_REMOTE_COMPROMISE、USER_VERIFICATION_BYPASS、ATTESTATION_KEY_COMPROMISE见 DefaultWebAuthnConfiguration。元数据校验在源码中的落地MDS3 集成位于 internal/webauthn/metadata.goNewMetaDataProvider依据config.WebAuthn.Metadata.Enabled决定是否构建StoreCachedMetadataProvider内存 provider 通过newMetadataProviderMemory把ValidateEntry、ValidateEntryPermitZeroAAGUID、ValidateTrustAnchor、ValidateStatus、ValidateStatusPermitted/Prohibited逐一映射到底层memoryprovider 的选项中。productionMDS3Provider.FetchMDS3向 FIDO 生产 MDS3 端点发起请求使用If-None-Match携带当前 blob 编号做条件请求返回200 OK时读取新 blob304 Not Modified时复用缓存429 Too Many Requests时报错与cache_policy: relaxed的降级行为对应。缓存写入存储后端的mds3键cacheMDS3常量通过storage.CachedDataProvider的LoadCachedData/SaveCachedData持久化。这与配置文档中约占用存储 5MB的说明一致。StartupCheck在启动时执行初始化尝试拉取最新元数据strict策略下失败即返回错误导致启动失败relaxed策略下仅记录 Debug 日志同时会检查缓存是否过期、是否加载到了任何元数据。元数据状态Metadata Status全表配置中的validate_status_permitted与validate_status_prohibited允许基于元数据状态过滤认证器。以下为参考指南给出的全部状态值及其官方语义validate_status_permitted/prohibited的合法枚举与之一致见 schema/webauthn.go 的 jsonschema enum 定义值说明NOT_FIDO_CERTIFIED该认证器未通过 FIDO 认证FIDO_CERTIFIED认证器已通过 FIDO 功能认证该认证体系已逐步淘汰将由FIDO_CERTIFIED_L1取代FIDO_CERTIFIED_L1认证器已通过 FIDO Authenticator 一级认证比FIDO_CERTIFIED更严格的新一代认证FIDO_CERTIFIED_L1plus认证器已通过 FIDO Authenticator 一级认证严格程度高于一级FIDO_CERTIFIED_L2认证器已通过 FIDO Authenticator 二级认证严格程度高于一级FIDO_CERTIFIED_L2plus认证器已通过 FIDO Authenticator 二级认证严格程度高于二级FIDO_CERTIFIED_L3认证器已通过 FIDO Authenticator 三级认证严格程度高于二级FIDO_CERTIFIED_L3plus认证器已通过 FIDO Authenticator 三级认证严格程度高于三级USER_VERIFICATION_BYPASS安全风险恶意软件能够绕过用户验证认证器可能在用户不知情、未同意的情况下被使用ATTESTATION_KEY_COMPROMISE安全风险该认证器的 attestation 密钥已知被攻陷。依赖方应检查证书字段以定位受影响的批次若未提供证书字段应拒绝该认证器的所有新注册。厂商应将日期设为失陷发生日USER_KEY_REMOTE_COMPROMISE安全风险该认证器存在允许已注册密钥被攻陷的弱点如弱熵导致可预测密钥、或侧信道允许伪造/猜测/提取密钥或签名不应被信任USER_KEY_PHYSICAL_COMPROMISE安全风险与上一条相同的信任结论但失陷途径为物理侧如物理侧信道允许伪造/猜测/提取密钥或签名不应被信任UPDATE_AVAILABLE设备有可用的软件或固件更新REVOKEDFIDO 联盟认定该认证器因任何原因如已知是欺诈产品或含有蓄意后门都不应被信任依赖方应拒绝该型号认证器的任何未来注册SELF_ASSERTION_SUBMITTED认证器厂商已完成并提交自我认证清单给 FIDO 联盟若该清单公开其 URL 会记录在url字段如何选择 permitted / prohibitedvalidate_status_permitted白名单模式只有状态命中列表的认证器才通过校验。官方在 schema 注释中提示通常不鼓励使用。validate_status_prohibited黑名单模式命中列表的认证器一律拒绝注册。默认值已包含 5 个安全风险状态REVOKED、USER_KEY_PHYSICAL_COMPROMISE、USER_KEY_REMOTE_COMPROMISE、USER_VERIFICATION_BYPASS、ATTESTATION_KEY_COMPROMISE官方强烈建议不要改动默认值因为被默认排除的认证器很可能已被攻陷。注意 schema 枚举中的状态名与文档表格略有差异源码枚举使用FIDO_NOT_CERTIFIED对应表格中的NOT_FIDO_CERTIFIED配置时以各自上下文为准——validate_status_*参考本表及 schema 枚举。注册与校验链路配置如何影响实际流程把参考指南的配置落到真实请求链路上可以帮助理解为什么推荐配置是安全的。以 handler_register_webauthn.go 为例挑战阶段WebAuthnRegistrationPUT校验用户会话与描述字段1~64 字符、不可与已有凭证重名随后BeginRegistration生成 attestation challenge。值得注意的是注册请求的加密算法参数覆盖了 MLDSAML-DSA-44/65/87后量子密码、EdDSA、ES256/384/512、RS256/384/512、PS256/384/512——这与 Authelia 项目Post-Quantum Cryptography Ready的定位一致。响应阶段WebAuthnRegistrationPOST解析客户端响应、CreateCredential创建凭证后调用ValidateCredentialAllowed即上文VerifyCredential执行 MDS 验证与 AAGUID/backup eligibility 过滤全部通过后才SaveWebAuthnCredential持久化并记录审计事件。Passkey 登录FirstFactorPasskeyGET等见 handler_firstfactor_passkey.go使用BeginDiscoverableLogin发起可发现凭证断言此时enable_passkey_login与discoverability的配置直接决定登录体验与凭证类型。元数据校验失败如 AAGUID 未登记、状态为REVOKED会体现在VerifyCredentialResult的MetaDataValidationError等字段中最终注册被拒绝——这正是参考指南推荐开启validate_entry、validate_status的底层原因。实践建议小结新部署直接采用推荐配置将本文第一节的 YAML 作为 Passkey 场景基线配合配置文档按需调整timeout、display_name与selection_criteria。谨慎对待实验性选项experimental_enable_passkey_uv_two_factors与experimental_enable_passkey_upgrade均不被官方支持且未来会变更/移除生产环境应避免依赖。默认禁止状态保持不动validate_status_prohibited的默认 5 项是失陷认证器的安全底线如需白名单化可研究validate_status_permitted但先评估对现有用户凭证的影响。关注存储与启动行为开启metadata.enabled会占用约 5MB 存储用于缓存 MDS3 blob见存储配置说明cache_policy: strict下启动拉取失败会直接报错离线环境可评估relaxed。联动文档Passkey 与remember_me的行为见会话配置常见疑问见安全密钥 FAQ实验性选项的演进方向见细粒度授权路线图。【免费下载链接】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 WebAuthn 参考指南：推荐配置、Passkey 登录与 FIDO 元数据状态
Authelia WebAuthn 参考指南推荐配置、Passkey 登录与 FIDO 元数据状态【免费下载链接】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 官方参考文档docs/content/reference/guides/webauthn.md展开系统梳理 WebAuthn 的推荐安全配置含 NIST 合规的 Passkey 方案以及 FIDO Metadata ServiceMDS3状态值的完整语义并结合仓库源码说明这些配置在注册、认证与校验链路上的实际作用。读完本文你将能够为 Authelia 配置一套可信、可审计的 WebAuthn/Passkey 二因素方案并理解 AAGUID、attestation、authenticator status 等概念在源码中的落地方式。为什么需要 WebAuthn 参考指南Authelia 在引入 WebAuthn 之初配置项非常基础随着版本演进官方加入了大量面向安全与信任的选项attestation 偏好、AAGUID 过滤、备份资格限制、MDS3 元数据校验等用于充分利用现代浏览器与 FIDO 认证器提供的能力。参考指南正是为这些高级能力给出的权威说明其核心内容分为两块推荐配置Recommended Configurations针对 Passkey 场景给出符合 NIST 建议的完整 YAML 配置。元数据状态Metadata Status列出 MDS3 blob 中可用于过滤认证器的全部状态值及其安全含义。这两块内容与官方 WebAuthn 配置文档互为补充参考指南回答应该怎么配与这些状态值代表什么配置文档回答每个参数是什么。推荐配置Passkey 与 NIST 合规基线指南开篇强调随着时间推移 Authelia 增加了大量安全与信任导向security and trust focused的选项以便充分利用可用技术。以下配置即官方给出的、符合 NIST 建议的 Passkey 配置# yaml-language-server: $schemahttps://www.authelia.com/schemas/latest/json-schema/configuration.json webauthn: enable_passkey_login: true attestation_conveyance_preference: direct filtering: prohibit_backup_eligibility: true metadata: enabled: true validate_trust_anchor: true validate_entry: true validate_status: true validate_entry_permit_zero_aaguid: false这份配置在源码层面有清晰的对应关系。配置结构体定义在 internal/configuration/schema/webauthn.go 的WebAuthn、WebAuthnMetadata、WebAuthnFiltering等类型中其默认值与文档一致例如attestation_conveyance_preference默认为indirect、timeout默认为 60 秒、metadata.enabled默认为false见 DefaultWebAuthnConfiguration。逐项解读推荐配置的含义配置项推荐值作用enable_passkey_logintrue允许用户使用 Passkey 代替用户名 密码登录此登录只算单因素若请求需要多因素认证用户仍会被提示输入密码attestation_conveyance_preferencedirect要求认证器直接签名生成 attestation statement从而能够收集 AAGUID 等认证器模型信息供元数据校验使用filtering.prohibit_backup_eligibilitytrue禁止注册具备凭证导出能力的认证器backup eligible从而大概率阻止同步凭证如跨设备云同步的 Passkey注册metadata.enabledtrue开启 MDS3 元数据服务校验下载约 5MB 的 metadata blob 存入存储后端metadata.validate_trust_anchortrue校验 attestation 证书链是否可追溯到 MDS3 blob 中已认可的 CA 证书推荐保持默认metadata.validate_entrytrue校验认证器的 AAGUID 是否在 MDS3 中有登记条目这是验证认证器真实性的前提metadata.validate_statustrue校验认证器条目的状态默认会拒绝已被判定为失陷/吊销的认证器metadata.validate_entry_permit_zero_aaguidfalse不允许空 AAGUID 的认证器通过部分未做 FIDO 认证的厂商可能返回空 AAGUID需要时才打开配置提示enable_passkey_login与remember_me的联动行为请参阅会话配置说明中关于remember_me的说明开启 Passkey 登录后的常见疑问如同步凭证、跨设备行为见安全密钥 FAQ。校验器对推荐配置的约束配置校验逻辑位于 internal/configuration/validator/webauthn.go。从源码看以下组合会被拒绝enable_passkey_login: true与disable: true冲突错误信息errFmtWebAuthnBoolean两个实验性选项experimental_enable_passkey_uv_two_factors、experimental_enable_passkey_upgrade都要求enable_passkey_login先开启filtering.permitted_aaguids与filtering.prohibited_aaguids互斥不能同时设置metadata.cache_policy只能是strict或relaxed。此外attestation_conveyance_preference的合法值限定为none、indirect、direct见 const.go 中validWebAuthnConveyancePreferencesuser_verification、attachment、discoverability也都有各自的枚举约束。配置项全景从参考指南到配置文档参考指南提到的能力在WebAuthn 配置文档中有完整参数级说明。以下按功能域分组与源码中的结构体一一对应基础开关与外观disableboolean默认false设为true时整体禁用 WebAuthn。enable_passkey_loginboolean默认false启用 Passkey 单因素登录。该选项映射到源码结构体字段WebAuthn.EnablePasskeyLogin。experimental_enable_passkey_uv_two_factorsboolean默认false实验性选项允许强制执行用户验证PIN、生物识别等且上报已执行 user verification 的认证器满足访问控制规则中的two_factor策略。官方在配置文档中标注为不受支持、完全实验性未来会被细粒度授权路线图中定义的 custom policy flows 取代该功能上线后此选项会导致启动失败。experimental_enable_passkey_upgradeboolean默认false实验性选项。部分认证器/浏览器无法正确上报新注册凭证是否为 Passkey规范要求此时按非 Passkey处理但会造成用户困惑开启后 Authelia 会尝试自动把这类凭证升级为 Passkey。官方明确该选项未来会被移除可能变为 UI 内的明确流程、自动流程或彻底删除。display_namestring默认Authelia发送给客户端展示的依赖方显示名具体展示方式由浏览器/操作系统决定。timeoutduration默认60 secondsWebAuthn 交互的超时时间源码默认值见 DefaultWebAuthnConfigurationtime.Second * 60。attestation_conveyance_preference控制 attestation 的传达conveyancing偏好。传达允许收集认证器的 attestation statement如 AAGUID用于标识认证器型号。合法值值说明none指示客户端不进行 attestation 传达indirect指示客户端进行传达但允许客户端自行选择方式包括使用第三方匿名 CAdirect指示客户端传达由认证器直接签名的 attestation statement推荐配置采用此值源码类型为protocol.ConveyancePreference合法枚举定义在 const.govalidWebAuthnConveyancePreferences。filtering注册期过滤permitted_aaguidslist of UUID仅允许列表中的 AAGUID 注册适合公司强制使用指定型号认证器的策略。与prohibited_aaguids互斥。prohibited_aaguidslist of UUID禁止列表中的 AAGUID 注册适合公司禁止特定型号认证器的策略。与permitted_aaguids互斥。prohibit_backup_eligibilityboolean默认false设为true时声称具备凭证导出能力backup eligible的认证器无法注册通常会阻止同步凭证注册。上述过滤在注册流程中的实际执行位于 internal/webauthn/credential.go 的VerifyCredential它依次检查 attestation 是否存在、通过 MDS 验证凭证、设置AttestationType随后判断BackupEligible对应IsProhibitedBackupEligibility并在PermittedAAGUIDs/ProhibitedAAGUIDs列表中匹配 AAGUID对应IsProhibitedAAGUID。校验失败时注册接口会返回 403见 handler_register_webauthn.go 中WebAuthnRegistrationPOST调用iwebauthn.ValidateCredentialAllowed的逻辑。selection_criteria认证器选择偏好attachment默认空新建凭证的附着偏好。空值表示展示可用认证器让用户自行选择cross-platform表示可跨设备移动的物理安全密钥platform表示平台内置认证器Windows Hello、Apple ID 等。discoverability默认preferred可发现性偏好可能影响 Passkey 的创建。discouraged表示尽量不可发现preferred倾向可发现但不可发现时不报错required强制可发现、不可发现时报错。源码类型为protocol.ResidentKeyRequirement。user_verification默认preferred用户验证偏好。discouraged倾向不要求验证preferred在认证器支持时要求验证required强制验证、不支持则失败。源码类型为protocol.UserVerificationRequirement。metadataMDS3 元数据服务enabledboolean默认false开启认证器与凭证的元数据服务校验。需要下载 metadata service blob约占用存储后端 5MB 数据。官方建议用户花时间配置此项。cache_policy默认strict元数据缓存的运行模式。strict在启动时尝试下载新副本失败则报错relaxed同样尝试下载但若已有未过期的缓存版本遇到元数据服务返回429 Too Many Requests时只记录错误日志。对应常量定义在 internal/webauthn/const.goCachePolicyStrict/CachePolicyRelaxed。validate_trust_anchorboolean默认true校验 attestation 证书是否可追溯到已验证 MDS3 blob 中的 CA 证书。官方强烈建议保持默认。validate_entryboolean默认true校验认证器在 MDS3 blob 中是否有条目。注意这可能会排除没有 FIDO 合规认证或未向 MDS3 登记的认证器官方建议保持默认因为缺少该校验就无法验证认证器的真实性。validate_entry_permit_zero_aaguidboolean默认false允许提供了空 AAGUID 的认证器。部分未取得 FIDO 合规认证的认证器可能需要开启。validate_statusboolean默认true校验 attestation 条目状态。一般没有理由关闭因为默认被排除的认证器大概率已失陷。validate_status_permittedlist of string认证器通过校验所必须处于的状态列表白名单。合法值见下文元数据状态。validate_status_prohibitedlist of string禁止注册的认证器状态列表黑名单。官方强烈建议不要修改默认值。默认配置为REVOKED、USER_KEY_PHYSICAL_COMPROMISE、USER_KEY_REMOTE_COMPROMISE、USER_VERIFICATION_BYPASS、ATTESTATION_KEY_COMPROMISE见 DefaultWebAuthnConfiguration。元数据校验在源码中的落地MDS3 集成位于 internal/webauthn/metadata.goNewMetaDataProvider依据config.WebAuthn.Metadata.Enabled决定是否构建StoreCachedMetadataProvider内存 provider 通过newMetadataProviderMemory把ValidateEntry、ValidateEntryPermitZeroAAGUID、ValidateTrustAnchor、ValidateStatus、ValidateStatusPermitted/Prohibited逐一映射到底层memoryprovider 的选项中。productionMDS3Provider.FetchMDS3向 FIDO 生产 MDS3 端点发起请求使用If-None-Match携带当前 blob 编号做条件请求返回200 OK时读取新 blob304 Not Modified时复用缓存429 Too Many Requests时报错与cache_policy: relaxed的降级行为对应。缓存写入存储后端的mds3键cacheMDS3常量通过storage.CachedDataProvider的LoadCachedData/SaveCachedData持久化。这与配置文档中约占用存储 5MB的说明一致。StartupCheck在启动时执行初始化尝试拉取最新元数据strict策略下失败即返回错误导致启动失败relaxed策略下仅记录 Debug 日志同时会检查缓存是否过期、是否加载到了任何元数据。元数据状态Metadata Status全表配置中的validate_status_permitted与validate_status_prohibited允许基于元数据状态过滤认证器。以下为参考指南给出的全部状态值及其官方语义validate_status_permitted/prohibited的合法枚举与之一致见 schema/webauthn.go 的 jsonschema enum 定义值说明NOT_FIDO_CERTIFIED该认证器未通过 FIDO 认证FIDO_CERTIFIED认证器已通过 FIDO 功能认证该认证体系已逐步淘汰将由FIDO_CERTIFIED_L1取代FIDO_CERTIFIED_L1认证器已通过 FIDO Authenticator 一级认证比FIDO_CERTIFIED更严格的新一代认证FIDO_CERTIFIED_L1plus认证器已通过 FIDO Authenticator 一级认证严格程度高于一级FIDO_CERTIFIED_L2认证器已通过 FIDO Authenticator 二级认证严格程度高于一级FIDO_CERTIFIED_L2plus认证器已通过 FIDO Authenticator 二级认证严格程度高于二级FIDO_CERTIFIED_L3认证器已通过 FIDO Authenticator 三级认证严格程度高于二级FIDO_CERTIFIED_L3plus认证器已通过 FIDO Authenticator 三级认证严格程度高于三级USER_VERIFICATION_BYPASS安全风险恶意软件能够绕过用户验证认证器可能在用户不知情、未同意的情况下被使用ATTESTATION_KEY_COMPROMISE安全风险该认证器的 attestation 密钥已知被攻陷。依赖方应检查证书字段以定位受影响的批次若未提供证书字段应拒绝该认证器的所有新注册。厂商应将日期设为失陷发生日USER_KEY_REMOTE_COMPROMISE安全风险该认证器存在允许已注册密钥被攻陷的弱点如弱熵导致可预测密钥、或侧信道允许伪造/猜测/提取密钥或签名不应被信任USER_KEY_PHYSICAL_COMPROMISE安全风险与上一条相同的信任结论但失陷途径为物理侧如物理侧信道允许伪造/猜测/提取密钥或签名不应被信任UPDATE_AVAILABLE设备有可用的软件或固件更新REVOKEDFIDO 联盟认定该认证器因任何原因如已知是欺诈产品或含有蓄意后门都不应被信任依赖方应拒绝该型号认证器的任何未来注册SELF_ASSERTION_SUBMITTED认证器厂商已完成并提交自我认证清单给 FIDO 联盟若该清单公开其 URL 会记录在url字段如何选择 permitted / prohibitedvalidate_status_permitted白名单模式只有状态命中列表的认证器才通过校验。官方在 schema 注释中提示通常不鼓励使用。validate_status_prohibited黑名单模式命中列表的认证器一律拒绝注册。默认值已包含 5 个安全风险状态REVOKED、USER_KEY_PHYSICAL_COMPROMISE、USER_KEY_REMOTE_COMPROMISE、USER_VERIFICATION_BYPASS、ATTESTATION_KEY_COMPROMISE官方强烈建议不要改动默认值因为被默认排除的认证器很可能已被攻陷。注意 schema 枚举中的状态名与文档表格略有差异源码枚举使用FIDO_NOT_CERTIFIED对应表格中的NOT_FIDO_CERTIFIED配置时以各自上下文为准——validate_status_*参考本表及 schema 枚举。注册与校验链路配置如何影响实际流程把参考指南的配置落到真实请求链路上可以帮助理解为什么推荐配置是安全的。以 handler_register_webauthn.go 为例挑战阶段WebAuthnRegistrationPUT校验用户会话与描述字段1~64 字符、不可与已有凭证重名随后BeginRegistration生成 attestation challenge。值得注意的是注册请求的加密算法参数覆盖了 MLDSAML-DSA-44/65/87后量子密码、EdDSA、ES256/384/512、RS256/384/512、PS256/384/512——这与 Authelia 项目Post-Quantum Cryptography Ready的定位一致。响应阶段WebAuthnRegistrationPOST解析客户端响应、CreateCredential创建凭证后调用ValidateCredentialAllowed即上文VerifyCredential执行 MDS 验证与 AAGUID/backup eligibility 过滤全部通过后才SaveWebAuthnCredential持久化并记录审计事件。Passkey 登录FirstFactorPasskeyGET等见 handler_firstfactor_passkey.go使用BeginDiscoverableLogin发起可发现凭证断言此时enable_passkey_login与discoverability的配置直接决定登录体验与凭证类型。元数据校验失败如 AAGUID 未登记、状态为REVOKED会体现在VerifyCredentialResult的MetaDataValidationError等字段中最终注册被拒绝——这正是参考指南推荐开启validate_entry、validate_status的底层原因。实践建议小结新部署直接采用推荐配置将本文第一节的 YAML 作为 Passkey 场景基线配合配置文档按需调整timeout、display_name与selection_criteria。谨慎对待实验性选项experimental_enable_passkey_uv_two_factors与experimental_enable_passkey_upgrade均不被官方支持且未来会变更/移除生产环境应避免依赖。默认禁止状态保持不动validate_status_prohibited的默认 5 项是失陷认证器的安全底线如需白名单化可研究validate_status_permitted但先评估对现有用户凭证的影响。关注存储与启动行为开启metadata.enabled会占用约 5MB 存储用于缓存 MDS3 blob见存储配置说明cache_policy: strict下启动拉取失败会直接报错离线环境可评估relaxed。联动文档Passkey 与remember_me的行为见会话配置常见疑问见安全密钥 FAQ实验性选项的演进方向见细粒度授权路线图。【免费下载链接】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），仅供参考