使用 Microsoft Graph 管理用户的身份验证方法

项目
03/21/2024

身份验证方法是用户在 Entra ID Microsoft进行身份验证的方式。以下身份验证方法目前在 Microsoft Entra ID 中可用，可通过 Microsoft Graph 进行管理：

Windows Hello 企业版
Microsoft Authenticator
FIDO2 安全密钥
基于证书的身份验证
OATH 硬件令牌 (预览)
OATH 软件令牌
临时访问密码 (TAP)
短信
语音
Password

身份验证方法用于主要、双重因素和分步身份验证，此外还适用于自助式密码重置 (SSPR) 流程。

可以使用身份验证方法 API 做什么？

可以使用身份验证方法 API 集成到应用，以管理用户的身份验证方法。例如，你能够：

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

重要

对于需要循环访问整个用户群体以实现审核或安全检查目的的方案，建议不要使用身份验证方法 API。对于这些类型的方案，我们建议使用身份验证方法注册和使用情况报告 API ， (某些 API 仅在终结点上 beta 可用) 。

使用策略管理租户中的身份验证方法

可以通过配置身份验证方法策略，选择租户中用户允许的 身份验证方法。对于每个策略，可以配置是否启用身份验证方法及其设置，并且可以显式定义允许或不允许使用方法的用户组。

示例应用场景

本文介绍如何：

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

步骤 1：使用正确的角色和权限Microsoft Entra ID 进行身份验证

使用至少具有 Privileged Authentication Administrator 或 Authentication AdministratorMicrosoft Entra 角色的帐户登录到 API 客户端（例如 Graph 资源管理器）。可以使用包含示例数据的测试租户来试用 API。

接下来，向应用授予 UserAuthenticationMethod.ReadWrite.All 权限。需要此权限才能在此方案中执行读取和写入操作。

现在可以开始使用 API。在此方案中，使用 API 来管理 Cameron White 的身份验证方法。

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

请求

GET https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/methods


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.Methods.GetAsync();



mgc users authentication methods list --user-id {user-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
methods, err := graphClient.Users().ByUserId("user-id").Authentication().Methods().Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

AuthenticationMethodCollectionResponse result = graphClient.users().byUserId("{user-id}").authentication().methods().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let methods = await client.api('/users/CameronW@Contoso.com/authentication/methods')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->users()->byUserId('user-id')->authentication()->methods()->get()->wait();


Import-Module Microsoft.Graph.Identity.SignIns

Get-MgUserAuthenticationMethod -UserId $userId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.users.by_user_id('user-id').authentication.methods.get()

响应

在此响应中，Cameron 仅启用了密码身份验证方法。 28c10230-6103-485e-b985-444c60001490 是跨 Microsoft Entra ID 的密码身份验证方法的全局唯一 ID。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('CameronW%40contoso.com')/authentication/methods",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users('<key>')/authentication/methods?$select=id",
    "value": [
        {
            "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
            "id": "28c10230-6103-485e-b985-444c60001490",
            "password": null,
            "createdDateTime": "2023-09-18T10:38:07Z"
        }
    ]
}

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

在此步骤中，将添加一个新的移动电话号码供 Cameron 使用。

请求

POST https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/phoneMethods
Content-Type: application/json

