本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Amazon Cognito 故障診斷
<a name="troubleshooting"></a>

本章提供使用 Amazon Cognito 時可能遇到的常見問題的解決方案。Amazon Cognito 實作可能會在身分驗證流程、使用者集區組態和聯合身分設定之間面臨各種挑戰。無論您是開發新的應用程式還是維護現有的應用程式，此故障診斷指南都可協助您快速識別和解決常見問題。

## 自訂網域組態錯誤
<a name="troubleshoot_custom_domain_errors"></a>

在 Amazon Cognito 中設定自訂網域名稱時，您可能會收到錯誤訊息。常見的錯誤包括驗證問題、憑證問題或網域衝突。

### `Custom domain is not a valid subdomain`
<a name="troubleshoot_custom_domain_subdomain"></a>

此錯誤表示父網域的 DNS 解析有問題。Amazon Cognito 不支援頂層網域，並且需要父網域具有 DNS A 記錄以進行驗證。

**問題**  
此錯誤表示父網域的 DNS 解析有問題。Amazon Cognito 不支援頂層網域，並且需要父網域具有 DNS A 記錄以進行驗證。

**解決方案**  
+ **為父系網域建立 A 記錄：**您必須在自訂網域的父系網域的 DNS 組態中建立 A 記錄。
  + **範例：**如果您的自訂網域是 `auth.xyz.yourdomain.com`，則父網域是 `xyz.yourdomain.com`。如果您想要將 `xyz.yourdomain.com`設定為自訂網域，父系為 `yourdomain.com`。
  + 父網域必須解析為有效的 IP 地址。如果不指向實際 IP 地址，您可以使用虛擬 IP 地址，例如 `8.8.8.8`。
+ **驗證 DNS 傳播 （選用但建議）：**若要確保您的 DNS 提供者已傳播變更，您可以執行 `dig`命令。
  + 如果使用 `auth.xyz.yourdomain.com`做為自訂網域： `dig A xyz.yourdomain.com +short`
  + 如果使用 `xyz.yourdomain.com`做為自訂網域： `dig A yourdomain.com +short`
  + 命令應傳回您設定的 IP 地址。如果沒有，請等待變更完全傳播。
+ **移除父系網域 A 記錄：**在 Amazon Cognito 中成功建立自訂網域後，如果父系網域是虛擬網域，您可以移除為父系網域建立的記錄。

如需詳細資訊，請參閱[將您自己的網域用於託管 UI](cognito-user-pools-add-custom-domain.md)。

### `Domain already associated with another user pool`
<a name="troubleshoot_domain_already_associated"></a>

自訂網域名稱在所有 AWS 帳戶 和 區域中必須是唯一的。

**問題**  
自訂網域名稱在所有 AWS 帳戶 和 區域中必須是唯一的。

**解決方案**  
+ 若要使用新使用者集區的網域名稱，您必須從目前相關聯的使用者集區中刪除自訂網域。
+ **刪除後等待：**自訂網域需要一些時間才能從第一個使用者集區完全刪除。在刪除後立即建立具有相同名稱的新自訂網域仍可能導致此錯誤。請等待幾分鐘，然後再試一次。

### `One or more of the CNAMEs that you provided are already associated with a different resource`
<a name="troubleshoot_cname_already_associated"></a>

當您建立自訂網域時，Amazon Cognito 會建立 AWS受管的 Amazon CloudFront 分佈。網域名稱只能與一個 Amazon CloudFront 分佈搭配使用。如果網域名稱已在用作另一個 Amazon CloudFront 分佈的替代網域，則會發生此錯誤。

**問題**  
當您建立自訂網域時，Amazon Cognito 會建立 AWS受管的 Amazon CloudFront 分佈。網域名稱只能與一個 Amazon CloudFront 分佈搭配使用。如果網域名稱已在用作另一個 Amazon CloudFront 分佈的替代網域，則會發生此錯誤。

**解決方案**  
+ **選項 1：**為您的 Amazon Cognito 自訂網域使用不同的網域名稱。
+ **選項 2：**如果您使用 Amazon Cognito 的網域名稱，請勿將其與另一個 Amazon CloudFront 分佈搭配使用。

