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

项目
11/19/2024

本主题介绍了如何在 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 管理中心。
浏览到“保护”>“身份验证方法”>“硬件 OATH 令牌(预览版)”。
选择“启用”，选择要包含在策略中的用户组，然后单击“保存”。

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

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

此方案介绍了如何以管理员身份创建、分配和激活硬件 OATH 令牌，包括必要的 API 调用和验证步骤。

注意

策略传播最多可能会延迟 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

方案：管理员创建并分配用户激活的令牌

在此方案中，身份验证策略管理员创建并分配令牌，然后用户可以在其“安全信息”页上或使用 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"
}
```

方案：管理员创建用户自行分配和激活的令牌

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

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

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

故障排除

用户有两个具有相同 SerialNumber 的令牌

用户可能有注册为身份验证方法的同一硬件 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 令牌。

通过

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

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

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

方案：管理员创建并分配用户激活的令牌

方案：管理员创建用户自行分配和激活的令牌

故障排除

用户有两个具有相同 SerialNumber 的令牌

反馈

其他资源

通过

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

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

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

方案：管理员创建并分配用户激活的令牌

方案：管理员创建用户自行分配和激活的令牌

故障排除

用户有两个具有相同 SerialNumber 的令牌

相关内容

反馈

其他资源