Microsoft Graph 身份验证方法 API 入门Get started with the Microsoft Graph authentication methods API

身份验证方法 是用户在 Azure Active Directory (Azure AD) 中的身份验证方式。Authentication methods are the ways that users authenticate in Azure Active Directory (Azure AD). Azure AD 中的身份验证方法包括密码和手机(例如,短信和语音呼叫),目前可在 Microsoft Graph 中对这些方法进行管理,此外还有 FIDO2 安全密钥和 Microsoft Authenticator 应用。Authentication methods in Azure AD include password and phone (for example, SMS and voice calls), which are manageable in Microsoft Graph today, among many others such as FIDO2 security keys and the Microsoft Authenticator app. 身份验证方法用于主要、双重因素和分步身份验证,此外还适用于自助式密码重置 (SSPR) 流程。Authentication methods are used in primary, second-factor, and step-up authentication, and also in the self-service password reset (SSPR) process.

可使用身份验证方法 API 来管理用户的身份验证方法。You can use the authentication method APIs to manage a user's authentication methods. 例如,你能够:For example, you can:

  • 为用户添加一个电话号码,通过策略启用短信和语音呼叫身份验证后,该用户即可使用该号码进行此类身份验证Add a phone number for a user, who can then use that number for SMS and voice call authentication if they're enabled to use it by policy
  • 更新或删除分配给用户的电话号码Update or delete the phone number assigned to a user
  • 启用或禁用用于短信登录的号码Enable or disable the number for SMS sign-in
  • 重置用户密码Reset a user's password

API 是用于管理用户身份验证方法的一种关键工具。The APIs are a key tool to manage your users' authentication methods.

在本教程中,你将学习如何:In this tutorial, you'll learn how to:

  • 使用正确的角色和权限对 Azure AD 进行身份验证Authenticate to Azure AD with the right roles and permissions
  • 检查用户的身份验证方法Check the user's authentication methods
  • 为用户添加新的电话号码Add new phone numbers for the user
  • 删除用户的电话号码Remove a phone number from the user
  • 重置用户密码Reset the user's password

步骤 1:使用正确的角色和权限对 Azure AD 进行身份验证Step 1: Authenticate to Azure AD with the right roles and permissions

使用你喜欢的工具与 Microsoft Graph 交互,使用具有以下一种角色的帐户登录:Using your favorite tool for interacting with Microsoft Graph, sign in using an account with one of these roles:

  • 全局管理员Global administrator
  • 特权身份验证管理员Privileged authentication administrator
  • 身份验证管理员Authentication administrator

接下来,修改你的权限。Next, modify your permissions. 在本教程中,我们将使用 UserAuthenticationMethod.ReadWrite.All,因此,请确保已在 Graph 浏览器或你的应用中启用此权限。We'll use UserAuthenticationMethod.ReadWrite.All for this tutorial, so make sure it's enabled in Graph Explorer or your app.

分配范围并获得同意后,即可开始使用 API。Once the scope is assigned and consented, you can start using the API. 此处的示例使用名为 Avery Howard 的标准用户。The examples here use a standard user named Avery Howard. 您应该使用现有的测试帐户,或按照这些说明创建一个新的测试帐户。You should use a preexisting test account or create a new one following these instructions. 这些 API 是实时的,因此请不要在实际用户上对其进行测试。These APIs are live so don't test them on real users.

步骤 2:检查用户的身份验证方法Step 2: Check the user's authentication methods

拨打电话,以查看用户的身份验证方法。Make a call to see the user's authentication methods. 获取 URL 以查看用户的个人资料并添加 /authentication/methodsTake the URL to see a user's profile and add /authentication/methods:

请求Request

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

响应Response

{
    "@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:为用户添加新的电话号码Step 3: Add new phone numbers for the user

在上一步中,新用户 (Avery) 仅注册了密码。From the previous step, a new user (Avery) only has a password registered. 若要分配新的电话号码供 Avery 使用,请在正文中使用电话类型和号码发出 POST 请求。To assign a new phone number for Avery to use, make a POST request with the phone type and number in the body. 若要告知系统正在添加电话号码,还需要将 URL 的末尾从 methods 更改为 phoneMethodsTo tell the system that a phone number is being added, you'll also need to change the end of the URL from methods to phoneMethods.

请求Request

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

响应Response

{
    "@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,但要更新电话类型和电话号码:To add Avery's office number, you'll POST again to the same URL but update the phone type and number:

请求Request

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

响应Response

{
    "@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 的所有电话号码:Do one more GET to the phone methods URL to see all of Avery's phone numbers:

请求Request

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

响应Response

{
    "@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"
        }
    ]
}

确认你可以按预期看到这两个号码。Confirm that you can see both numbers as expected.

步骤 4:删除用户的电话号码Step 4: Remove a phone number from the user

在本场景中,Avery 现在在家工作,你需要从他们的帐户中删除他们的办公室号码。In this scenario, Avery is now working from home you need to remove their office number from their account. 需要在办公室电话 URL 上呼叫 DELETE,可以通过将办公室电话的 ID 附加到电话方法 URL 来创建办公室电话 URL。You need to call DELETE on the office phone URL, which you can create by appending the office phone's ID to the phone methods URL. 查看上面的 Avery 电话列表:办公室电话 ID 以“e37f”开头。Look at Avery's list of phones above: the office phone ID starts with "e37f".

请求Request

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

响应中没有数据,因为没有更多符合预期的办公室电话。There's no data in the response because there's no more office phone as intended. 可通过查看 Avery 的所有方法来确认它已删除,与之前的发出的 GET 相同:You can confirm it's gone by looking at all of Avery's methods, which is the same GET that was made previously:

请求Request

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

响应Response

{
    "@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
        }
    ]
}

正如预期的那样,用户现在又回到只有一部手机和一个密码的状态。As expected, the user is now back to only having one mobile phone and a password.

步骤 5:重置用户密码Step 5: Reset the user's password

在此场景中,Avery 忘记了密码,你需要为他们重置。In this scenario, Avery has forgotten their password and you need to reset it for them. 若要重置密码,你需要向其密码的 URL 发出 POST(请查看 Avery 身份验证方法列表中以“28c1”开头的 ID),并指定“resetPassword”操作。To reset, you'll make a POST to their password's URL (see the ID starting with "28c1" above in Avery's list of authentication methods), specifying the "resetPassword" action. 在请求正文中提供新密码。Provide the new password in the request body.

请求Request

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"
}

响应Response

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,可能需要几分钟,因此你有一个可以查看其是否完整的地址。Because this is syncing the password down to Active Directory in the tenant's on-prem infrastructure, it might take a few minutes, so you have an address where you can check to see if it's complete. 此地址位于响应的位置标头中,可查看该 URL 上的 GET 状态。This address is in the location header of the response, and to see the status do a GET on that URL.

请求Request

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

响应Response

{
    "@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"
}

成功!And success! 你已经演练了查看用户个人资料、查看用户的身份验证方法、添加和删除电话号码以及重置用户密码。You've walked through seeing a user's profile, their auth methods, adding and removing phone numbers, and resetting their password. 现在可以开始管理自己用户的方法了。Now you're ready to go manage your own users' methods.

API 参考API reference

在查找身份验证方法的 API 参考?Looking for the API reference for authentication methods?

后续步骤Next steps