{
    "phoneNumber": "+1 2065555555",
    "phoneType": "mobile"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new PhoneAuthenticationMethod
{
	PhoneNumber = "+1 2065555555",
	PhoneType = AuthenticationPhoneType.Mobile,
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.PhoneMethods.PostAsync(requestBody);



mgc users authentication phone-methods create --user-id {user-id} --body '{\
    "phoneNumber": "+1 2065555555",\
    "phoneType": "mobile"\
}\
'



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewPhoneAuthenticationMethod()
phoneNumber := "+1 2065555555"
requestBody.SetPhoneNumber(&phoneNumber) 
phoneType := graphmodels.MOBILE_AUTHENTICATIONPHONETYPE 
requestBody.SetPhoneType(&phoneType) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
phoneMethods, err := graphClient.Users().ByUserId("user-id").Authentication().PhoneMethods().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

PhoneAuthenticationMethod phoneAuthenticationMethod = new PhoneAuthenticationMethod();
phoneAuthenticationMethod.setPhoneNumber("+1 2065555555");
phoneAuthenticationMethod.setPhoneType(AuthenticationPhoneType.Mobile);
PhoneAuthenticationMethod result = graphClient.users().byUserId("{user-id}").authentication().phoneMethods().post(phoneAuthenticationMethod);


const options = {
	authProvider,
};

const client = Client.init(options);

const phoneAuthenticationMethod = {
    phoneNumber: '+1 2065555555',
    phoneType: 'mobile'
};

await client.api('/users/CameronW@Contoso.com/authentication/phoneMethods')
	.post(phoneAuthenticationMethod);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\PhoneAuthenticationMethod;
use Microsoft\Graph\Generated\Models\AuthenticationPhoneType;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new PhoneAuthenticationMethod();
$requestBody->setPhoneNumber('+1 2065555555');
$requestBody->setPhoneType(new AuthenticationPhoneType('mobile'));

$result = $graphServiceClient->users()->byUserId('user-id')->authentication()->phoneMethods()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Identity.SignIns

$params = @{
	phoneNumber = "+1 2065555555"
	phoneType = "mobile"
}

New-MgUserAuthenticationPhoneMethod -UserId $userId -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.phone_authentication_method import PhoneAuthenticationMethod
from msgraph.generated.models.authentication_phone_type import AuthenticationPhoneType
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = PhoneAuthenticationMethod(
	phone_number = "+1 2065555555",
	phone_type = AuthenticationPhoneType.Mobile,
)

result = await graph_client.users.by_user_id('user-id').authentication.phone_methods.post(request_body)

响应

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('CameronW%40contoso.com')/authentication/phoneMethods/$entity",
    "id": "3179e48a-750b-4051-897c-87b9720928f7",
    "phoneNumber": "+1 2065555555",
    "phoneType": "mobile",
    "smsSignInState": "notAllowedByPolicy"
}

运行相同的请求，添加 Office phoneType。

步骤 4：验证用户的身份验证方法

请求

GET https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/methods


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.Methods.GetAsync();



mgc users authentication methods list --user-id {user-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
methods, err := graphClient.Users().ByUserId("user-id").Authentication().Methods().Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

AuthenticationMethodCollectionResponse result = graphClient.users().byUserId("{user-id}").authentication().methods().get();


const options = {
	authProvider,
};

const client = Client.init(options);

let methods = await client.api('/users/CameronW@Contoso.com/authentication/methods')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->users()->byUserId('user-id')->authentication()->methods()->get()->wait();


Import-Module Microsoft.Graph.Identity.SignIns

Get-MgUserAuthenticationMethod -UserId $userId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.users.by_user_id('user-id').authentication.methods.get()

响应

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('CameronW%40contoso.com')/authentication/methods",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users('<key>')/authentication/methods?$select=id",
    "value": [
        {
            "@odata.type": "#microsoft.graph.phoneAuthenticationMethod",
            "id": "e37fc753-ff3b-4958-9484-eaa9425c82bc",
            "phoneNumber": "+1 4255550199",
            "phoneType": "office",
            "smsSignInState": "notSupported"
        },
        {
            "@odata.type": "#microsoft.graph.phoneAuthenticationMethod",
            "id": "3179e48a-750b-4051-897c-87b9720928f7",
            "phoneNumber": "+1 2065555555",
            "phoneType": "mobile",
            "smsSignInState": "notAllowedByPolicy"
        },
        {
            "@odata.type": "#microsoft.graph.passwordAuthenticationMethod",
            "id": "28c10230-6103-485e-b985-444c60001490",
            "password": null,
            "createdDateTime": "2023-09-18T10:38:07Z"
        }
    ]
}

确认你可以按预期看到这两个号码。不同电话号码类型的 ID 在Microsoft Entra ID 中全局相同，如下所示：

b6332ec1-7057-4abe-9331-3d72feddfe41 for alternateMobile Phone type
e37fc753-ff3b-4958-9484-eaa9425c82bc 对于办公电话类型
3179e48a-750b-4051-897c-87b9720928f7 手机类型

步骤 5：删除用户的电话号码

卡梅伦现在在家工作，所以你需要从他的帐户中删除 办公室 号码。

DELETE https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/phoneMethods/e37fc753-ff3b-4958-9484-eaa9425c82bc


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Users["{user-id}"].Authentication.PhoneMethods["{phoneAuthenticationMethod-id}"].DeleteAsync();



mgc users authentication phone-methods delete --user-id {user-id} --phone-authentication-method-id {phoneAuthenticationMethod-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Users().ByUserId("user-id").Authentication().PhoneMethods().ByPhoneAuthenticationMethodId("phoneAuthenticationMethod-id").Delete(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

graphClient.users().byUserId("{user-id}").authentication().phoneMethods().byPhoneAuthenticationMethodId("{phoneAuthenticationMethod-id}").delete();


const options = {
	authProvider,
};

const client = Client.init(options);

await client.api('/users/CameronW@Contoso.com/authentication/phoneMethods/e37fc753-ff3b-4958-9484-eaa9425c82bc')
	.delete();


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$graphServiceClient->users()->byUserId('user-id')->authentication()->phoneMethods()->byPhoneAuthenticationMethodId('phoneAuthenticationMethod-id')->delete()->wait();


Import-Module Microsoft.Graph.Identity.SignIns

Remove-MgUserAuthenticationPhoneMethod -UserId $userId -PhoneAuthenticationMethodId $phoneAuthenticationMethodId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

await graph_client.users.by_user_id('user-id').authentication.phone_methods.by_phone_authentication_method_id('phoneAuthenticationMethod-id').delete()

请求会返回 204 No Content 响应代码。若要验证是否已从 Cameron 的帐户中删除 了 Office 电话方法，请在步骤 4 中重新运行请求。卡梅隆现在应该只有手机和密码身份验证方法。

步骤 6：重置用户密码

卡梅隆忘记了他们的密码，你需要为他们重置密码。可以重置用户的密码并指定临时密码，也可以让Microsoft Entra ID 生成临时密码。

在这两种方法中，响应都包含一个 Location 标头，其中包含可用于通过 GET 操作检查操作状态的 URL。重置操作不会立即完成，因为Microsoft Entra ID 需要同步密码，包括租户的本地基础结构中的 Active Directory， (本地用户) 。该 URL 的有效期为 24 小时。

选项 1：重置用户密码并提供临时新密码

请求

POST https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/passwordMethods/28c10230-6103-485e-b985-444c60001490/resetPassword
Content-Type: application/json

{
    "newPassword": "29sdjfw#fajsdA_a_3an3223"
}

Snippet not available

Snippet not available

Snippet not available

Snippet not available


const options = {
	authProvider,
};

const client = Client.init(options);

const passwordResetResponse = {
    newPassword: '29sdjfw#fajsdA_a_3an3223'
};

await client.api('/users/CameronW@Contoso.com/authentication/passwordMethods/28c10230-6103-485e-b985-444c60001490/resetPassword')
	.post(passwordResetResponse);

Snippet not available

Snippet not available

Snippet not available

响应

HTTP/1.1 202 Accepted

Location: https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/operations/cc8e9b0e-7495-47f2-ad4a-3daa966543c6?aadgdc=DUB02P&aadgsu=ssprprod-a

选项 2：重置用户的密码，让Microsoft Entra ID 生成临时新密码

在此请求中，你不会提供新密码，而是让Microsoft Entra ID 生成密码并在响应中返回密码。

POST https://graph.microsoft.com/v1.0/users/CameronW@Contoso.com/authentication/passwordMethods/28c10230-6103-485e-b985-444c60001490/resetPassword

响应

HTTP/1.1 202 Accepted

Location: https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/operations/ba0c9a11-5163-4353-89ba-81501617ede0?aadgdc=AM4P&aadgsu=ssprprod-a
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.passwordResetResponse",
    "newPassword": "Hopu0277"
}

检查密码重置操作的状态

请求

GET https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/operations/ba0c9a11-5163-4353-89ba-81501617ede0?aadgdc=AM4P&aadgsu=ssprprod-a


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.Operations["{longRunningOperation-id}"].GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Aadgdc = "AM4P";
	requestConfiguration.QueryParameters.Aadgsu = "ssprprod-a";
});



