Управление методами проверки подлинности пользователей с помощью Microsoft Graph

Методы проверки подлинности — это способы проверки подлинности пользователей в Microsoft Entra ID. На сегодняшний день в Microsoft Entra ID доступны следующие методы проверки подлинности, которыми можно управлять с помощью Microsoft Graph:

  • Windows Hello для бизнеса
  • Microsoft Authenticator
  • Ключ безопасности FIDO2
  • Проверка подлинности на основе сертификатов
  • Токены оборудования OATH (предварительная версия)
  • Токены программного обеспечения OATH
  • Временный пропуск доступа (TAP)
  • SMS
  • Голос
  • Пароль

Способы проверки подлинности используются в ходе основной, двухфакторной проверки подлинности, проверки подлинности повышенного уровня, а также в процессе самостоятельного сброса пароля (SSPR).

Что можно сделать с API методов проверки подлинности?

Api методов проверки подлинности можно использовать для интеграции с приложениями для управления методами проверки подлинности пользователя. Например, вы можете:

  • добавить номер телефона пользователя, который затем он может использовать для проверки подлинности с помощью SMS и голосового вызова, если применение такого способа разрешено политикой;
  • обновить или удалить номер телефона, назначенный пользователю;
  • включить или отключить номер для входа с помощью SMS;
  • сбросить пароль пользователя.

Важно!

Мы не рекомендуем использовать API-интерфейсы методов проверки подлинности для сценариев, в которых необходимо выполнить итерацию по всей вашей совокупности пользователей для аудита или обеспечения безопасности проверка целях. В таких сценариях рекомендуется использовать API регистрации метода проверки подлинности и отчетов об использовании (некоторые API доступны только в конечной точке beta ).

Использование политик для управления методами проверки подлинности в клиенте

Вы можете выбрать, какие методы проверки подлинности разрешены для пользователей в клиенте, настроив политики методов проверки подлинности. Для каждой политики необходимо настроить, включен ли метод проверки подлинности, его параметры и можно явно определить группы пользователей, которым разрешено или запрещено использовать метод.

Пример сценария

Из этой статьи вы узнаете, как:

  • Проверка подлинности для Microsoft Entra ID с правильными ролями и разрешениями
  • проверять способы проверки подлинности пользователя;
  • добавлять новые номера телефонов пользователю;
  • удалять номера телефона у пользователя;
  • сбрасывать пароль пользователя.

Шаг 1. Проверка подлинности для Microsoft Entra ID с правильными ролями и разрешениями

Войдите в клиент API, например Graph Обозреватель с учетной записью, которая имеет по крайней мере роль администратора привилегированной проверки подлинности или администратора проверки подлинностиMicrosoft Entra. Для тестирования API можно использовать тестовый клиент с примерами данных.

Затем предоставьте приложению разрешение UserAuthenticationMethod.ReadWrite.All . Это разрешение требуется для выполнения операций чтения и записи в этом сценарии.

Теперь вы можете приступить к использованию API. В этом сценарии api используются для управления методами проверки подлинности Кэмерона Уайта.

Этап 2: проверка способов проверки подлинности пользователя

Запрос

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

Отклик

В этом ответе у Кэмерона включен только метод проверки подлинности паролем. 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: добавление новых номеров телефонов пользователю

На этом шаге вы добавите новый номер мобильного телефона, который будет использоваться Кэмероном.

Запрос

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

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

Отклик

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

Отклик

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 ID следующим образом:

  • b6332ec1-7057-4abe-9331-3d72feddfe41 для альтернативного типа мобильного телефона
  • 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

Запрос возвращает код отклика 204 No Content. Чтобы убедиться, что метод office phone удален из учетной записи Кэмерона, повторно выполните запрос на шаге 4. Кэмерон теперь должен иметь только мобильный телефон и методы проверки подлинности пароля.

Шаг 6. Сброс пароля пользователя

Кэмерон забыл свой пароль, и вам нужно сбросить его для них. Вы можете сбросить пароль пользователя и указать временный пароль или позволить Microsoft Entra ID создать временный пароль.

В обоих методах ответ включает заголовок Location с URL-адресом, который можно использовать для проверка состояния операции с помощью операции GET. Операция сброса не завершается сразу, так как 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"
}

Отклик

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

Отклик

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 для способов проверки подлинности?