### `The specified SSL certificate doesn't exist`
<a name="troubleshoot_ssl_certificate_not_exist"></a>

Amazon Cognito 使用 Amazon CloudFront，無論使用者集區的區域為何 AWS 區域，都需要 AWS Certificate Manager (ACM) 憑證位於 `us-east-1`（維吉尼亞北部）。

**問題**  
Amazon Cognito 使用 Amazon CloudFront，無論使用者集區的區域為何 AWS 區域，都需要 AWS Certificate Manager (ACM) 憑證位於 `us-east-1`（維吉尼亞北部）。

**解決方案**  
+ **確保憑證區域：**確認 ACM 憑證位於 `us-east-1`區域。
+ **檢查憑證有效性：**確定選取的憑證未過期。
+ **匯入的憑證：**如果您將憑證匯入 ACM，請確保：
  + 它由公有憑證授權單位發行。
  + 它包含正確的憑證鏈。
+ **AWS KMS 政策檢查：**建立網域的 IAM 使用者或角色的 AWS Key Management Service (AWS KMS) 政策中的明確`deny`陳述式可能會導致此錯誤。具體而言，請檢查 `kms:DescribeKey`、 `kms:CreateGrant`或 `kms:*`動作是否有明確拒絕。

## `Invalid refresh token` 錯誤
<a name="troubleshoot_invalid_refresh_token"></a>

**問題**  
嘗試使用重新整理字符從 Amazon Cognito 使用者集區使用 `AdminInitiateAuth`或 `InitiateAuth` API 操作取得新的存取和 ID 字符時，您會收到`Invalid refresh token`錯誤。

**解決方案**  
根據您的使用者集區組態和 API 用量實作下列疑難排解步驟：  
+ **確保一致的應用程式用戶端 ID：**呼叫 `AdminInitiateAuth`或 `InitiateAuth` API 進行權杖重新整理時，您必須使用與產生重新整理權杖的初始身分驗證期間所使用的完全相同的應用程式用戶端 ID。
+ **確認裝置：**如果您已在使用者集區上啟用[裝置追蹤](amazon-cognito-user-pools-device-tracking.md)，但尚未確認使用者的裝置，您必須先呼叫 [ConfirmDevice](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_ConfirmDevice.html) API。使用者確認其裝置後，您可以交換重新整理字符。
+ 在**重新整理請求中包含裝置金鑰：**如果已啟用裝置追蹤，請在使用`REFRESH_TOKEN_AUTH`流程`AuthParameter`時將唯一裝置金鑰納入為 ：

  ```
  {
    "AuthFlow": "REFRESH_TOKEN_AUTH",
    "AuthParameters": {
      "REFRESH_TOKEN": "example_refresh_token",
      "SECRET_HASH": "example_secret_hash", // Required if your app client uses a client secret
      "DEVICE_KEY": "example_device_key" 
    }
  }
  ```
+ **`USER_SRP_AUTH` 用於裝置追蹤：**如果您使用裝置追蹤，初始身分驗證流程必須為 `USER_SRP_AUTH`。

如需詳細資訊，請參閱[在使用者集區中使用使用者裝置](amazon-cognito-user-pools-device-tracking.md)。

## 聯合中的無效 SAML 回應錯誤
<a name="troubleshoot_invalid_saml_response"></a>

嘗試使用 SAML 2.0 聯合到 Amazon Cognito 時，使用者會收到各種`Invalid SAML response`和類似的錯誤。這些錯誤可能是因為屬性映射問題、憑證問題或組態不相符而發生。

### `Invalid user attributes: Required attribute`
<a name="troubleshoot_saml_required_attribute"></a>

**問題**  
使用者缺少使用者集區中所需的屬性值，或 IdP 正在嘗試移除或更新不可變屬性。

