Управление аппаратными токенами OATH в идентификаторе Microsoft Entra (предварительная версия)

Статья
03/04/2025

В этом разделе описывается, как управлять аппаратными токенами присяги в идентификаторе Microsoft Entra, включая API Microsoft Graph, которые можно использовать для отправки, активации и назначения аппаратных токенов OATH.

Включение аппаратных токенов OATH в политике методов проверки подлинности

Вы можете просматривать и включать аппаратные токены OATH в политике методов проверки подлинности с помощью API Microsoft Graph или Центра администрирования Microsoft Entra.

Чтобы просмотреть состояние политики токенов OATH оборудования с помощью API:
```
GET https://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/hardwareOath
```
Чтобы включить политику аппаратных токенов OATH с помощью API.
```
PATCH https://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/hardwareOath
```
В тексте запроса добавьте:
```
{
  "state": "enabled"
}
```

Чтобы включить аппаратные токены OATH в Центре администрирования Microsoft Entra, выполните следующие действия.

Войдите в Центр администрирования Microsoft Entra как минимум с правами Администратора политик аутентификации.
Перейдите к Защита>методы аутентификации>Аппаратные OATH токены (Предварительная версия).
Выберите Включить, выберите группы пользователей, которые нужно включить в политику, и выберите Сохранить.

Мы рекомендуем перейти на политику методов аутентификации для управления аппаратными токенами OATH. Если вы включите токены OATH в устаревшей политике MFA, перейдите к политике в Центре администрирования Microsoft Entra в качестве администратора политики проверки подлинности: Защита>Многофакторная проверка подлинности>Дополнительные параметры облачной многофакторной проверки подлинности. Снимите флажок для кода проверки из мобильного приложения или аппаратного токена.

Сценарий: администратор создает, назначает и активирует аппаратный токен OATH

В этом сценарии описывается создание, назначение и активация аппаратного токена OATH в качестве администратора, включая необходимые вызовы API и шаги проверки. Дополнительные сведения о разрешениях, необходимых для вызова этих API и проверки примеров запроса-ответа, см. в документации по API Microsoft Graph для операции Create OathTokenAuthenticationMethodDevice.

Примечание.

Для распространения политики может потребоваться до 20-минутной задержки. Оставьте час для обновления политики, прежде чем пользователи смогут войти с помощью своего аппаратного токена OATH и увидеть его в разделе Информация о безопасности.

Рассмотрим пример, в котором администратор политики проверки подлинности создает маркер и назначает его пользователю. Можно разрешить назначение без активации.

Для тела POST-запроса в этом примере можно найти серийный номер вашего устройства, а секретный ключ доставляется вам.

POST https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices
{ 
"serialNumber": "GALT11420104", 
"manufacturer": "Thales", 
"model": "OTP 110 Token", 
"secretKey": "C2dE3fH4iJ5kL6mN7oP1qR2sT3uV4w", 
"timeIntervalInSeconds": 30, 
"assignTo": {"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}
}

Ответ включает идентификатор токена id и идентификатор пользователя id, которому назначен токен:

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#directory/authenticationMethodDevices/hardwareOathDevices/$entity",
    "id": "3dee0e53-f50f-43ef-85c0-b44689f2d66d",
    "displayName": null,
    "serialNumber": "GALT11420104",
    "manufacturer": "Thales",
    "model": "OTP 110 Token",
    "secretKey": null,
    "timeIntervalInSeconds": 30,
    "status": "available",
    "lastUsedDateTime": null,
    "hashFunction": "hmacsha1",
    "assignedTo": {
        "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "displayName": "Test User"
    }
}

Вот как администратор политики проверки подлинности может активировать маркер. Замените код проверки в тексте запроса кодом из аппаратного токена OATH.

POST https://graph.microsoft.com/beta/users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee/authentication/hardwareOathMethods/3dee0e53-f50f-43ef-85c0-b44689f2d66d/activate

{ 
    "verificationCode" : "903809" 
}

Чтобы проверить, активирован ли токен, войдите в Информация о безопасности как тестовый пользователь. Если вам будет предложено утвердить запрос на вход из Microsoft Authenticator, выберите "Использовать код проверки".

Вы можете получить список токенов.

GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices

В этом примере создается один маркер:

POST https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices

В тексте запроса добавьте:

