如何在 Microsoft Entra ID 中管理硬件 OATH 令牌（预览版）

2025-04-30

本主题介绍了如何在 Microsoft Entra ID 中管理硬件 OATH 令牌，包括可用于上传、激活和分配硬件 OATH 令牌的 Microsoft Graph API。

在身份验证方法策略中启用硬件 OATH 令牌

可以使用 Microsoft Graph API 或 Microsoft Entra 管理中心在身份验证方法策略中查看和启用硬件 OATH 令牌。

若要使用 API 查看硬件 OATH 令牌策略状态，请执行以下操作：

GET https://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/hardwareOath

若要使用 API 启用硬件 OATH 令牌策略，请执行以下操作：

PATCH https://graph.microsoft.com/beta/policies/authenticationMethodsPolicy/authenticationMethodConfigurations/hardwareOath

在请求正文中，添加：

{
  "state": "enabled"
}

若要在 Microsoft Entra 管理中心启用硬件 OATH 令牌，请执行以下操作：

以至少身份验证策略管理员身份登录到 Microsoft Entra 管理中心。
浏览到 Entra ID>身份验证方法>硬件 OATH 令牌（预览版）。
选择“ 启用”，选择要包含在策略中的用户组，然后选择“ 保存”。

建议迁移到身份验证方法策略来管理硬件 OATH 令牌。如果在旧 MFA 策略中启用 OATH 令牌，请以身份验证策略管理员身份浏览到 Microsoft Entra 管理中心中的策略：Entra ID>多重身份验证>设置。清除“移动应用或硬件令牌提供的验证码”旁边的复选框。

方案：管理员创建、分配和激活硬件 OATH 令牌

此方案介绍了如何以管理员身份创建、分配和激活硬件 OATH 令牌，包括必要的 API 调用和验证步骤。有关调用这些 API 和检查请求响应示例所需的权限的详细信息，请参阅 Create hardwareOathTokenAuthenticationMethodDevice。

注意

策略传播最多可能会延迟 20 分钟。允许策略更新一小时，然后用户才能使用其硬件 OATH 令牌登录，并在其安全信息中查看它。

让我们看看身份验证策略管理员创建令牌并将其分配给用户的示例。无需激活即可允许分配。

对于本示例中 POST 的正文，可以从设备上找到 serialNumber，secretKey 会传送给你。

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 列出令牌：

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" 
}

响应包含令牌 ID。

#### 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

此示例演示了如何删除令牌 ID 为 3dee0e53-f50f-43ef-85c0-b44689f2d66d 的令牌：

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

方案：管理员创建并分配以供用户激活的硬件 OATH 令牌

在此方案中，身份验证策略管理员创建并分配令牌，然后用户可以在其“安全信息”页上或使用 Microsoft Graph 资源管理器激活令牌。分配令牌时，可以共享用户登录安全信息以激活其令牌的步骤。他们可以选择“添加登录方法“硬件令牌”。> 他们需要提供硬件令牌序列号，该序列号通常位于设备背面。

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 值。身份验证管理员可以将令牌分配给用户：

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 令牌将显示在可用身份验证方法列表中。

下面是用户使用 Graph 浏览器自行激活其硬件 OATH 令牌的步骤：

打开 Microsoft Graph 浏览器，登录，并同意所需的权限。
请确保具有所需的权限。要使用户能够执行自助 API 操作，需要管理员同意 Directory.Read.All、User.Read.All 和 User.ReadWrite.All。

获取分配给帐户但尚未激活的硬件 OATH 令牌列表。

GET https://graph.microsoft.com/beta/me/authentication/hardwareOathMethods

复制令牌设备的 ID，并将其添加到 URL 末尾，后跟 /activate。需要在请求正文中输入验证码，并在验证码发生更改之前提交 POST 调用。
```
POST https://graph.microsoft.com/beta/me/authentication/hardwareOathMethods/b65fd538-b75e-4c88-bd08-682c9ce98eca/activate
```
请求正文：
```
{
   "verificationCode": "988659"
}
```

方案：管理员批量创建多个硬件 OATH 令牌，以便用户自行分配和激活

在此方案中，身份验证管理员创建令牌而不进行分配，用户自行分配并激活令牌。可以将新令牌批量上传到租户。用户可以登录到安全信息以激活其令牌。他们可以选择“添加登录方法“硬件令牌”。> 他们需要提供硬件令牌序列号，该序列号通常位于设备背面。

为了进一步保证令牌仅由特定用户激活，可以将令牌分配给用户，并将设备寄给他们进行自我激活。

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 令牌的两个实例。如果旧令牌在使用 Microsoft Graph 上传后，未从 Microsoft Entra 管理中心的“OATH 令牌(预览版)”中移除，则会发生这种情况。

发生这种情况时，令牌的两个实例都会列为已为用户注册：

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

令牌的两个实例也会列在 Microsoft Entra 管理中心的“OATH 令牌(预览版)”中：

Microsoft Entra 管理中心中重复令牌的屏幕截图。

若要识别和移除旧令牌，请执行以下操作：

列出用户上的所有硬件 OATH 令牌。
```
GET https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods
```
找到两个令牌的 ID，然后复制重复令牌的 serialNumber。

识别旧令牌。以下命令的响应中仅返回一个令牌。该令牌是使用 Microsoft Graph 创建的。

GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices?$filter=serialNumber eq '20033752'

移除用户的旧令牌分配。知道新令牌 ID 后，可以从步骤 1 中返回的列表中识别旧令牌 ID。使用旧令牌 ID 创建 URL。
```
DELETE https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods/{legacyHardwareOathMethodId}
```

使用此调用中的旧令牌 ID 删除旧令牌。

DELETE https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices/{legacyHardwareOathMethodId}

详细了解 OATH 令牌。了解如何创建一个或多个 hardwareOathTokenAuthenticationMethodDevices。

通过