Authelia WebAuthn 配置指南从安全密钥到 Passkey 的完整实践【免费下载链接】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 单点登录门户中WebAuthn 第二因素Second Factor配置的完整技术指南。WebAuthn 是 Authelia 支持的现代浏览器安全密钥规范支持 FIDO2 安全密钥、平台内建认证器如 Windows Hello与 Passkey 登录。读完本文你将掌握webauthn配置块下所有选项的语义与取值、认证器过滤与选择标准的用法、FIDO MDS3 元数据服务的开启与调优以及 Authelia 在源码层面对这些配置的校验与执行逻辑能够直接落地一套可运行、可审计的 WebAuthn 配置。配置总览WebAuthn 配置位于configuration.yml的webauthn键下完整的可用配置键清单共 23 个可以从源码生成的 schema/keys.go 中确认例如webauthn.disable、webauthn.enable_passkey_login、webauthn.filtering.permitted_aaguids、webauthn.metadata.cache_policy等。以下是一个包含全部选项的参考配置webauthn: disable: false enable_passkey_login: false display_name: Authelia attestation_conveyance_preference: indirect timeout: 60 seconds filtering: permitted_aaguids: [] prohibited_aaguids: [] prohibit_backup_eligibility: false selection_criteria: attachment: discoverability: preferred user_verification: preferred metadata: enabled: false cache_policy: strict validate_trust_anchor: true validate_entry: true validate_entry_permit_zero_aaguid: false validate_status: true validate_status_permitted: [] validate_status_prohibited: - REVOKED - USER_KEY_PHYSICAL_COMPROMISE - USER_KEY_REMOTE_COMPROMISE - USER_VERIFICATION_BYPASS - ATTESTATION_KEY_COMPROMISE以上默认值与源码中DefaultWebAuthnConfiguration的定义一致见 schema/webauthn.goDisplayName默认为Authelia、Timeout默认为 60 秒、ConveyancePreference默认为indirect、元数据校验默认开启信任锚与条目校验、默认禁止五种安全状态。该配置块整体映射到结构体schema.WebAuthn见 schema/webauthn.go其中Filtering、SelectionCriteria、Metadata分别对应WebAuthnFiltering、WebAuthnSelectionCriteria、WebAuthnMetadata三个子结构体。基础选项disable{{ confkey typeboolean defaultfalse requiredno }}设置为true时完全禁用 WebAuthn 功能。需要注意它与enable_passkey_login存在互斥关系配置校验器validator/webauthn.go会检查当enable_passkey_login为true而disable也为true时抛出错误因为二者语义冲突。enable_passkey_login{{ confkey typeboolean defaultfalse requiredno }}启用后用户可以通过 Passkey 直接登录而无需输入用户名和密码。需要注意这种登录**仅算作单因素single factor**认证如果请求需要多因素认证Authelia 默认仍会提示用户输入密码该选项与remember_me的交互逻辑需要特别注意详见 会话配置中的 remember_me 说明。从校验源码可以进一步看到enable_passkey_login是 Passkey 相关能力的总开关两个实验性选项experimental_enable_passkey_uv_two_factors与experimental_enable_passkey_upgrade只有在enable_passkey_login开启时才允许启用否则校验器会直接报错见 validator/webauthn.go。此外若同时将enable_passkey_login设为true而把selection_criteria.discoverability设为discouraged校验器会给出警告见 validator/webauthn.go因为可发现的discoverable凭据是 Passkey 体验的基础。display_name{{ confkey typestring defaultAuthelia requiredno }}设置发送给客户端用于展示的显示名称。具体如何展示由浏览器乃至操作系统自行决定Authelia 只负责将display_name作为 WebAuthn Relying Party 的名称属性传递。相关字段定义与默认值见 schema/webauthn.go。若该项为空字符串校验器会将其回填为默认值Authelia见 validator/webauthn.go。attestation_conveyance_preference{{ confkey typestring defaultindirect requiredno }}设置认证器证明attestation的传递偏好。证明Conveyancing允许收集关于认证器的证明声明例如 AAGUID——它标识了认证器的型号。可选值如下值说明none指示客户端不执行证明传递indirect指示客户端执行证明传递但客户端可自行选择方式包括使用第三方匿名化 CAdirect指示客户端执行证明传递且证明声明由认证器直接签名该字段在结构体中被定义为protocol.ConveyancePreference类型见 schema/webauthn.go校验器会在值为空时回填默认indirect并对非法值报错见 validator/webauthn.go。timeout{{ confkey typestring,integer syntaxduration default60 seconds requiredno }}调整一次 WebAuthn 交互注册/认证仪式请求的超时时间。类型为 Go 的time.Duration见 schema/webauthn.go因此支持诸如60 seconds、1 minute这类人类可读写法。若值小于等于 0校验器会回填默认的 60 秒见 validator/webauthn.go。实验性选项以下两个选项在配置结构中均已定义见 schema/webauthn.go但不被视为受支持的正式功能请在生产环境中谨慎使用。experimental_enable_passkey_uv_two_factors{{ confkey typeboolean defaultfalse requiredno }}{{ callout contextdanger titleStability and Security Notice iconoutline/alert-octagon }} 该选项不受支持完全处于实验阶段未来将被 访问控制中的自定义策略流 取代——后者可以在访问控制段定义并为认证提供确定性的结果以正确支持认证流程的 Authentication Method Reference Values。在加入替代流程的版本中此选项将导致启动失败。 {{ /callout }}该选项允许那些强制用户验证PIN 输入、生物识别等并向服务器报告已执行用户验证的认证器直接满足访问控制规则的two_factor策略——即一次通过用户验证的 Passkey 登录即可同时充当第二因素。experimental_enable_passkey_upgrade{{ confkey typeboolean defaultfalse requiredno }}{{ callout contextdanger titleStability Notice iconoutline/alert-octagon }} 该选项不受支持完全处于实验阶段未来会被移除。它要么成为 UI 中一个明确的操作流程要么变为自动行为要么被彻底移除。 {{ /callout }}部分认证器或浏览器在报告某个 WebAuthn 凭据是否真的是 Passkey 时存在问题相关规范指示实现者在无法确认时应假定其不是 Passkey这会给用户带来困惑。当该选项为true时若浏览器或认证器未将新注册的 WebAuthn 凭据报告为 PasskeyAuthelia 会尝试自动将该凭据升级为 Passkey以缓解上述困惑。filtering注册时的认证器过滤filtering子配置用于在注册阶段对认证器进行过滤对应结构体WebAuthnFiltering见 schema/webauthn.go。其底层执行逻辑位于 internal/webauthn/util.go 的ValidateCredentialAllowed函数先检查ProhibitBackupEligibility再按PermittedAAGUIDs白名单优先匹配最后逐项检查ProhibitedAAGUIDs黑名单。permitted_aaguids{{ confkey typelist(string) syntaxuuid requiredno }}Authenticator Attestation GUIDAAGUID白名单只有出现在该列表中的认证器型号才允许注册。适合公司政策要求只能使用指定认证器的场景。与prohibited_aaguids互斥——两者同时配置时校验器会报错见 validator/webauthn.go。源码中该字段类型为[]uuid.UUID因此列表项必须是合法的 UUID 格式。prohibited_aaguids{{ confkey typelist(string) syntaxuuid requiredno }}AAGUID黑名单出现在该列表中的认证器型号将无法注册。适合公司政策禁止某些认证器的场景。与permitted_aaguids互斥规则同上。白名单优先于黑名单生效当配置了白名单时未命中白名单的 AAGUID 直接拒绝黑名单不再参与判断见 util.go。prohibit_backup_eligibility{{ confkey typeboolean defaultfalse requiredno }}设为true后能够导出凭据即具备备份能力的认证器将无法注册。这通常会阻止同步凭据例如跨设备云同步的 Passkey被注册。源码中对应ProhibitBackupEligibility字段schema/webauthn.go当凭据的BackupEligible为真且该选项开启时ValidateCredentialAllowed会直接返回错误见 util.go。selection_criteria认证器选择标准该子配置设置创建新凭据时选择合适认证器的偏好对应结构体WebAuthnSelectionCriteria见 schema/webauthn.go。三个字段均定义了合法取值非法值会被校验器拒绝见 validator/webauthn.go。attachment{{ confkey typestring default requiredno }}设置新创建凭据的认证器连接偏好。值说明空字符串展示所有可用的认证器由用户自行选择具体标准cross-platform可在不同系统间移动的认证器如物理安全密钥platform平台内置认证器如 Windows Hello、Apple ID 等discoverability{{ confkey typestring defaultpreferred requiredno }}设置可发现性discoverable credential偏好可能影响 Passkey 的创建。值说明discouraged倾向于不可发现非 resident keypreferred倾向于可发现若不可发现也不会报错required强制要求可发现若不可发现可能会报错该字段类型为protocol.ResidentKeyRequirement见 schema/webauthn.go与 Passkey 登录体验直接相关。user_verification{{ confkey typestring defaultpreferred requiredno }}设置用户验证偏好。值说明discouraged倾向于不要求用户验证preferred合规客户端会在认证器支持时要求用户进行验证required客户端必须要求用户验证若认证器不支持验证则失败该字段类型为protocol.UserVerificationRequirement见 schema/webauthn.go。metadataFIDO 元数据服务MDS3metadata子配置用于启用元数据服务以校验认证器的真实性——适合公司政策要求只能使用符合 FIDO 规范的认证器的场景对应结构体WebAuthnMetadata见 schema/webauthn.go。推荐配置请参阅 WebAuthn 参考指南的 Recommended Configurations。enabled{{ confkey typeboolean defaultfalse requiredno }}启用元数据服务对认证器与凭据的校验。启用后 Authelia 需要下载 MDS3 blob该数据在你的 存储后端 中大约占用5MB空间——源码中元数据 blob 通过storage.CachedDataProvider以mds3为缓存名写入存储见 internal/webauthn/const.go 与 internal/webauthn/metadata.go。该值默认false是为了避免破坏现有部署但官方建议用户尽早配置启用。从实现来看元数据提供器实现了model.StartupCheck接口metadata.go会在启动阶段完成初始化检查。cache_policy{{ confkey typestring defaultstrict requiredno }}设置元数据服务缓存的运行模式可选strict与relaxedstrict默认启动时尝试下载一份全新的 MDS3 blob如果无法下载则启动失败relaxed启动时仍会尝试下载新副本但如果存储中已有未过期的缓存副本那么当元数据服务返回429 Too Many Requests状态码时只记录错误日志而不中断启动。这一行为可以直接在源码中得到印证metadata.go 的init方法在下载失败时若cachePolicy CachePolicyStrict则直接返回错误否则仅以 Debug 级别记录日志。而 metadata.go 的FetchMDS3会通过If-None-Match头携带当前 blob 编号做条件请求对200 OK、304 Not Modified、429 Too Many Requests分别处理。校验器只允许这两个取值见 validator/webauthn.go常量定义见 internal/webauthn/const.go。validate_trust_anchor{{ confkey typeboolean defaulttrue requiredno }}启用对证明证书attestation certificate与已验证 MDS3 blob 中 CA 证书的信任锚校验。官方建议始终保留默认值true。源码中该选项通过memory.WithValidateTrustAnchor注入内存元数据提供器metadata.go。validate_entry{{ confkey typeboolean defaulttrue requiredno }}启用对认证器在 MDS3 blob 中是否存在条目的校验。建议保留默认值但注意这可能会排除那些没有FIDO 合规认证、或未在 MDS3 注册的认证器——理由是缺少该校验就无法验证特定认证器的真实性。对应memory.WithValidateEntry选项metadata.go。validate_entry_permit_zero_aaguid{{ confkey typeboolean defaultfalse requiredno }}允许提交了空 AAGUID的认证器通过条目校验。某些没有FIDO 合规认证的认证器可能需要开启此项。注意源码注释中该选项默认值为true的 jsonschema 描述与实际默认值false存在出入实际生效的默认值以 DefaultWebAuthnConfiguration 中的ValidateEntryPermitZeroAAGUID: false为准。对应memory.WithValidateEntryPermitZeroAAGUID选项metadata.go。validate_status{{ confkey typeboolean defaulttrue requiredno }}启用对证明条目状态的校验。一般没有任何理由关闭它因为默认被排除的认证器很可能已被攻破。对应memory.WithValidateStatus选项metadata.go。validate_status_permitted{{ confkey typelist(string) requiredno }}认证器通过校验所必须处于的状态的白名单。合法取值请参阅 WebAuthn 参考指南的 Metadata Status。该字段对应memory.WithStatusDesired选项metadata.go一般不建议使用。validate_status_prohibited{{ confkey typelist(string) requiredno }}认证器被禁止注册的状态黑名单。合法取值同样参阅 WebAuthn 参考指南的 Metadata Status。强烈建议不要修改默认值默认配置即为上文 配置总览 中的五个状态REVOKED、USER_KEY_PHYSICAL_COMPROMISE、USER_KEY_REMOTE_COMPROMISE、USER_VERIFICATION_BYPASS、ATTESTATION_KEY_COMPROMISE与源码中的默认值完全一致schema/webauthn.go对应memory.WithStatusUndesired选项metadata.go。配置校验规则小结结合 validator/webauthn.go 的源码Authelia 在启动时会执行以下 WebAuthn 配置校验display_name为空 → 回填Autheliatimeout 0→ 回填 60 秒enable_passkey_logintrue与disabletrue互斥报错实验性选项必须在enable_passkey_logintrue时才能开启metadata.cache_policy仅允许strict/relaxedattestation_conveyance_preference仅允许none/indirect/directattachment、discoverability、user_verification均有各自的合法取值集合Passkey 模式下discoverabilitydiscouraged会产生警告permitted_aaguids与prohibited_aaguids同时配置会报错。推荐配置与 FAQ面向 Passkey 的推荐配置以下是一份符合 NIST 建议的 Passkey 配置完整说明见 WebAuthn 参考指南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该配置组合了Passkey 登录、直接证明以获取明确的 AAGUID、禁止可导出凭据阻止同步凭据、并全面开启 MDS3 元数据校验形成高信任度的注册链路。常见问题关于安全密钥与 WebAuthn 的常见问题请参阅 Security Key 常见问题。延伸阅读配置结构体与默认值定义internal/configuration/schema/webauthn.go配置校验逻辑internal/configuration/validator/webauthn.go认证器过滤与凭据可发现性判断internal/webauthn/util.goMDS3 元数据提供器与缓存实现internal/webauthn/metadata.go完整配置键列表internal/configuration/schema/keys.go推荐配置与 Metadata Status 取值docs/content/reference/guides/webauthn.md【免费下载链接】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 的完整实践
Authelia WebAuthn 配置指南从安全密钥到 Passkey 的完整实践【免费下载链接】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 单点登录门户中WebAuthn 第二因素Second Factor配置的完整技术指南。WebAuthn 是 Authelia 支持的现代浏览器安全密钥规范支持 FIDO2 安全密钥、平台内建认证器如 Windows Hello与 Passkey 登录。读完本文你将掌握webauthn配置块下所有选项的语义与取值、认证器过滤与选择标准的用法、FIDO MDS3 元数据服务的开启与调优以及 Authelia 在源码层面对这些配置的校验与执行逻辑能够直接落地一套可运行、可审计的 WebAuthn 配置。配置总览WebAuthn 配置位于configuration.yml的webauthn键下完整的可用配置键清单共 23 个可以从源码生成的 schema/keys.go 中确认例如webauthn.disable、webauthn.enable_passkey_login、webauthn.filtering.permitted_aaguids、webauthn.metadata.cache_policy等。以下是一个包含全部选项的参考配置webauthn: disable: false enable_passkey_login: false display_name: Authelia attestation_conveyance_preference: indirect timeout: 60 seconds filtering: permitted_aaguids: [] prohibited_aaguids: [] prohibit_backup_eligibility: false selection_criteria: attachment: discoverability: preferred user_verification: preferred metadata: enabled: false cache_policy: strict validate_trust_anchor: true validate_entry: true validate_entry_permit_zero_aaguid: false validate_status: true validate_status_permitted: [] validate_status_prohibited: - REVOKED - USER_KEY_PHYSICAL_COMPROMISE - USER_KEY_REMOTE_COMPROMISE - USER_VERIFICATION_BYPASS - ATTESTATION_KEY_COMPROMISE以上默认值与源码中DefaultWebAuthnConfiguration的定义一致见 schema/webauthn.goDisplayName默认为Authelia、Timeout默认为 60 秒、ConveyancePreference默认为indirect、元数据校验默认开启信任锚与条目校验、默认禁止五种安全状态。该配置块整体映射到结构体schema.WebAuthn见 schema/webauthn.go其中Filtering、SelectionCriteria、Metadata分别对应WebAuthnFiltering、WebAuthnSelectionCriteria、WebAuthnMetadata三个子结构体。基础选项disable{{ confkey typeboolean defaultfalse requiredno }}设置为true时完全禁用 WebAuthn 功能。需要注意它与enable_passkey_login存在互斥关系配置校验器validator/webauthn.go会检查当enable_passkey_login为true而disable也为true时抛出错误因为二者语义冲突。enable_passkey_login{{ confkey typeboolean defaultfalse requiredno }}启用后用户可以通过 Passkey 直接登录而无需输入用户名和密码。需要注意这种登录**仅算作单因素single factor**认证如果请求需要多因素认证Authelia 默认仍会提示用户输入密码该选项与remember_me的交互逻辑需要特别注意详见 会话配置中的 remember_me 说明。从校验源码可以进一步看到enable_passkey_login是 Passkey 相关能力的总开关两个实验性选项experimental_enable_passkey_uv_two_factors与experimental_enable_passkey_upgrade只有在enable_passkey_login开启时才允许启用否则校验器会直接报错见 validator/webauthn.go。此外若同时将enable_passkey_login设为true而把selection_criteria.discoverability设为discouraged校验器会给出警告见 validator/webauthn.go因为可发现的discoverable凭据是 Passkey 体验的基础。display_name{{ confkey typestring defaultAuthelia requiredno }}设置发送给客户端用于展示的显示名称。具体如何展示由浏览器乃至操作系统自行决定Authelia 只负责将display_name作为 WebAuthn Relying Party 的名称属性传递。相关字段定义与默认值见 schema/webauthn.go。若该项为空字符串校验器会将其回填为默认值Authelia见 validator/webauthn.go。attestation_conveyance_preference{{ confkey typestring defaultindirect requiredno }}设置认证器证明attestation的传递偏好。证明Conveyancing允许收集关于认证器的证明声明例如 AAGUID——它标识了认证器的型号。可选值如下值说明none指示客户端不执行证明传递indirect指示客户端执行证明传递但客户端可自行选择方式包括使用第三方匿名化 CAdirect指示客户端执行证明传递且证明声明由认证器直接签名该字段在结构体中被定义为protocol.ConveyancePreference类型见 schema/webauthn.go校验器会在值为空时回填默认indirect并对非法值报错见 validator/webauthn.go。timeout{{ confkey typestring,integer syntaxduration default60 seconds requiredno }}调整一次 WebAuthn 交互注册/认证仪式请求的超时时间。类型为 Go 的time.Duration见 schema/webauthn.go因此支持诸如60 seconds、1 minute这类人类可读写法。若值小于等于 0校验器会回填默认的 60 秒见 validator/webauthn.go。实验性选项以下两个选项在配置结构中均已定义见 schema/webauthn.go但不被视为受支持的正式功能请在生产环境中谨慎使用。experimental_enable_passkey_uv_two_factors{{ confkey typeboolean defaultfalse requiredno }}{{ callout contextdanger titleStability and Security Notice iconoutline/alert-octagon }} 该选项不受支持完全处于实验阶段未来将被 访问控制中的自定义策略流 取代——后者可以在访问控制段定义并为认证提供确定性的结果以正确支持认证流程的 Authentication Method Reference Values。在加入替代流程的版本中此选项将导致启动失败。 {{ /callout }}该选项允许那些强制用户验证PIN 输入、生物识别等并向服务器报告已执行用户验证的认证器直接满足访问控制规则的two_factor策略——即一次通过用户验证的 Passkey 登录即可同时充当第二因素。experimental_enable_passkey_upgrade{{ confkey typeboolean defaultfalse requiredno }}{{ callout contextdanger titleStability Notice iconoutline/alert-octagon }} 该选项不受支持完全处于实验阶段未来会被移除。它要么成为 UI 中一个明确的操作流程要么变为自动行为要么被彻底移除。 {{ /callout }}部分认证器或浏览器在报告某个 WebAuthn 凭据是否真的是 Passkey 时存在问题相关规范指示实现者在无法确认时应假定其不是 Passkey这会给用户带来困惑。当该选项为true时若浏览器或认证器未将新注册的 WebAuthn 凭据报告为 PasskeyAuthelia 会尝试自动将该凭据升级为 Passkey以缓解上述困惑。filtering注册时的认证器过滤filtering子配置用于在注册阶段对认证器进行过滤对应结构体WebAuthnFiltering见 schema/webauthn.go。其底层执行逻辑位于 internal/webauthn/util.go 的ValidateCredentialAllowed函数先检查ProhibitBackupEligibility再按PermittedAAGUIDs白名单优先匹配最后逐项检查ProhibitedAAGUIDs黑名单。permitted_aaguids{{ confkey typelist(string) syntaxuuid requiredno }}Authenticator Attestation GUIDAAGUID白名单只有出现在该列表中的认证器型号才允许注册。适合公司政策要求只能使用指定认证器的场景。与prohibited_aaguids互斥——两者同时配置时校验器会报错见 validator/webauthn.go。源码中该字段类型为[]uuid.UUID因此列表项必须是合法的 UUID 格式。prohibited_aaguids{{ confkey typelist(string) syntaxuuid requiredno }}AAGUID黑名单出现在该列表中的认证器型号将无法注册。适合公司政策禁止某些认证器的场景。与permitted_aaguids互斥规则同上。白名单优先于黑名单生效当配置了白名单时未命中白名单的 AAGUID 直接拒绝黑名单不再参与判断见 util.go。prohibit_backup_eligibility{{ confkey typeboolean defaultfalse requiredno }}设为true后能够导出凭据即具备备份能力的认证器将无法注册。这通常会阻止同步凭据例如跨设备云同步的 Passkey被注册。源码中对应ProhibitBackupEligibility字段schema/webauthn.go当凭据的BackupEligible为真且该选项开启时ValidateCredentialAllowed会直接返回错误见 util.go。selection_criteria认证器选择标准该子配置设置创建新凭据时选择合适认证器的偏好对应结构体WebAuthnSelectionCriteria见 schema/webauthn.go。三个字段均定义了合法取值非法值会被校验器拒绝见 validator/webauthn.go。attachment{{ confkey typestring default requiredno }}设置新创建凭据的认证器连接偏好。值说明空字符串展示所有可用的认证器由用户自行选择具体标准cross-platform可在不同系统间移动的认证器如物理安全密钥platform平台内置认证器如 Windows Hello、Apple ID 等discoverability{{ confkey typestring defaultpreferred requiredno }}设置可发现性discoverable credential偏好可能影响 Passkey 的创建。值说明discouraged倾向于不可发现非 resident keypreferred倾向于可发现若不可发现也不会报错required强制要求可发现若不可发现可能会报错该字段类型为protocol.ResidentKeyRequirement见 schema/webauthn.go与 Passkey 登录体验直接相关。user_verification{{ confkey typestring defaultpreferred requiredno }}设置用户验证偏好。值说明discouraged倾向于不要求用户验证preferred合规客户端会在认证器支持时要求用户进行验证required客户端必须要求用户验证若认证器不支持验证则失败该字段类型为protocol.UserVerificationRequirement见 schema/webauthn.go。metadataFIDO 元数据服务MDS3metadata子配置用于启用元数据服务以校验认证器的真实性——适合公司政策要求只能使用符合 FIDO 规范的认证器的场景对应结构体WebAuthnMetadata见 schema/webauthn.go。推荐配置请参阅 WebAuthn 参考指南的 Recommended Configurations。enabled{{ confkey typeboolean defaultfalse requiredno }}启用元数据服务对认证器与凭据的校验。启用后 Authelia 需要下载 MDS3 blob该数据在你的 存储后端 中大约占用5MB空间——源码中元数据 blob 通过storage.CachedDataProvider以mds3为缓存名写入存储见 internal/webauthn/const.go 与 internal/webauthn/metadata.go。该值默认false是为了避免破坏现有部署但官方建议用户尽早配置启用。从实现来看元数据提供器实现了model.StartupCheck接口metadata.go会在启动阶段完成初始化检查。cache_policy{{ confkey typestring defaultstrict requiredno }}设置元数据服务缓存的运行模式可选strict与relaxedstrict默认启动时尝试下载一份全新的 MDS3 blob如果无法下载则启动失败relaxed启动时仍会尝试下载新副本但如果存储中已有未过期的缓存副本那么当元数据服务返回429 Too Many Requests状态码时只记录错误日志而不中断启动。这一行为可以直接在源码中得到印证metadata.go 的init方法在下载失败时若cachePolicy CachePolicyStrict则直接返回错误否则仅以 Debug 级别记录日志。而 metadata.go 的FetchMDS3会通过If-None-Match头携带当前 blob 编号做条件请求对200 OK、304 Not Modified、429 Too Many Requests分别处理。校验器只允许这两个取值见 validator/webauthn.go常量定义见 internal/webauthn/const.go。validate_trust_anchor{{ confkey typeboolean defaulttrue requiredno }}启用对证明证书attestation certificate与已验证 MDS3 blob 中 CA 证书的信任锚校验。官方建议始终保留默认值true。源码中该选项通过memory.WithValidateTrustAnchor注入内存元数据提供器metadata.go。validate_entry{{ confkey typeboolean defaulttrue requiredno }}启用对认证器在 MDS3 blob 中是否存在条目的校验。建议保留默认值但注意这可能会排除那些没有FIDO 合规认证、或未在 MDS3 注册的认证器——理由是缺少该校验就无法验证特定认证器的真实性。对应memory.WithValidateEntry选项metadata.go。validate_entry_permit_zero_aaguid{{ confkey typeboolean defaultfalse requiredno }}允许提交了空 AAGUID的认证器通过条目校验。某些没有FIDO 合规认证的认证器可能需要开启此项。注意源码注释中该选项默认值为true的 jsonschema 描述与实际默认值false存在出入实际生效的默认值以 DefaultWebAuthnConfiguration 中的ValidateEntryPermitZeroAAGUID: false为准。对应memory.WithValidateEntryPermitZeroAAGUID选项metadata.go。validate_status{{ confkey typeboolean defaulttrue requiredno }}启用对证明条目状态的校验。一般没有任何理由关闭它因为默认被排除的认证器很可能已被攻破。对应memory.WithValidateStatus选项metadata.go。validate_status_permitted{{ confkey typelist(string) requiredno }}认证器通过校验所必须处于的状态的白名单。合法取值请参阅 WebAuthn 参考指南的 Metadata Status。该字段对应memory.WithStatusDesired选项metadata.go一般不建议使用。validate_status_prohibited{{ confkey typelist(string) requiredno }}认证器被禁止注册的状态黑名单。合法取值同样参阅 WebAuthn 参考指南的 Metadata Status。强烈建议不要修改默认值默认配置即为上文 配置总览 中的五个状态REVOKED、USER_KEY_PHYSICAL_COMPROMISE、USER_KEY_REMOTE_COMPROMISE、USER_VERIFICATION_BYPASS、ATTESTATION_KEY_COMPROMISE与源码中的默认值完全一致schema/webauthn.go对应memory.WithStatusUndesired选项metadata.go。配置校验规则小结结合 validator/webauthn.go 的源码Authelia 在启动时会执行以下 WebAuthn 配置校验display_name为空 → 回填Autheliatimeout 0→ 回填 60 秒enable_passkey_logintrue与disabletrue互斥报错实验性选项必须在enable_passkey_logintrue时才能开启metadata.cache_policy仅允许strict/relaxedattestation_conveyance_preference仅允许none/indirect/directattachment、discoverability、user_verification均有各自的合法取值集合Passkey 模式下discoverabilitydiscouraged会产生警告permitted_aaguids与prohibited_aaguids同时配置会报错。推荐配置与 FAQ面向 Passkey 的推荐配置以下是一份符合 NIST 建议的 Passkey 配置完整说明见 WebAuthn 参考指南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该配置组合了Passkey 登录、直接证明以获取明确的 AAGUID、禁止可导出凭据阻止同步凭据、并全面开启 MDS3 元数据校验形成高信任度的注册链路。常见问题关于安全密钥与 WebAuthn 的常见问题请参阅 Security Key 常见问题。延伸阅读配置结构体与默认值定义internal/configuration/schema/webauthn.go配置校验逻辑internal/configuration/validator/webauthn.go认证器过滤与凭据可发现性判断internal/webauthn/util.goMDS3 元数据提供器与缓存实现internal/webauthn/metadata.go完整配置键列表internal/configuration/schema/keys.go推荐配置与 Metadata Status 取值docs/content/reference/guides/webauthn.md【免费下载链接】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），仅供参考
