如何在 Microsoft Entra ID 中管理硬體 OATH 令牌（預覽）

發行項
03/12/2025

本主題涵蓋如何在 Microsoft Entra 識別符中管理硬體 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 呼叫和驗證步驟。如需叫用這些 API 和檢查要求回應範例所需許可權的詳細資訊，請參閱 Create hardwareOathTokenAuthenticationMethodDevice 作業的 Microsoft Graph 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"}
}

回應包含令牌識別碼，以及指派令牌的使用者識別碼：

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

回應包含令牌識別碼。

#### 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 令牌會出現在您可用的驗證方法清單中。

以下是使用者可以使用 Graph 瀏覽器自行啟用其硬體 OATH 驗證器的步驟。

開啟 Microsoft Graph 工具，登入及授予必要的權限。
請確定您具有必要的許可權。若要讓用戶能夠執行自助 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 令牌，讓使用者自行指派並啟用

在此案例中，驗證系統管理員會建立令牌而不指派，以及使用者自行指派並啟用令牌。您可以將新的令牌大量上傳至租戶。用戶可以登入安全性資訊以啟用其令牌。他們可以選擇 新增登入方法>硬體令牌。他們需要提供硬體令牌序號，這通常是在裝置背面。

為了進一步保證令牌只會由特定用戶啟用，您可以將令牌指派給使用者，並將裝置傳送給使用者以進行自我啟用。

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
```
尋找兩個令牌的標識碼，並複製重複令牌的序列號。

識別舊版令牌。下列命令的回應中只會傳回一個令牌。該令牌是使用 Microsoft Graph 建立的。

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

從使用者移除舊版令牌指派。既然您已知道 新令牌的標識碼 ，您可以從步驟 1 中傳回的清單識別 舊版令牌的標識碼 。使用舊版令牌 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 令牌

情境：系統管理員建立並指派硬體 OATH 令牌，讓用戶啟用

案例：系統管理員會大量建立多個硬體 OATH 令牌，讓使用者自行指派並啟用

針對硬體 OATH 令牌的問題進行故障排除

使用者有兩個具有相同序號的令牌

意見反應

其他資源

共用方式為

如何在 Microsoft Entra ID 中管理硬體 OATH 令牌 （預覽）

在驗證方法原則中啟用硬體 OATH 令牌

案例：系統管理員建立、指派和啟用硬體 OATH 令牌

情境：系統管理員建立並指派硬體 OATH 令牌，讓用戶啟用

案例：系統管理員會大量建立多個硬體 OATH 令牌，讓使用者自行指派並啟用

針對硬體 OATH 令牌的問題進行故障排除

使用者有兩個具有相同序號的令牌

相關內容

意見反應

其他資源

如何在 Microsoft Entra ID 中管理硬體 OATH 令牌（預覽）