Microsoft Graph 身份验证方法 API 入门

身份验证方法 是用户在 Azure Active Directory (Azure AD) 中的身份验证方式。 Azure AD 中的身份验证方法包括密码和手机(例如,短信和语音呼叫),目前可在 Microsoft Graph 中对这些方法进行管理,此外还有 FIDO2 安全密钥和 Microsoft Authenticator 应用。 身份验证方法用于主要、双重因素和分步身份验证,此外还适用于自助式密码重置 (SSPR) 流程。

可使用身份验证方法 API 来管理用户的身份验证方法。例如,你可以:

  • 为用户添加一个电话号码,通过策略启用短信和语音呼叫身份验证后,该用户即可使用该号码进行此类身份验证
  • 更新或删除分配给用户的电话号码
  • 启用或禁用用于短信登录的号码
  • 重置用户密码

API 是用于管理用户身份验证方法的一种关键工具。

在本教程中,你将学习如何:

  • 使用正确的角色和权限对 Azure AD 进行身份验证
  • 检查用户的身份验证方法
  • 为用户添加新的电话号码
  • 删除用户的电话号码
  • 重置用户密码

步骤 1:使用正确的角色和权限对 Azure AD 进行身份验证

使用你喜欢的工具与 Microsoft Graph 交互,使用具有以下一种角色的帐户登录:

  • 全局管理员
  • 特权身份验证管理员
  • 身份验证管理员

接下来,修改你的权限。 在本教程中,我们将使用 UserAuthenticationMethod.ReadWrite.All,因此,请确保已在 Graph 浏览器或你的应用中启用此权限。

分配范围并获得同意后,即可开始使用 API。 此处的示例使用名为 Avery Howard 的标准用户。 您应该使用现有的测试帐户,或按照这些说明创建一个新的测试帐户。 这些 API 是实时的,因此请不要在实际用户上对其进行测试。

步骤 2:检查用户的身份验证方法

拨打电话,以查看用户的身份验证方法。 获取 URL 以查看用户的个人资料并添加 /authentication/methods

请求

GET https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/methods

响应

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/methods",
    "value": [
        {
            "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
            "id": "28c10230-6103-485e-b985-444c60001490",
            "password": null,
            "creationDateTime": null
        }
    ]
}

步骤 3:为用户添加新的电话号码

在上一步中,新用户 (Avery) 仅注册了密码。 若要分配新的电话号码供 Avery 使用,请在正文中使用电话类型和号码发出 POST 请求。 若要告知系统正在添加电话号码,还需要将 URL 的末尾从 methods 更改为 phoneMethods

请求

POST https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods
Content-Type: application/json
{
    "phoneType": "mobile",
    "phoneNumber": "+1 2065550123"
}

响应

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/phoneMethods/$entity",
    "id": "3179e48a-750b-4051-897c-87b9720928f7",
    "phoneNumber": "+1 2065550123",
    "phoneType": "mobile",
    "smsSignInState": "ready"
}

要添加 Avery 的办公室号码,你将再次POST访问相同的 URL,但要更新电话类型和电话号码:

请求

POST https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods
Content-Type: application/json
{
    "phoneType": "office",
    "phoneNumber": "+1 4255550199"
}

响应

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/phoneMethods/$entity",
    "id": "e37fc753-ff3b-4958-9484-eaa9425c82bc",
    "phoneNumber": "+1 4255550199",
    "phoneType": "office",
    "smsSignInState": "notSupported"
}

对电话方法 URL 再执行一次 GET,以查看 Avery 的所有电话号码:

请求

GET https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods

响应

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/phoneMethods",
    "value": [
        {
            "id": "e37fc753-ff3b-4958-9484-eaa9425c82bc",
            "phoneNumber": "+1 4255550199",
            "phoneType": "office",
            "smsSignInState": "notSupported"
        },
        {
            "id": "3179e48a-750b-4051-897c-87b9720928f7",
            "phoneNumber": "+1 2065550123",
            "phoneType": "mobile",
            "smsSignInState": "ready"
        }
    ]
}

确认你可以按预期看到这两个号码。

步骤 4:删除用户的电话号码

在本场景中,Avery 现在在家工作,你需要从他们的帐户中删除他们的办公室号码。 需要在办公室电话 URL 上呼叫 DELETE,可以通过将办公室电话的 ID 附加到电话方法 URL 来创建办公室电话 URL。 查看上面的 Avery 电话列表:办公室电话 ID 以“e37f”开头。

请求

DELETE https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/phoneMethods/e37fc753-ff3b-4958-9484-eaa9425c82bc

响应中没有数据,因为没有更多符合预期的办公室电话。 可通过查看 Avery 的所有方法来确认它已删除,与之前的发出的 GET 相同:

请求

GET https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/methods

响应

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('avery.howard%40wingtiptoysonline.com')/authentication/methods",
    "value": [
        {
            "@odata.type": "#microsoft.graph.phoneAuthenticationMethod",
            "id": "3179e48a-750b-4051-897c-87b9720928f7",
            "phoneNumber": "+1 2065550123",
            "phoneType": "mobile",
            "smsSignInState": "ready"
        },
        {
            "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
            "id": "28c10230-6103-485e-b985-444c60001490",
            "password": null,
            "creationDateTime": null
        }
    ]
}

正如预期的那样,用户现在又回到只有一部手机和一个密码的状态。

步骤 5:重置用户密码

在此场景中,Avery 忘记了密码,你需要为他们重置。 若要重置密码,你需要向其密码的 URL 发出 POST(请查看 Avery 身份验证方法列表中以“28c1”开头的 ID),并指定“resetPassword”操作。 在请求正文中提供新密码。

请求

POST https://graph.microsoft.com/beta/users/avery.howard@wingtiptoysonline.com/authentication/passwordMethods/28c10230-6103-485e-b985-444c60001490/resetPassword
Content-Type: application/json
{
    "newPassword": "29sdjfw#fajsdA_a_3an3223"
}

响应

Location: https://graph.microsoft.com/beta/users/ed178e23-7447-4892-baf8-fc46f8af26ce/authentication/operations/74bfa1a6-c0e0-4957-8c37-f91048f4959e?aadgdc=BY01P&aadgsu=ssprprod-a

由于这是将密码向下同步到租户的本地基础结构中的 Active Directory,可能需要几分钟,因此你有一个可以查看其是否完整的地址。 此地址位于响应的位置标头中,可查看该 URL 上的 GET 状态。

请求

GET https://graph.microsoft.com/beta/users/ed178e23-7447-4892-baf8-fc46f8af26ce/authentication/operations/74bfa1a6-c0e0-4957-8c37-f91048f4959e?aadgdc=BY01P&aadgsu=ssprprod-a

响应

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('ed178e23-7447-4892-baf8-fc46f8af26ce')/authentication/operations/$entity",
    "id": "74bfa1a6-c0e0-4957-8c37-f91048f4959e",
    "createdDateTime": "2020-05-14T00:23:40Z",
    "lastActionDateTime": "2020-05-14T00:23:41Z",
    "status": "succeeded",
    "statusDetail": "ResetSuccess",
    "resourceLocation": "https://graph.microsoft.com/beta/users/ed178e23-7447-4892-baf8-fc46f8af26ce/authentication/methods/28c10230-6103-485e-b985-444c60001490"
}

成功! 你已经演练了查看用户个人资料、查看用户的身份验证方法、添加和删除电话号码以及重置用户密码。 现在可以开始管理自己用户的方法了。

API 参考

在查找身份验证方法的 API 参考?

后续步骤