將自有網域用於託管 UI

設定應用程式用戶端之後，您可以設定使用者集區搭配自訂網域，以用於 Amazon Cognito 託管 UI 和身分驗證 API 端點。利用自訂網域，您就能讓使用者使用您的自有網址登入您的應用程式。

將自訂網域新增到使用者集區

若要新增自訂網域到您的使用者集區，請由 Amazon Cognito 主控台指定網域名稱，並提供您透過 AWS Certificate Manager (ACM) 所管理的憑證。在您新增網域後，Amazon Cognito 將提供別名目標以讓您加入至您的 DNS 組態。

必要條件

開始之前，您需要：

• 搭配應用程式用戶端的使用者集區。如需詳細資訊，請參閱 使用者集區入門。

• 您擁有的 Web 網域。其父網域必須有一個有效的 DNS A 記錄。您可以為此記錄指派任何值。父網域可能是網域的根，也可以是網域階層中向上一層的子網域。例如，如果您的自訂網域是 auth.xyz.example.com，則 Amazon Cognito 必須能夠將 yz.example.com 解析至一個 IP 地址。為了避免意外影響客戶基礎設施，Amazon Cognito 不支援將頂層網域 (TLD) 用於自訂網域。如需詳細資訊，請參閱網域名稱。

• 能夠為您的自訂網域建立子網域。建議您使用 auth 做為子網域。例如：auth.example.com。

  注意

  如果您沒有萬用字元憑證，那麼您可能需要為自訂網域的子網域取得新憑證。

• 由 ACM 管理的 Secure Sockets Layer (SSL) 憑證。

  注意

  在申請或匯入憑證之前，您必須在 ACM 主控台中將 AWS 區域變更為美國東部 (維吉尼亞北部)。