mgc users authentication operations get --user-id {user-id} --long-running-operation-id {longRunningOperation-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)


requestAadgdc := "AM4P"
requestAadgsu := "ssprprod-a"

requestParameters := &graphusers.ItemAuthenticationOperationsItemRequestBuilderGetQueryParameters{
	Aadgdc: &requestAadgdc,
	Aadgsu: &requestAadgsu,
}
configuration := &graphusers.ItemAuthenticationOperationsItemRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
operations, err := graphClient.Users().ByUserId("user-id").Authentication().Operations().ByLongRunningOperationId("longRunningOperation-id").Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

LongRunningOperation result = graphClient.users().byUserId("{user-id}").authentication().operations().byLongRunningOperationId("{longRunningOperation-id}").get(requestConfiguration -> {
	requestConfiguration.queryParameters.aadgdc = "AM4P";
	requestConfiguration.queryParameters.aadgsu = "ssprprod-a";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let longRunningOperation = await client.api('/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/operations/ba0c9a11-5163-4353-89ba-81501617ede0?aadgdc=AM4P&aadgsu=ssprprod-a')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Users\Item\Authentication\Operations\Item\LongRunningOperationItemRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new LongRunningOperationItemRequestBuilderGetRequestConfiguration();
$queryParameters = LongRunningOperationItemRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->aadgdc = "AM4P";
$queryParameters->aadgsu = "ssprprod-a";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->users()->byUserId('user-id')->authentication()->operations()->byLongRunningOperationId('longRunningOperation-id')->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Identity.SignIns

Get-MgUserAuthenticationOperation -UserId $userId -LongRunningOperationId $longRunningOperationId -Aadgdc "AM4P" -Aadgsu "ssprprod-a"


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.users.item.authentication.operations.item.long_running_operation_item_request_builder import LongRunningOperationItemRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
query_params = LongRunningOperationItemRequestBuilder.LongRunningOperationItemRequestBuilderGetQueryParameters(
		aadgdc = "AM4P",
		aadgsu = "ssprprod-a",
)

request_configuration = RequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.by_user_id('user-id').authentication.operations.by_long_running_operation_id('longRunningOperation-id').get(request_configuration = request_configuration)

响应

HTTP/1.1 202 Accepted

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('a87cc624-b550-4559-b934-3bc0325a4808')/authentication/operations/$entity",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET users('<guid>')/authentication/operations('<guid>')?$select=createdDateTime,lastActionDateTime",
    "id": "ba0c9a11-5163-4353-89ba-81501617ede0",
    "createdDateTime": "2024-01-18T16:37:10Z",
    "lastActionDateTime": "2024-01-18T16:37:10Z",
    "status": "succeeded",
    "statusDetail": "ResetSuccess",
    "resourceLocation": "https://graph.microsoft.com/v1.0/users/a87cc624-b550-4559-b934-3bc0325a4808/authentication/methods/28c10230-6103-485e-b985-444c60001490"
}

API 参考

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

请参阅 Microsoft Entra 身份验证方法 API 概述
请参阅 Microsoft Entra 身份验证方法策略 API 参考

通过