{ 
"serialNumber": "GALT11420104", 
"manufacturer": "Thales", 
"model": "OTP 110 Token", 
"secretKey": "abcdef2234567abcdef2234567", 
"timeIntervalInSeconds": 30, 
"hashFunction": "hmacsha1" 
}

Ответ содержит идентификатор токена.

#### Response
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#directory/authenticationMethodDevices/hardwareOathDevices/$entity",
    "id": "3dee0e53-f50f-43ef-85c0-b44689f2d66d",
    "displayName": null,
    "serialNumber": "GALT11420104",
    "manufacturer": "Thales",
    "model": "OTP 110 Token",
    "secretKey": null,
    "timeIntervalInSeconds": 30,
    "status": "available",
    "lastUsedDateTime": null,
    "hashFunction": "hmacsha1",
    "assignedTo": null
}

Администраторы политики аутентификации или конечный пользователь могут отменить назначение токена:

DELETE https://graph.microsoft.com/beta/users/66aa66aa-bb77-cc88-dd99-00ee00ee00ee/authentication/hardwareoathmethods/6c0272a7-8a5e-490c-bc45-9fe7a42fc4e0

В этом примере показано, как удалить маркер с идентификатором маркера 3dee0e53-f50f-43ef-85c0-b44689f2d66d:

DELETE https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices/3dee0e53-f50f-43ef-85c0-b44689f2d66d

Сценарий. Администратор создает и назначает аппаратный токен OATH, активируемый пользователем

В этом сценарии администратор политики проверки подлинности создает и назначает маркер, а затем пользователь может активировать его на странице сведений о безопасности или с помощью Microsoft Graph Explorer. При назначении токена вы можете предоставить пользователю инструкции по входу в сведения о безопасности для активации их токена. Они могут выбрать Добавить метод входа>Аппаратный токен. Они должны предоставить серийный номер аппаратного маркера, который обычно находится на задней части устройства.

