本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在使用者集區中使用使用者裝置
當您使用 Amazon Cognito 使用者集區 API 登入本機使用者集區使用者時，您可以將使用者來自[威脅防護](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pool-settings-threat-protection.html)的活動日誌與其每個裝置建立關聯，並選擇性地允許您的使用者在信任的裝置上略過多重要素驗證 (MFA)。Amazon Cognito 會針對任何尚未包含裝置資訊的登入，在回應中包含裝置金鑰。裝置金鑰的格式為 `Region_UUID`。使用裝置金鑰、Secure Remote Password (SRP) 程式庫，以及允許裝置身分驗證的使用者集區，您就可以在應用程式中提示使用者信任目前的裝置，並且不再於登入時提示輸入 MFA 代碼。
**Topics**
+ [設定記住的裝置](#amazon-cognito-user-pools-setting-up-remembered-devices)
+ [取得裝置金鑰](#user-pools-remembered-devices-getting-a-device-key)
+ [使用裝置登入](#user-pools-remembered-devices-signing-in-with-a-device)
+ [檢視、更新和忘記裝置](#user-pools-remembered-devices-viewing-updating-forgetting)
## 設定記住的裝置
使用 Amazon Cognito 使用者集區，您就可以將使用者的每一部裝置與唯一裝置識別碼 (也就是裝置金鑰) 建立關聯。當您在登入時出示裝置金鑰並執行裝置身分驗證時，您可以使用*信任的裝置*身分驗證流程來設定應用程式。在此流程中，您的應用程式可以向使用者提供在沒有 MFA 的情況下登入的選擇，直到稍後為止，取決於應用程式的安全需求或使用者的偏好設定。在該期間結束時，您的應用程式必須將裝置狀態變更為*不記住*，且使用者必須使用 MFA 登入，直到確認他們想要記住裝置為止。例如，您的應用程式可能會提示您的使用者信任裝置 30、60 或 90 天。您可以將此日期存放在自訂屬性中，並在該日期變更其裝置的記住狀態。然後，您必須重新提示使用者提交 MFA 代碼，並將裝置設定為在身分驗證成功後再次記住。
1. 記住的裝置只能在 MFA 處於作用中狀態的使用者集區中覆寫 MFA。
當您的使用者使用記住的裝置登入時，您必須在其身分驗證流程中執行額外的裝置身分驗證。如需詳細資訊，請參閱[使用裝置登入](#user-pools-remembered-devices-signing-in-with-a-device)。
在裝置追蹤下，設定您的使用者集區以記住使用者集區的**登入**選單中的裝置。 ****透過 Amazon Cognito 主控台來設定記住的裝置功能時，您有三個選項：**Always (一律)**、**User Opt-In (使用者選擇記住)** 和 **No (否)**。
**不要記住**
您的使用者集區不會在登入時提示使用者記住裝置。
**永遠記住**
當您的應用程式確認使用者的裝置時，您的使用者集區會一律記住該裝置，而且後續裝置成功登入時，不會傳回 MFA 挑戰。
**使用者選擇加入**
當您的應用程式確認使用者的裝置時，您的使用者集區不會自動抑制 MFA 挑戰。您必須提示使用者選擇是否要記住裝置。
若您選擇**永遠記住**或**使用者選擇加入**，每次使用者從無法辨識的裝置登入時，Amazon Cognito 都會產生裝置識別碼金鑰和秘密。裝置金鑰是使用者執行裝置身分驗證時，您的應用程式傳送至使用者集區的初始識別碼。
無論使用者裝置是自動記住或選擇加入，一經確認後，您就可以使用裝置識別碼金鑰和秘密在每次使用者登入時進行裝置身分驗證。
您也可以在[CreateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_CreateUserPool.html) 或 [UpdateUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html) API 請求中，為使用者集區設定記住的裝置設定。如需詳細資訊，請參閱 [DeviceConfiguration](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateUserPool.html#CognitoUserPools-UpdateUserPool-request-DeviceConfiguration) 屬性。
Amazon Cognito 使用者集區 API 有其他可針對記住的裝置進行的操作。
1. [ListDevices](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListDevices.html) 和 [AdminListDevices](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminListDevices.html) 會傳回使用者的裝置金鑰及其中繼資料清單。
1. [GetDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetDevice.html) 和 [AdminGetDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminGetDevice.html) 會傳回單一裝置的裝置金鑰和中繼資料。
1. [UpdateDeviceStatus](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateDeviceStatus.html) 和 [AdminUpdateDeviceStatus](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateDeviceStatus.html) 會將使用者裝置設定為記住或不記住。
1. [ForgetDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgetDevice.html) 和 [AdminForgetDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminForgetDevice.html) 會從設定檔中移除使用者已確認的裝置。
名稱開頭為 `Admin` 的 API 操作可用於伺服器端應用程式，且必須透過 IAM 憑證授權。如需詳細資訊，請參閱[了解 API、OIDC 和受管登入頁面身分驗證](authentication-flows-public-server-side.md#user-pools-API-operations)。
## 取得裝置金鑰
只要您的使用者透過使用者集區 API 登入，且未在身分驗證參數中包含裝置金鑰作為 `DEVICE_KEY`，Amazon Cognito 就會在回應中傳回新的裝置金鑰。在您的公有用戶端應用程式中，將裝置金鑰放入應用程式儲存中，您就可以在後續請求中包含該金鑰。在機密伺服器端應用程式中，使用您使用者的裝置金鑰設定瀏覽器 Cookie 或其他用戶端權杖。
您的應用程式必須先確認裝置金鑰並提供其他資訊，您的使用者才能使用其受信任的裝置登入。對 Amazon Cognito 產生 [ConfirmDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmDevice.html) 請求，以透過裝置金鑰、易記名稱、密碼驗證程式和 salt 來確認使用者裝置。如果您設定使用者集區進行選擇加入裝置身分驗證，Amazon Cognito 會回應您的 `ConfirmDevice` 請求，並提示您的使用者必須選擇是否要記住目前的裝置。在 [UpdateDeviceStatus](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateDeviceStatus.html) 請求中以使用者的選擇回應。
若您確認使用者的裝置，但未將其設定為記住，Amazon Cognito 會儲存關聯，但是在您提供裝置金鑰時，會進行非裝置登入。裝置可以產生日誌，對於使用者安全和疑難排解來說很實用。已確認但未記住的裝置不會利用登入功能，而是利用安全監控日誌功能。當您為應用程式用戶端啟用威脅防護並將裝置指紋編碼為請求時，Amazon Cognito 會將使用者事件與已確認的裝置建立關聯。
**取得新的裝置金鑰**
1. 透過 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API 請求啟動使用者登入工作階段。
1. 使用 [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) 回應所有身分驗證挑戰，直到收到將您的使用者登入工作階段標記為完成的 JSON Web 權杖 (UWT) 為止。
1. 在您的應用程式中，記錄 Amazon Cognito 在其 `RespondToAuthChallenge` 或 `InitiateAuth` 回應中的 `NewDeviceMetadata` 傳回的值：`DeviceGroupKey` 和 `DeviceKey`。
1. 為您的使用者產生新的 SRP 秘密：salt 和密碼驗證程式。此功能可在提供 SRP 程式庫的 SDK 中使用。
1. 提示您的使用者輸入裝置名稱，或根據使用者裝置的特性產生名稱。
1. 在 [ConfirmDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmDevice.html) API 請求中，提供使用者的存取權仗、裝置金鑰、裝置名稱及 SRP 秘密。如果您的使用者集區設定為**永遠記住**裝置，表示您的使用者註冊已完成。
1. 如果 Amazon Cognito 以 `"UserConfirmationNecessary": true` 回應 `ConfirmDevice`，請提示您的使用者選擇是否要記住裝置。如果使用者確認要記住裝置，請利用使用者的存取權杖、裝置金鑰及 `"DeviceRememberedStatus": "remembered"` 產生 [UpdateDeviceStatus](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_UpdateDeviceStatus.html) API 請求。
1. 如果您已指示 Amazon Cognito 記住裝置，則會在使用者下一次登入時，對其顯示 `DEVICE_SRP_AUTH` 挑戰，而不是 MFA 挑戰。
## 使用裝置登入
設定要記住的使用者裝置後，當使用者使用相同的裝置金鑰登入時，Amazon Cognito 就不會再要求他們提交 MFA 代碼。裝置身分驗證只會將 MFA 身分驗證挑戰取代為裝置身分驗證挑戰。您無法只使用裝置身分驗證讓使用者登入。您的使用者必須先使用其密碼或自訂挑戰完成身分驗證。以下是使用者在記住的裝置上進行身分驗證的程序。
若要在使用[自訂身分驗證挑戰 Lambda 觸發條件](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-challenge.html)的流程中執行裝置身分驗證，請在 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API 請求中傳遞 `DEVICE_KEY` 參數。在使用者成功通過所有挑戰，且 `CUSTOM_CHALLENGE` 挑戰傳回的 `issueTokens` 值 `true` 之後，Amazon Cognito 就會傳回最後一項 `DEVICE_SRP_AUTH` 挑戰。
**使用裝置登入**
1. 從用戶端儲存擷取使用者的裝置金鑰。
1. 透過 [InitiateAuth](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html) API 請求啟動使用者登入工作階段。選擇 `USER_SRP_AUTH`、`REFRESH_TOKEN_AUTH`、`USER_PASSWORD_AUTH` 或 `CUSTOM_AUTH` 的 `AuthFlow`。在 `AuthParameters` 中，將使用者的裝置金鑰新增至 `DEVICE_KEY` 參數，並包含所選登入流程的其他必要參數。
1. 您也可以在 `PASSWORD_VERIFIER` 回應的參數中，將 `DEVICE_KEY` 傳遞至身分驗證挑戰。
1. 完成挑戰回應，直到您在回應中收到 `DEVICE_SRP_AUTH` 挑戰為止。
1. 在 [RespondToAuthChallenge](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_RespondToAuthChallenge.html) API 請求中，傳送 `DEVICE_SRP_AUTH` 的 `ChallengeName`，以及 `USERNAME`、`DEVICE_KEY` 和 `SRP_A` 的參數。
1. Amazon Cognito 會以 `DEVICE_PASSWORD_VERIFIER` 挑戰回應。此挑戰回應包括 `SECRET_BLOCK` 和 `SRP_B` 的值。
1. 使用 SRP 程式庫產生並提交 `PASSWORD_CLAIM_SIGNATURE`、`PASSWORD_CLAIM_SECRET_BLOCK`、`TIMESTAMP`、`USERNAME` 和 `DEVICE_KEY` 參數。在另一個 `RespondToAuthChallenge` 請求中提交這些參數。
1. 完成其他挑戰，直到您收到使用者的 JWT 為止。
下列虛擬程式碼示範如何計算 `DEVICE_PASSWORD_VERIFIER` 挑戰回應的值。對於使用裝置的 SRP 身分驗證，請為您的使用者產生*新的* SRP 秘密：新的高熵密碼 `DeviceSecret`、 salt 和相關聯的密碼驗證器。這些值與用於使用者 SRP 身分驗證的密碼、 salt 和驗證器不同。它們僅用於裝置身分驗證，並且只會存放在裝置上。為使用者裝置產生 SRP 秘密的函數可在各種 SDKs 提供的 [SRP 程式庫](https://github.com/secure-remote-password/implementations)中使用。
```
PASSWORD_CLAIM_SECRET_BLOCK = SECRET_BLOCK
TIMESTAMP = "Tue May 7 00:09:40 UTC 2025"
k = SHA256(N || g) as a non-negative integer in big-endian
u = SHA256(SRP_A || SRP_B) as a non-negative integer in big-endian
x = SHA256(salt || SHA256(DeviceGroupKey || DeviceKey || ":" || DeviceSecret)) as a non-negative integer in big-endian
S_USER = (SRP_B - k * g^x)^(a + u * x) % N
K_USER = HKDF_HMAC_SHA256(salt=u, ikm=S_USER, info="Caldera Derived Key", length=16 bytes)
PASSWORD_CLAIM_SIGNATURE = Base64(HMAC_SHA256(key=K_USER, message=(DeviceGroupKey || DeviceKey || PASSWORD_CLAIM_SECRET_BLOCK || TIMESTAMP)))
```
## 檢視、更新和忘記裝置
您可以使用 Amazon Cognito API 在應用程式中實作下列功能。
1. 顯示有關使用者目前裝置的資訊。
1. 顯示使用者所有裝置的清單。
1. 忘記裝置。
1. 更新裝置的記住狀態。
下列說明中授權給 API 請求的存取權杖必須包含 `aws.cognito.signin.user.admin` 範圍。Amazon Cognito 會將此範圍的宣告新增至您使用 Amazon Cognito 使用者集區 API 產生的所有存取權杖。第三方 IdP 必須針對向 Amazon Cognito 進行身分驗證的使用者，分別管理裝置和 MFA。在受管登入中，您可以請求`aws.cognito.signin.user.admin`範圍，但受管登入會自動將裝置資訊新增至進階安全使用者日誌，而且不會提供記住裝置。
**顯示有關裝置的資訊**
您可以查詢有關使用者裝置的資訊，以判斷該裝置目前是否仍在使用中。例如，您可能希望在記住的裝置未登入長達 90 天後，將裝置停用。
+ 若要在公有用戶端應用程式中顯示使用者的裝置資訊，請在 [GetDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_GetDevice.html) API 請求中提交使用者的存取金鑰和裝置金鑰。
+ 若要在機密用戶端應用程式中顯示使用者的裝置資訊，請使用 AWS 登入資料簽署 [AdminGetDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminGetDevice.html) API 請求，然後提交使用者的使用者名稱、裝置金鑰和使用者集區。
**顯示使用者所有裝置的清單**
您可以顯示使用者所有裝置及其屬性的清單。例如，您可能希望驗證目前的裝置是否與記住的裝置相符。
+ 在公有用戶端應用程式中，於 [ListDevices](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ListDevices.html) API 請求中提交使用者的存取權仗。
+ 在機密用戶端應用程式中，使用 AWS 登入資料簽署 [AdminListDevices](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminListDevices.html) API 請求，並提交使用者的使用者名稱和使用者集區。
**忘記裝置**
您可以刪除使用者的裝置金鑰。當您判斷使用者不再使用某部裝置，或是偵測到異常活動並且想要提示使用者再次完成 MFA 時，就會希望這麼做。若稍後要再次註冊裝置，您必須產生並儲存新的裝置金鑰。
+ 在公有用戶端應用程式中，於 [ForgetDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ForgetDevice.html) API 請求中提交使用者的裝置金鑰和存取權仗。
+ 在機密用戶端應用程式中，於 [AdminForgetDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminForgetDevice.html) API 請求中提交使用者的裝置金鑰和存取權仗。