企业官网建设流程全解析

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 Service（MDS3）状态值的完整语义，并结合仓库源码说明这些配置在注册、认证与校验链路上的实际作用。读完本文，你将能够为 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: $schema=https://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_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 中validWebAuthnConveyancePreferences），user_verification、attachment、discoverability也都有各自的枚举约束。

配置项全景：从参考指南到配置文档

参考指南提到的能力，在WebAuthn 配置文档中有完整参数级说明。以下按功能域分组，与源码中的结构体一一对应：

基础开关与外观

• disable（boolean，默认false）：设为true时整体禁用 WebAuthn。
• enable_passkey_login（boolean，默认false）：启用 Passkey 单因素登录。该选项映射到源码结构体字段WebAuthn.EnablePasskeyLogin。
• experimental_enable_passkey_uv_two_factors（boolean，默认false）：实验性选项，允许强制执行用户验证（PIN、生物识别等）且上报已执行 user verification 的认证器满足访问控制规则中的two_factor策略。官方在配置文档中标注为不受支持、完全实验性，未来会被细粒度授权路线图中定义的 custom policy flows 取代（该功能上线后此选项会导致启动失败）。
• experimental_enable_passkey_upgrade（boolean，默认false）：实验性选项。部分认证器/浏览器无法正确上报新注册凭证是否为 Passkey，规范要求此时按"非 Passkey"处理，但会造成用户困惑；开启后 Authelia 会尝试自动把这类凭证升级为 Passkey。官方明确该选项未来会被移除（可能变为 UI 内的明确流程、自动流程或彻底删除）。
• display_name（string，默认Authelia）：发送给客户端展示的依赖方显示名，具体展示方式由浏览器/操作系统决定。
• timeout（duration，默认60 seconds）：WebAuthn 交互的超时时间，源码默认值见 DefaultWebAuthnConfiguration（time.Second * 60）。

attestation_conveyance_preference

控制 attestation 的传达（conveyancing）偏好。传达允许收集认证器的 attestation statement（如 AAGUID，用于标识认证器型号）。合法值：

源码类型为protocol.ConveyancePreference，合法枚举定义在 const.go（validWebAuthnConveyancePreferences）。

filtering（注册期过滤）

• permitted_aaguids（list of UUID）：仅允许列表中的 AAGUID 注册，适合公司强制使用指定型号认证器的策略。与prohibited_aaguids互斥。
• prohibited_aaguids（list of UUID）：禁止列表中的 AAGUID 注册，适合公司禁止特定型号认证器的策略。与permitted_aaguids互斥。
• prohibit_backup_eligibility（boolean，默认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。

metadata（MDS3 元数据服务）

• enabled（boolean，默认false）：开启认证器与凭证的元数据服务校验。需要下载 metadata service blob，约占用存储后端 5MB 数据。官方建议用户花时间配置此项。
• cache_policy（默认strict）：元数据缓存的运行模式。strict在启动时尝试下载新副本，失败则报错；relaxed同样尝试下载，但若已有未过期的缓存版本，遇到元数据服务返回429 Too Many Requests时只记录错误日志。对应常量定义在 internal/webauthn/const.go（CachePolicyStrict/CachePolicyRelaxed）。
• validate_trust_anchor（boolean，默认true）：校验 attestation 证书是否可追溯到已验证 MDS3 blob 中的 CA 证书。官方强烈建议保持默认。
• validate_entry（boolean，默认true）：校验认证器在 MDS3 blob 中是否有条目。注意这可能会排除没有 FIDO 合规认证或未向 MDS3 登记的认证器；官方建议保持默认，因为缺少该校验就无法验证认证器的真实性。
• validate_entry_permit_zero_aaguid（boolean，默认false）：允许提供了空 AAGUID 的认证器。部分未取得 FIDO 合规认证的认证器可能需要开启。
• validate_status（boolean，默认true）：校验 attestation 条目状态。一般没有理由关闭，因为默认被排除的认证器大概率已失陷。
• validate_status_permitted（list of string）：认证器通过校验所必须处于的状态列表（白名单）。合法值见下文"元数据状态"。
• validate_status_prohibited（list of string）：禁止注册的认证器状态列表（黑名单）。官方强烈建议不要修改默认值。默认配置为REVOKED、USER_KEY_PHYSICAL_COMPROMISE、USER_KEY_REMOTE_COMPROMISE、USER_VERIFICATION_BYPASS、ATTESTATION_KEY_COMPROMISE，见 DefaultWebAuthnConfiguration。

元数据校验在源码中的落地

MDS3 集成位于 internal/webauthn/metadata.go：

• NewMetaDataProvider依据config.WebAuthn.Metadata.Enabled决定是否构建StoreCachedMetadataProvider；内存 provider 通过newMetadataProviderMemory把ValidateEntry、ValidateEntryPermitZeroAAGUID、ValidateTrustAnchor、ValidateStatus、ValidateStatusPermitted/Prohibited逐一映射到底层memoryprovider 的选项中。
• productionMDS3Provider.FetchMDS3向 FIDO 生产 MDS3 端点发起请求，使用If-None-Match携带当前 blob 编号做条件请求：返回200 OK时读取新 blob，304 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 定义）：

如何选择 permitted / prohibited

• validate_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 为例：

1. 挑战阶段（WebAuthnRegistrationPUT）：校验用户会话与描述字段（1~64 字符、不可与已有凭证重名），随后BeginRegistration生成 attestation challenge。值得注意的是，注册请求的加密算法参数覆盖了 MLDSA（ML-DSA-44/65/87，后量子密码）、EdDSA、ES256/384/512、RS256/384/512、PS256/384/512——这与 Authelia 项目"Post-Quantum Cryptography Ready"的定位一致。
2. 响应阶段（WebAuthnRegistrationPOST）：解析客户端响应、CreateCredential创建凭证后，调用ValidateCredentialAllowed（即上文VerifyCredential）执行 MDS 验证与 AAGUID/backup eligibility 过滤；全部通过后才SaveWebAuthnCredential持久化并记录审计事件。
3. Passkey 登录（FirstFactorPasskeyGET等，见 handler_firstfactor_passkey.go）：使用BeginDiscoverableLogin发起可发现凭证断言，此时enable_passkey_login与discoverability的配置直接决定登录体验与凭证类型。

元数据校验失败（如 AAGUID 未登记、状态为REVOKED）会体现在VerifyCredentialResult的MetaDataValidationError等字段中，最终注册被拒绝——这正是参考指南推荐开启validate_entry、validate_status的底层原因。

实践建议小结

1. 新部署直接采用推荐配置：将本文第一节的 YAML 作为 Passkey 场景基线，配合配置文档按需调整timeout、display_name与selection_criteria。
2. 谨慎对待实验性选项：experimental_enable_passkey_uv_two_factors与experimental_enable_passkey_upgrade均不被官方支持且未来会变更/移除，生产环境应避免依赖。
3. 默认禁止状态保持不动：validate_status_prohibited的默认 5 项是失陷认证器的安全底线；如需白名单化可研究validate_status_permitted，但先评估对现有用户凭证的影响。
4. 关注存储与启动行为：开启metadata.enabled会占用约 5MB 存储用于缓存 MDS3 blob（见存储配置说明）；cache_policy: strict下启动拉取失败会直接报错，离线环境可评估relaxed。
5. 联动文档：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