Microsoft Entra 身份验证方法 API 概述

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

身份验证方法是用户在 Microsoft Entra ID 中进行身份验证的方式。 Microsoft Entra ID 中的身份验证方法包括密码和电话 (,例如短信和语音通话) ,目前可在 Microsoft Graph 中进行管理,以及许多其他方法,例如 FIDO2 安全密钥和 Microsoft Authenticator 应用。 身份验证方法用于主要、双重因素和分步身份验证,此外还适用于自助式密码重置 (SSPR) 流程。

身份验证方法 API 用于管理用户的身份验证方法。 例如:

  • 可以向用户添加电话号码。 如果策略允许用户使用该电话号码,则用户可以使用该电话号码进行 SMS 和语音呼叫身份验证。
  • 可以更新该号码,也可从用户中删除该号码。
  • 可以启用或禁用短信登录号码。
  • 可以重置用户的密码。
  • 可以检索用户的 FIDO2 安全密钥的详细信息,如果用户丢失了密钥,则将其删除。
  • 你可以检索用户的 Microsoft Authenticator 注册的详细信息,如果用户丢失了手机,则将其删除。
  • 你可以检索用户的 Windows Hello 企业版注册的详细信息,如果用户丢失了设备,则将其删除。
  • 可以向用户添加电子邮件地址。 然后,用户可以将该电子邮件用作 Self-Service 密码重置 (SSPR) 过程的一部分。
  • 可以更新该电子邮件,或从用户中删除它。
  • 可以为用户分配和激活硬件 OATH 令牌。
  • 可以检索用户的 QR 码身份验证的详细信息,并在用户丢失标准 QR 码时将其删除。

某些 API 支持自助操作,允许用户管理自己的身份验证方法。 例如,用户可以添加、更新或删除自己用于身份验证和 SSPR 的电话号码和电子邮件地址。

重要

从 2026 年 1 月 26 日开始,如果用户在当前会话中最后进行身份验证是在 10 分钟多前,自助凭据管理操作要求用户完成多重身份验证 (MFA) 。 此更改适用于管理凭据的最终用户和管理员,并且可能会导致已注册 MFA 的用户收到更频繁的 MFA 提示。 调用凭据管理 API 时,应用程序必须正确处理“403 已禁止”响应:

  1. 检测 403 响应 - 当 API 返回 403 状态代码时,用户需要完成 MFA。
  2. 请求新 MFA - 使用以下声明参数新建交互式 OAuth2 请求:
    {"access_token":{"amr":{"essential":true,"values":["ngcmfa"]}}}
    
  3. 用户完成 MFA - 在交互式 OAuth2 请求期间,具有已注册 MFA 方法的用户必须完成身份验证。 MFA 凭据在 10 分钟内保持有效。
  4. 使用新令牌重试 - 使用新获取的访问令牌重试凭据管理请求。

有关在应用程序中实现索赔质询的更多信息,请参阅:

用户使用身份验证方法的能力受租户的 身份验证方法策略 的约束。 例如,可能只有 R&D 部门中的用户被启用以使用 FIDO2 方法,而所有用户都可以使用 Microsoft Authenticator。

不建议在需要循环访问整个用户群体以进行审核或安全检查的情况中使用身份验证方法 API。 对于这些类型的方案,我们建议使用 身份验证方法注册和使用情况报告 API。

注意

对身份验证方法 API 的请求在 60 秒后超时。

可以在 Microsoft Graph 中管理哪些身份验证方法?

注意

若要管理基于证书的身份验证 (CBA) ,请参阅 x509CertificateAuthenticationMethodConfiguration

身份验证方法 说明 示例
emailAuthenticationMethod 用户可以将电子邮件地址用作 Self-Service 密码重置 (SSPR) 过程的一部分。 查看用户的身份验证电子邮件地址。 向用户添加、更新或删除电子邮件地址。
externalAuthenticationMethod 用户可以使用外部标识提供程序登录到 Microsoft Entra ID。 删除用户的外部 MFA。
fido2AuthenticationMethod 用户可以使用 FIDO2 安全密钥登录到 Microsoft Entra ID。 删除丢失的 FIDO2 安全密钥。
hardwareOathAuthenticationMethod 允许用户使用提供一次性代码的硬件 OATH 设备执行多重身份验证。 获取 (un) 分配或 () 为用户激活硬件令牌。
microsoftAuthenticatorAuthenticationMethod 用户可以使用 Microsoft Authenticator 应用登录或对 Microsoft Entra ID 执行多重身份验证 删除 Microsoft Authenticator 身份验证方法。
passwordAuthenticationMethod 密码当前是 Microsoft Entra ID 中的默认主要身份验证方法。 重置用户密码
phoneAuthenticationMethod 用户可以在策略允许的情况下使用 电话使用短信或语音呼叫 进行身份验证。 查看用户的身份验证电话号码。 向用户添加、更新或删除电话号码。 启用或禁用用于短信登录的主移动电话。
platformCredentialAuthenticationMethod 平台凭据是 macOS 设备上用户的登录身份验证方法。 查看用户的平台凭据。 删除用户的平台凭据。
softwareOathAuthenticationMethod 允许用户使用支持 OATH 规范并提供一次性代码的应用程序执行多重身份验证。 获取和删除分配给用户的软件令牌。
TemporaryAccessPassAuthenticationMethod 临时访问通行证是一种限时密码,可作为强凭据并允许加入无密码凭据。 为用户设置新的临时访问通行证。
verifiedIdProfile 验证 ID 配置文件定义了可验证凭据交换的属性和使用模式,包括面部检查配置。 创建、更新或删除验证 ID 配置文件。 配置面部检查和可验证凭据设置。
windowsHelloForBusinessAuthenticationMethod Windows Hello 企业版是 Windows 设备上的一种无密码登录方法。 查看用户已启用 Windows Hello 企业版登录的设备。 删除 Windows Hello 企业版凭据。
身份验证状态 管理用户的登录首选项和每用户 MFA 查看或设置用户的 MFA 状态。 请参阅或设置系统首选的多重身份验证 (MFA) 设置。
qrCodePinAuthenticationMethod QR 码是一种专为一线工作人员设计的身份验证方法,旨在提供简单的身份验证体验。 用户只需扫描提供给他们的唯一 QR 码,然后输入其 PIN 即可登录应用。 为用户添加 QR 码身份验证方法。
PasswordlessMicrosoftAuthenticatorAuthenticationMethod (已弃用) Microsoft Authenticator 用户可使用无密码手机登录来登录 Microsoft Entra ID 删除无密码手机登录身份验证方法。

Microsoft Graph beta尚不支持以下身份验证方法。

身份验证方法 说明 示例
安全问题和解答 允许用户在执行自助密码重置时验证其标识。 删除用户注册的安全问题。

需要重新注册多重身份验证

若要要求用户在下次登录时设置新的多重身份验证,请调用单独的 DELETE 身份验证方法操作来删除每个用户的当前身份验证方法。 当用户没有其他方法时,系统会提示他们下次登录时需要强身份验证的地方进行注册。

租户级身份验证方法使用

可以使用身份验证 方法使用情况报告 API 监视租户级身份验证方法注册和使用情况,包括为 MFA 和无密码身份验证注册或注销的用户,以及为 SSPR 注册或注销的用户。

后续步骤

  • 查看身份验证方法类型及其各种方法。
  • 在 Graph 浏览器中试用 API。