POST https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices
{ 
"serialNumber": "GALT11420104", 
"manufacturer": "Thales", 
"model": "OTP 110 Token", 
"secretKey": "C2dE3fH4iJ5kL6mN7oP1qR2sT3uV4w", 
"timeIntervalInSeconds": 30, 
"assignTo": {"id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}
}

Ответ содержит значение идентификатора для каждого маркера. Администратор проверки подлинности может назначить маркер пользователю:

POST https://graph.microsoft.com/beta/users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee/authentication/hardwareOathMethods
{
    "device": 
    {
        "id": "6c0272a7-8a5e-490c-bc45-9fe7a42fc4e0" 
    }
}

Ниже приведены шаги, которые пользователь может выполнить для самостоятельной активации токена OATH оборудования в сведениях о безопасности:

Войдите в сведения о безопасности.
Выберите Добавить метод входа и выберите токен оборудования.
После выбора маркера оборудования нажмите Добавить.
Проверьте серийный номер на задней части устройства, введите его и нажмите Далее.
Создайте удобное имя, чтобы выбрать этот метод для выполнения многофакторной аутентификации, и выберите Далее.
Укажите код случайной проверки, который отображается при нажатии кнопки на устройстве. Для маркера, обновляющего код каждые 30 секунд, необходимо ввести код и выбрать Далее в течение одной минуты. Для маркера, который обновляется каждые 60 секунд, у вас есть две минуты.
После успешного добавления аппаратного токена OATH выберите Готово.
Аппаратный токен OATH отображается в списке доступных методов проверки подлинности.

Ниже приведены шаги, которые пользователи могут выполнить для самостоятельной активации токена OATH с помощью Graph Explorer.

Откройте Microsoft Graph Explorer, войдите и предоставите согласие на необходимые разрешения.
Убедитесь, что необходимые разрешения доступны. Для того чтобы пользователь мог выполнять операции с API самообслуживания, согласие администратора требуется для Directory.Read.All, User.Read.Allи User.ReadWrite.All.
Получите список OATH-токенов, привязанных к вашему аккаунту, но еще не активированы.
```
GET https://graph.microsoft.com/beta/me/authentication/hardwareOathMethods
```
Скопируйте идентификатор устройства токена и добавьте его в конец URL-адреса, за которым следует /activate. Необходимо ввести код проверки в тексте запроса и отправить вызов POST перед изменением кода.
```
POST https://graph.microsoft.com/beta/me/authentication/hardwareOathMethods/b65fd538-b75e-4c88-bd08-682c9ce98eca/activate
```
Текст запроса:
```
{
   "verificationCode": "988659"
}
```

Сценарий. Администратор создает несколько аппаратных токенов OATH в массовом режиме, которые пользователи самостоятельно назначают и активируют

В этом сценарии администратор проверки подлинности создает маркеры без назначения, а пользователи самостоятельно назначают и активируют маркеры. Вы можете загружать новые токены в тенант оптом. Пользователи могут войти на Сведения о безопасности для активации токена. Они могут выбрать Add sign-in method>Hardware token. Они должны предоставить серийный номер аппаратного маркера, который обычно находится на задней части устройства.

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

PATCH https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices
{
"@context":"#$delta", 
"value": [ 
    { 
        "@contentId": "1", 
        "serialNumber": "GALT11420108", 
        "manufacturer": "Thales", 
        "model": "OTP 110 Token", 
        "secretKey": "abcdef2234567abcdef2234567", 
        "timeIntervalInSeconds": 30, 
        "hashFunction": "hmacsha1" 
        },
    { 
        "@contentId": "2", 
        "serialNumber": "GALT11420112", 
        "manufacturer": "Thales", 
        "model": "OTP 110 Token", 
        "secretKey": "2234567abcdef2234567abcdef", 
        "timeIntervalInSeconds": 30, 
        "hashFunction": "hmacsha1" 
        }
    ]          
}

Устранение неполадок аппаратного токена OATH

В этом разделе рассматриваются общие сведения

У пользователя есть два маркера с одинаковым серийным номером

У пользователя может быть два экземпляра одного и того же аппаратного токена OATH, зарегистрированного в качестве методов проверки подлинности. Это происходит, если устаревший токен не удаляется из токенов OATH (предварительная версия) в Microsoft Entra Центре администрирования после загрузки с помощью Microsoft Graph.

В этом случае оба экземпляра токена перечислены в качестве зарегистрированных для пользователя.

GET https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods

Оба экземпляра токена также указаны в токенах OATH (предварительный просмотр) в Центре администрирования Microsoft Entra:

Снимок экрана с повторяющимися токенами в Центре администрирования Microsoft Entra.

Определение и удаление устаревшего токена.

Перечислите все аппаратные токены OATH у пользователя.
```
GET https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods
```
Найдите идентификатор обоих токенов и скопируйте серийный номер дубликата токена.
Определите устаревший маркер. В ответе следующей команды возвращается только один токен. Этот маркер был создан с помощью Microsoft Graph.
```
GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices?$filter=serialNumber eq '20033752'
```
Удалите у пользователя устаревшее назначение токена. Теперь, когда вы знаете идентификатор нового маркера, вы можете определить идентификатор устаревшего маркера из списка, возвращенного на шаге 1. Создайте URL-адрес с использованием устаревшего токена id.
```
DELETE https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods/{legacyHardwareOathMethodId}
```
Удалите устаревший маркер с помощью идентификатора устаревшего маркера в этом вызове.
```
DELETE https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices/{legacyHardwareOathMethodId}
```

Дополнительные сведения о токенах OATH.

Поделиться через

Управление аппаратными токенами OATH в идентификаторе Microsoft Entra (предварительная версия)

Включение аппаратных токенов OATH в политике методов проверки подлинности

Сценарий: администратор создает, назначает и активирует аппаратный токен OATH

Сценарий. Администратор создает и назначает аппаратный токен OATH, активируемый пользователем

Сценарий. Администратор создает несколько аппаратных токенов OATH в массовом режиме, которые пользователи самостоятельно назначают и активируют

Устранение неполадок аппаратного токена OATH

У пользователя есть два маркера с одинаковым серийным номером

Обратная связь

Дополнительные ресурсы

Поделиться через

Управление аппаратными токенами OATH в идентификаторе Microsoft Entra (предварительная версия)

Включение аппаратных токенов OATH в политике методов проверки подлинности

Сценарий: администратор создает, назначает и активирует аппаратный токен OATH

Сценарий. Администратор создает и назначает аппаратный токен OATH, активируемый пользователем

Сценарий. Администратор создает несколько аппаратных токенов OATH в массовом режиме, которые пользователи самостоятельно назначают и активируют

Устранение неполадок аппаратного токена OATH

У пользователя есть два маркера с одинаковым серийным номером

Связанный контент

Обратная связь

Дополнительные ресурсы