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

發行項
12/11/2024

本主題涵蓋如何在 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 呼叫和驗證步驟。

注意

原則傳播可能會延遲 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 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

案例：系統管理員建立並指派用戶啟動的 hardare 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
```
尋找令牌的標識碼，並複製重複令牌的 serialNumber。

識別舊版令牌。下列命令的回應中只會傳回一個令牌。該令牌是使用 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 令牌。

共用方式為

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

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

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

案例：系統管理員建立並指派用戶啟動的 hardare OATH 令牌

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

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

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

意見反應

其他資源

共用方式為

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

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

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

案例：系統管理員建立並指派用戶啟動的 hardare OATH 令牌

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

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

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

相關內容

意見反應

其他資源

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