Управление методами проверки подлинности пользователей с помощью Microsoft Graph
Статья
Методы проверки подлинности — это способы проверки подлинности пользователей в идентификаторе Microsoft Entra. В настоящее время в Идентификаторе Microsoft Entra доступны следующие методы проверки подлинности, которыми можно управлять с помощью Microsoft Graph:
Windows Hello для бизнеса
Microsoft Authenticator
Ключ безопасности FIDO2
Проверка подлинности на основе сертификатов
Токены оборудования OATH (предварительная версия)
Токены программного обеспечения OATH
Временный пропуск доступа (TAP)
SMS
Голос
Пароль
Способы проверки подлинности используются в ходе основной, двухфакторной проверки подлинности, проверки подлинности повышенного уровня, а также в процессе самостоятельного сброса пароля (SSPR).
Что можно сделать с API методов проверки подлинности?
Api методов проверки подлинности можно использовать для интеграции с приложениями для управления методами проверки подлинности пользователя. Например, вы можете:
добавить номер телефона пользователя, который затем он может использовать для проверки подлинности с помощью SMS и голосового вызова, если применение такого способа разрешено политикой;
обновить или удалить номер телефона, назначенный пользователю;
включить или отключить номер для входа с помощью SMS;
сбросить пароль пользователя.
Важно!
Мы не рекомендуем использовать API-интерфейсы методов проверки подлинности для сценариев, в которых необходимо выполнить итерацию по всей вашей совокупности пользователей для аудита или проверки безопасности. В таких сценариях рекомендуется использовать API регистрации метода проверки подлинности и отчетов об использовании (некоторые API доступны только в конечной точке beta ).
Использование политик для управления методами проверки подлинности в клиенте
Вы можете выбрать, какие методы проверки подлинности разрешены для пользователей в клиенте, настроив политики методов проверки подлинности. Для каждой политики необходимо настроить, включен ли метод проверки подлинности, его параметры и можно явно определить группы пользователей, которым разрешено или запрещено использовать метод.
Пример сценария
Из этой статьи вы узнаете, как:
Проверка подлинности в Идентификаторе Microsoft Entra с правильными ролями и разрешениями
Шаг 1. Проверка подлинности в Microsoft Entra ID с правильными ролями и разрешениями
Войдите в клиент API, например Graph Explorer , с учетной записью, которая имеет по крайней мере роль Администратора привилегированной проверки подлинности или Администратора проверки подлинностиMicrosoft Entra. Для тестирования API можно использовать тестовый клиент с примерами данных.
Затем предоставьте приложению разрешение UserAuthenticationMethod.ReadWrite.All . Это разрешение требуется для выполнения операций чтения и записи в этом сценарии.
Теперь вы можете приступить к использованию API. В этом сценарии api используются для управления методами проверки подлинности Кэмерона Уайта.
Этап 2: проверка способов проверки подлинности пользователя
GET https://graph.microsoft.com/v1.0/users/[email protected]/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();
// 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();
# 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()
В этом ответе у Кэмерона включен только метод проверки подлинности паролем.
28c10230-6103-485e-b985-444c60001490 — это глобальный уникальный идентификатор метода проверки подлинности паролем в microsoft Entra 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: добавление новых номеров телефонов пользователю
На этом шаге вы добавите новый номер мобильного телефона, который будет использоваться Кэмероном.
// 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);
// 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);
<?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();
# 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)
GET https://graph.microsoft.com/v1.0/users/[email protected]/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();
// 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();
# 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"
}
]
}
Убедитесь, что вы видите оба номера, как и предполагалось. Идентификаторы разных типов номеров телефонов во всем мире одинаковы для идентификатора Microsoft Entra следующим образом:
b6332ec1-7057-4abe-9331-3d72feddfe41 для альтернативного типа мобильного телефона
e37fc753-ff3b-4958-9484-eaa9425c82bc для типа офисного телефона
3179e48a-750b-4051-897c-87b9720928f7 для типа мобильного телефона
Шаг 5. Удаление номера телефона у пользователя
Кэмерон теперь работает из дома, поэтому вам нужно удалить номер офиса из его учетной записи.
// 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();
// 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();
<?php
use Microsoft\Graph\GraphServiceClient;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$graphServiceClient->users()->byUserId('user-id')->authentication()->phoneMethods()->byPhoneAuthenticationMethodId('phoneAuthenticationMethod-id')->delete()->wait();
# 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. Чтобы убедиться, что метод office phone удален из учетной записи Кэмерона, повторно выполните запрос на шаге 4. Кэмерон теперь должен иметь только мобильный телефон и методы проверки подлинности пароля.
Шаг 6. Сброс пароля пользователя
Кэмерон забыл свой пароль, и вам нужно сбросить его для них. Вы можете сбросить пароль пользователя и указать временный пароль или разрешить идентификатору Microsoft Entra создать временный пароль.
В обоих методах ответ включает заголовок Location с URL-адресом, который можно использовать для проверки состояния операции с помощью операции GET. Операция сброса не завершается сразу, так как идентификатор Microsoft Entra должен синхронизировать пароль, в том числе вплоть до Active Directory в локальной инфраструктуре клиента (для локальных пользователей). URL-адрес действителен в течение 24 часов.
Вариант 1. Сброс пароля пользователя и ввод временного нового пароля
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";
});
// 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.UserItemAuthenticationOperationItemRequestBuilderGetQueryParameters{
Aadgdc: &requestAadgdc,
Aadgsu: &requestAadgsu,
}
configuration := &graphusers.UserItemAuthenticationOperationItemRequestBuilderGetRequestConfiguration{
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";
});
# 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 для способов проверки подлинности?