• 允許您的使用者集區授權伺服器將 Cookie 新增至使用者工作階段的應用程式。Amazon Cognito 為託管的用戶界面設置了幾個必需的 cookie。其中包括 cognito、cognito-fl 和 XSRF-TOKEN。雖然每個個別 Cookie 都符合瀏覽器大小限制，但是對使用者集區設定的變更可能會導致託管 UI Cookie 的大小增加。自訂網域前面的中繼服務 (例如 Application Load Balancer (ALB) 可能會強制執行標頭大小上限或總 Cookie 大小。如果您的應用程式也設定了自己的 Cookie，使用者的工作階段可能會超過這些限制。我們建議您不要在託管 UI 子網域上設定 Cookie，以避免大小限制衝突。

• 更新 Amazon CloudFront 分發的許可。做法是將下列 IAM 政策陳述式連接至您 AWS 帳戶中的使用者：

  {
      "Version": "2012-10-17",
      "Statement": [
           {
              "Sid": "AllowCloudFrontUpdateDistribution",
              "Effect": "Allow",
              "Action": [
                  "cloudfront:updateDistribution"
              ],
              "Resource": [
                  "*"
              ]
          }
      ]
  }

  如需有關授權動作的詳細資訊 CloudFront，請參閱〈使用以身分為基礎的政策 (IAM 政策)〉。 CloudFront

  Amazon Cognito 一開始會使用您的 IAM 許可來設定 CloudFront分發，但分配由 AWS管理。您無法變更 Amazon Cognito 與您的使用者集區相關聯的 CloudFront 分發組態。例如，您無法更新安全性政策中支援的 TLS 版本。

步驟 1：輸入您的自訂網域名稱

您可以使用 Amazon Cognito 主控台或 API，新增網域到您的使用者集區。

Amazon Cognito console

從 Amazon Cognito 主控台新增網域到您的使用者集區：

1. 登入 Amazon Cognito 主控台。若出現提示，請輸入 AWS 憑證。

2. 選擇 User pools (使用者集區)。

3. 選擇您要為其新增網域的使用者集區。

4. 選擇 App integration (應用程式整合) 索引標籤。

5. 在 Domain (網域) 旁，選擇 Actions (動作)，然後選擇 Create custom domain (建立自訂網域)。

   注意

   如果您已設定使用者集區網域，請選擇 Delete Cognito domain (刪除 Cognito 網域) 或者 Delete custom domain (刪除自訂網域)，以在建立新的自訂網域前刪除現有網域。

6. 對於 Custom domain (自訂網域)，輸入您要與 Amazon Cognito 搭配使用之網域的 URL。網域名稱只能包含小寫字母、數字和連字號。第一個字元或最後一個字元切勿使用連字號。使用句號分隔子網域名稱。

7. 對於 ACM certificate (ACM 憑證)，選擇您要用於此網域的 SSL 憑證。只有美國東部 (維吉尼亞北部) 的 ACM 憑證才能與 Amazon Cognito 自訂網域搭配使用，無論您 AWS 區域 的使用者集區為何。

   如果您沒有可用的憑證，則可使用 ACM 在美國東部 (維吉尼亞北部) 佈建一個憑證。如需詳細資訊，請參閱 AWS Certificate Manager 使用者指南中的入門。

8. 選擇建立。

9. Amazon Cognito 會讓您返回 App integration (應用程式整合) 索引標籤。系統會顯示標題為 Create an alias record in your domain's DNS (在您網域的 DNS 中建立別名記錄) 的訊息。請記下主控台中顯示的 Domain (網域) 和 Alias target (別名目標)。會在下一個步驟中使用它們，以將流量導向您的自訂網域。

API

使用 Amazon Cognito API 新增網域到您的使用者集區

• 使用 CreateUserPoolDomain 動作。

步驟 2：新增別名目標和子網域

在此步驟中，您會透過網域名稱伺服器 (DNS) 服務供應商，設定可指回在先前步驟所指定別名目標的別名。如果是使用 Amazon Route 53 進行 DNS 位址解析，請選擇使用 Route 53 新增別名目標和子網域一節。

將別名目標和子網域新增到目前的 DNS 組態

• 如果不是使用 Route 53 進行 DNS 地址解析，則您必須使用 DNS 服務供應商的組態工具，將先前步驟中的別名目標新增為網域的 DNS 記錄。您的 DNS 供應商也必須為您的自訂網域設定子網域。

使用 Route 53 新增別名目標和子網域

1. 登入 Route 53 主控台。若出現提示，請輸入 AWS 憑證。

2. 如果您在 Route 53 中沒有託管區域，請創建一個具有根的根目錄，該根是您的自定義域的父代。如需詳細資訊，請參閱

   1. 選擇建立託管區域。

   2. 輸入您自訂網域的上層網域，例如 auth.example.com，來自 Domain Name (網域名稱) 清單的網域，例如 myapp.auth.example.com。

   3. 輸入託管區域的說明。

   4. 選擇 Public hosted zone (公有託管區域) 的託管區域 Type (類型)，以允許公有用戶端解析您的自訂網域。不支援選擇 Private hosted zone (私有託管區域)。

   5. 根據需要套用 Tags (標籤)。

   6. 選擇建立託管區域。

      注意

      您也可以為自訂網域建立新的託管區域，可以在上層託管區域中建立委派集，上層託管區域會將查詢導向子網域託管區域。否則，請建立 A 記錄。此方法為您的託管區域提供更多靈活性與安全性。如需詳細資訊，請參閱為透過 Amazon Route 53 託管的網域建立子網域。

3. 在 Hosted Zones (託管區域) 頁面上，選擇託管區域的名稱。

4. 如果您還沒有自訂網域的上層網域，請新增 DNS 記錄。新增上層網域的 DNS A 記錄，然後選擇 [建立記錄]。以下是網域 auth.example.com 的範例記錄。

   auth.example.com. 60 IN A 198.51.100.1

   注意

   Amazon Cognito 會驗證您自訂網域的上層網域是否有 DNS 記錄，以防止生產網域遭到意外劫持。如果您沒有上層網域的 DNS 記錄，則 Amazon Cognito 會在您嘗試設定自訂網域時傳回錯誤。授權開始 (SOA) 記錄不足以用於父系網域驗證的 DNS 記錄。

5. 為您的自訂網域新增 DNS 記錄。例如，您記錄必須指向自訂網域別名目標123example.cloudfront.net。再次選擇 Create record (建立記錄)。

6. 輸入與您的自訂網域相符的 Record name (記錄名稱)，例如 myapp 來建立 myapp.auth.example.com 的記錄。

7. 啟用 Alias (別名) 選項。

8. 在 Route traffic to (將流量路由至) 下，選擇 Alias to CloudFront distribution (CloudFront 分佈的別名)。輸入您建立自訂網域時 Amazon Cognito 提供的 Alias target (別名目標)。

9. 選擇 Create Records (建立記錄)。

   注意

   您的新記錄可能需要大約 60 秒才能傳播到所有 Route 53 DNS 伺服器。您可以使用 Route 53 GetChangeAPI 方法來驗證您的變更是否已傳播。

步驟 3：驗證您的登入頁面

• 驗證可從自訂網域使用上述登入頁面。

  在瀏覽器中輸入這個地址後，登入您的自訂網域和子網域。下面是自訂網域 example.com、子網域 auth 的範例 URL：

  
  https://myapp.auth.example.com/login?response_type=code&client_id=<your_app_client_id>&redirect_uri=<your_callback_url>
  

變更自訂網域所用的 SSL 憑證

必要時，您可以使用 Amazon Cognito 變更自訂網域所要套用的憑證。

通常，若是由 ACM 例行憑證續約便不需要這麼做。當您在 ACM 續約現有的憑證時，該憑證的 ARN 將保持不變，而且您的自訂網域會自動使用新的憑證。

不過，若您使用新的憑證取代現有的憑證，則 ACM 將為新的憑證指派新的 ARN。若要將新憑證套用到您的自訂網域，您必須向 Amazon Cognito 提供該 ARN。

在您提供新憑證之後，Amazon Cognito 需歷經 1 小時才能將其分發到您的自訂網域。

開始之前

若要在 Amazon Cognito 中變更您的憑證，您必須先將該憑證新增至 ACM。如需詳細資訊，請參閱 AWS Certificate Manager 使用者指南中的入門。

將憑證新增至 ACM 時，您必須選擇美國東部 (維吉尼亞北部) 當作 AWS 區域。

您可以使用 Amazon Cognito 主控台或 API 變更您的憑證。

AWS Management Console

從 Amazon Cognito 主控台續約憑證：

1. 登入 AWS Management Console 並開啟 Amazon Cognito 主控台，位於https://console.aws.amazon.com/cognito/home。

2. 選擇 User Pools (使用者集區)。

3. 選擇您要為其更新憑證的使用者集區。

4. 選擇 App integration (應用程式整合) 索引標籤。

5. 選擇 Actions (動作)、Edit ACM certificate (編輯 ACM 憑證)。

6. 選取您要與自訂網域產生關聯的新憑證。

7. 選擇 Save changes (儲存變更)。

API

續約憑證 (Amazon Cognito API)

• 使用 UpdateUserPoolDomain 動作。