**解決方案**  
+ 檢查您的使用者集區組態中定義的[必要屬性](user-pool-settings-attributes.md#how-to-edit-standard-attributes)。
+ 在瀏覽器中使用網路擷取工具，擷取 SAML 回應。您可能需要執行 URL 和 base64 解碼。確認屬性存在於 SAML 聲明中。
+ 登入您的身分提供者，並檢閱其傳送至 Amazon Cognito 的屬性。確認 IdP 已設定為使用正確的名稱傳送所需的屬性。
+ 對於不可變屬性，請執行下列 AWS CLI 命令來識別它們：`aws cognito-idp describe-user-pool --user-pool-id USER-POOL-ID --query 'UserPool.SchemaAttributes[?Mutable==`false`].Name'`。
+ 在 IdP 的 SAML 屬性映射中，刪除任何以不可變 Amazon Cognito 屬性為目標的映射。或者，將目的地屬性更新為不同的可變屬性。

### `Invalid SAML response received: SAML Response signature is invalid`
<a name="troubleshoot_saml_signature_invalid"></a>

**問題**  
您的 IdP 已更新其 SAML 簽署憑證，導致 SAML 回應中的憑證與存放在 Amazon Cognito 中的中繼資料檔案不相符。

**解決方案**  

1. 從您的 IdP 下載最新的中繼資料檔案。

1. 在 Amazon Cognito 主控台中，導覽至使用者集區的**社交和外部提供者**、編輯 SAML 供應商，並將現有的中繼資料檔案取代為新下載的檔案。

### `Audience restriction` 或 `Application with identifier not found`
<a name="troubleshoot_saml_audience_restriction"></a>

**問題**  
您的 IdP 中設定了不正確的實體 ID，否則宣告會使用另一個使用者的統一資源名稱 (URN)。

**解決方案**  

1. 從 主控台的**概觀**區段取得您的 Amazon Cognito 使用者集區 ID。

1. 在 IdP 的管理主控台中，更新使用者集區的 SAML 應用程式中的實體 ID。設定實體 ID 以符合格式 `urn:amazon:cognito:sp:USER_POOL_ID`。將 取代`USER_POOL_ID`為上一個步驟中的使用者集區 ID。

### `An error was encountered with the requested page`
<a name="troubleshoot_saml_acs_url"></a>

**問題**  
向 IdP 註冊的聲明消費者服務 (ACS) URL 設定不正確，或者 IdP 未使用必要的 POST 繫結傳送 SAML 回應。

**解決方案**  
+ 在 IdP 的管理主控台中，使用正確的 ACS URL 格式更新應用程式，確保它使用`HTTP POST`繫結。
+ **預設網域格式：** `https://cognito-idp.Region.amazonaws.com/your user pool ID/saml2/idpresponse`
+ **自訂網域格式：** `https://auth.example.com/saml2/idpresponse`

### `Invalid relayState from identity provider`
<a name="troubleshoot_saml_relay_state"></a>

**問題**  
`RelayState` 參數遺失或無效，或 IdP 和 Amazon Cognito 之間的 URL 不相符。

**解決方案**  
+ **對於[服務供應商啟動 (SP 啟動）](cognito-user-pools-SAML-session-initiation.md#cognito-user-pools-saml-idp-authentication) 流程：**一律在您的使用者集區`/oauth2/authorize`端點啟動身分驗證。不會從使用者初次造訪 Amazon Cognito 傳回`RelayState`參數的 SAML 聲明不是有效的 SP 起始請求。
+ **對於[身分提供者啟動 (IdP 啟動）](cognito-user-pools-SAML-session-initiation.md#cognito-user-pools-SAML-session-initiation-idp-initiation) 流程：**IdP 必須使用所需的格式，將具有 SAML 聲明的 `RelayState` 參數包含到`/saml2/idpresponse`端點：`redirect_uri=REDIRECT_URI&state=STATE`。

如需詳細資訊，請參閱[搭配使用者集區使用 SAML 身分提供者](cognito-user-pools-saml-idp.md)。

## 受管登入使用者無法選取 MFA 因素
<a name="troubleshoot_mfa_factor_selection"></a>

**問題**  
透過受管登入登入時，使用者無法選擇偏好的 MFA 方法，或者不會提示您使用預期的 MFA 方法。

**解決方案**  
Amazon Cognito 遵循特定邏輯，根據使用者集區設定、使用者屬性和帳戶復原組態，判斷哪些 MFA 因素可供使用者使用。例如，如果電子郵件設定為其主要帳戶復原方法，則使用者無法使用電子郵件 MFA。  
若要覆寫預設 MFA 因素選擇，您可以實作下列其中一種方法：  
+ 對於公有應用程式：使用 [SetUserMFAPreference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_SetUserMFAPreference.html) 搭配有效的存取字符，讓使用者設定自己的 MFA 偏好設定
+ 對於管理員管理的應用程式：使用 [AdminSetUserMFAPreference](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminSetUserMFAPreference.html) 搭配 AWS 登入資料來設定使用者 MFA 偏好設定
這兩種操作都可讓您為個別使用者啟用或停用 SMS、電子郵件和 TOTP MFA 方法，並將一種方法設為偏好。

如需詳細資訊，請參閱[將 MFA 新增到使用者集區](user-pool-settings-mfa.md)。

### 無密碼和通行金鑰使用者無法使用 MFA
<a name="troubleshoot_passwordless_mfa"></a>

**問題**  
使用一次性密碼 (OTP) 身分驗證方法登入的使用者無法新增或使用多重要素身分驗證。

**解決方案**  
OTP 登入流程不支援 MFA。不過，使用者驗證的通行密鑰身分驗證可以滿足 MFA 要求。在您的使用者集區`MULTI_FACTOR_WITH_USER_VERIFICATION`中`FactorConfiguration`將 設定為 `WebAuthnConfiguration` ，以允許通行金鑰計為多重要素驗證。

如需詳細資訊，請參閱[使用使用者集區進行身分驗證](getting-started-identity-pools-application.md#user-pool-authentication)。

## 無法透過電子郵件/簡訊接收密碼重設碼
<a name="troubleshoot_password_reset_delivery"></a>

**問題**  
在忘記密碼工作流程期間，使用者無法透過電子郵件或簡訊接收驗證碼。

**解決方案**  
可能無法接收驗證碼的原因有很多。請依照此檢查清單對問題進行疑難排解：  
+ 檢查使用者的電子郵件垃圾郵件和垃圾郵件資料夾。
+ 確認使用者存在於使用者集區中。
+ 確認使用者的狀態不是 `FORCE_CHANGE_PASSWORD`。如果是這種情況，使用者是由管理員建立，Amazon Cognito 會在他們使用臨時密碼登入時提示他們設定密碼。
+ 檢查使用者是否具有已驗證的電子郵件或電話號碼屬性。
+ 檢查您的帳戶的簡訊支出限制
+ 檢查您的 Amazon Simple Email Service (Amazon SES) 訊息傳送配額。
+ 檢查 SMS 和 Amazon SES （如果您的使用者集區設定為**使用 Amazon SES 傳送電子郵件**) 是否已移出沙盒。如果未從沙盒移出，則未經 Amazon SES 驗證或 AWS End User Messaging SMS 無法接收密碼重設代碼的電子郵件地址或電話號碼。
+ 如果使用者具有作用中的 MFA 因素，請檢查他們是否未嘗試產生相同因素的訊息。例如，電子郵件 MFA 作用中的使用者無法透過電子郵件傳送密碼重設代碼。

如需詳細資訊，請參閱[Amazon Cognito 使用者集區的電子郵件設定](user-pool-email.md)及[Amazon Cognito 使用者集區的簡訊設定](user-pool-sms-settings.md)。

## 密碼重設失敗，具有未驗證的復原屬性： `Could not reset password for the account, please contact support or try again`
<a name="troubleshoot_password_reset_unverified_recovery"></a>

**問題**  
由於未驗證的復原方法或 MFA 組態衝突，使用者嘗試重設密碼時會收到此錯誤。當使用者的電子郵件或電話號碼屬性未經驗證，或其 MFA 設定無法使用設定的復原方法時，就會發生錯誤。

**解決方案**  
檢閱使用者集區的帳戶復原組態和受影響的使用者的驗證狀態：  
+ **驗證復原設定：**在您的使用者集區中，導覽至**登入** > **使用者帳戶復原**。確保啟用**自助式服務帳戶復原**，並檢閱您的**復原訊息交付方法**設定。
+ **檢查使用者屬性驗證：**確認使用者具有符合您復原方法組態的已驗證電子郵件地址或電話號碼。在 主控台中，前往使用者的設定檔，選取**使用者屬性** > **編輯**，然後將適當的屬性標記為已驗證。
+ **解決 MFA 衝突：**偏好的 MFA 方法為電子郵件的使用者無法透過電子郵件接收密碼重設代碼，而具有 SMS MFA 的使用者無法透過 SMS 接收代碼。更新您的**復原訊息交付方法**，以提供替代選項，例如**簡訊，否則是電子郵件**或**電子郵件，否則是簡訊**。
+ **管理驗證：**使用 API 操作 [AdminUpdateUserAttributes](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_AdminUpdateUserAttributes.html)，在主控台無法存取時以程式設計方式驗證使用者屬性。

如需詳細資訊，請參閱[密碼、帳戶復原和密碼政策](managing-users-passwords.md)。

## `SECRET_HASH` 錯誤
<a name="troubleshoot_secret_hash_required"></a>

**問題**  
對具有用戶端秘密的應用程式用戶端發出的身分驗證 API 請求會傳回錯誤，例如 `An error occurred (NotAuthorizedException) when calling the ForgotPassword operation: Client 1example23456789 is configured with secret but SECRET_HASH was not received.`

**解決方案**  
您的應用程式必須計算目前使用者、應用程式用戶端和用戶端秘密`SECRET_HASH`的 。計算方法是：  

```
Base64 ( HMAC_SHA256 ( "client secret", "Username" + "Client Id" ) )
```
若要取得用戶端秘密，您可以：  

1. 開啟 Amazon Cognito 主控台，並從應用程式用戶端選單導覽至您的**應用程式用戶端**。在**應用程式用戶端資訊**區段中，尋找**用戶端秘密**。選取**顯示用戶端秘密**，並顯示您的應用程式用戶端秘密。

1. 產生 [DescribeUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPoolClient.html) 請求。用戶端秘密包含在回應中。

如需詳細資訊，請參閱[運算私密雜湊值](signing-up-users-in-your-app.md#cognito-user-pools-computing-secret-hash)。

## Amazon Cognito 主控台會為新使用者集區選擇預設組態
<a name="troubleshoot_console_default_config"></a>

**問題**  
當您在主控台中設定新的使用者集區時，Amazon Cognito 會為您選擇數個預設設定。使用者集區建立後，無法變更某些設定。如何做出明智的選擇，並了解 Amazon Cognito 自動選取的項目？

**解決方案**  
Amazon Cognito 主控台中的新使用者集區設定專為快速測試和原型設計。主控台只會為您提供最重要的組態選擇，也就是使用者集區建立後無法變更的選項。Amazon Cognito 自動設定的所有其他設定都可以稍後修改。  
建議採取下列作法：  

1. 在您精簡實作時，使用 主控台建立測試使用者集區。

1. 確定生產組態之後，將這些設定套用到您的測試使用者集區。

1. 使用 [DescribeUserPool](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPool.html) 和 [DescribeUserPoolClient](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_DescribeUserPoolClient.html) API 操作來產生已測試組態的 JSON 範本。

1. 使用這些範本搭配部署工具，例如 AWS SDKs、CDK、REST API 或 CloudFormation 來建立您的生產資源。

如需詳細資訊，請參閱[使用者集區入門](getting-started-user-pools.md)。

## 其他疑難排解資源
<a name="troubleshoot_additional_resources"></a>

如需其他疑難排解指引和社群貢獻的解決方案，您也可以探索下列外部資源：
+ [AWS re：Post Amazon Cognito 社群](https://repost.aws/tags/TAkhAE7QaGSoKZwd6utGhGDA/amazon-cognito) - 瀏覽社群問題和解決方案
+ [AWS 知識中心 Amazon Cognito 文章](https://aws.amazon.com/premiumsupport/knowledge-center/cognito/) - 策劃疑難排解文章