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

Статья
01/07/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 в устаревшей политике MFA, перейдите к политике в Центре администрирования Microsoft Entra в качестве администратора политики проверки подлинности: >Дополнительные параметры многофакторной проверки подлинности на основе облака. Снимите флажок для кода проверки из мобильного приложения или маркера оборудования.

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

В этом сценарии описывается создание, назначение и активация аппаратного токена OATH в качестве администратора, включая необходимые вызовы API и шаги проверки.

Примечание.

Для распространения политики может потребоваться до 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"}
}

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

{
    "@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. При назначении маркера вы можете предоставить пользователю общий доступ к сведениям о безопасности для активации маркера. Они могут выбрать маркер "Add sign-in method>Hardware" (Добавление маркера оборудования для входа). Они должны предоставить серийный номер аппаратного маркера, который обычно находится на задней части устройства.

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" (Добавление маркера оборудования для входа). Они должны предоставить серийный номер аппаратного маркера, который обычно находится на задней части устройства.

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

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-адрес с помощью устаревшего идентификатора маркера.
```
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

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

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

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

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