從 CSV 檔案將使用者匯入使用者集區

當您有外部身分存放區，以及為新的本機使用者準備使用者集區的時間時，從逗號分隔值 (CSV) 檔案大量使用者匯入可以是遷移到 Amazon Cognito 使用者集區的低成本、低成本選項。CSV 檔案匯入是下載和填入範本檔案的程序，然後在匯入任務中將檔案交給您的使用者集區。您可以使用 CSV 匯入來快速建立測試使用者。您也可以以程式設計方式將檔案填入外部身分存放區的讀取 API 請求，接著將其詳細資訊和屬性剖析為檔案的寫入操作。

根據預設，匯入程序會為密碼以外的所有使用者屬性設定值。這表示您的使用者必須在第一次登入時變更密碼。您的使用者在使用此方法匯入時處於 RESET_REQUIRED 狀態。

或者，您可以使用其現有的密碼雜湊匯入使用者。當您在匯入任務建立期間指定密碼雜湊演算法，並在 CSV 檔案中包含密碼雜湊時，Amazon Cognito 會使用現有的密碼匯入使用者。這些使用者會以 CONFIRMED 狀態建立，並且可以立即登入，而無需重設密碼。如需詳細資訊，請參閱使用密碼雜湊匯入使用者。

從 CSV 匯入使用者的最低努力方法是在您的使用者集區中啟用無密碼登入。透過電子郵件地址和電話號碼屬性以及正確的使用者集區組態，使用者可以在匯入任務完成後立即使用電子郵件或簡訊一次性密碼 (OTPs) 登入。如需詳細資訊，請參閱需要匯入的使用者重設密碼。

您也可以使用將 Permanent 參數設定為 的 AdminSetUserPassword API 請求來設定使用者的密碼true。CSV 匯入不會計入使用者集區中的每月計費作用中使用者 MAUs)。不過，密碼重設操作會產生 MAUs。若要在匯入具有密碼的大量使用者時管理成本，而這些使用者可能不會立即處於作用中狀態，請設定您的應用程式，在使用者登入並收到RESET_REQUIRED挑戰時提示他們輸入新密碼。

建立 CloudWatch Logs IAM 角色

如果您是使用 Amazon Cognito CLI 或 API，則您需要建立 CloudWatch IAM 角色。下列程序說明如何建立 IAM 角色，讓 Amazon Cognito 可用來將匯入任務的結果寫入 CloudWatch Logs。

建立使用者匯入 CSV 檔案

您必須先建立包含欲匯入使用者及其屬性的逗號分隔值 (CSV) 檔案，才能將現有使用者匯入使用者集區。從您的使用者集區中，您可以擷取含有反映使用者集區屬性結構描述之標頭的使用者匯入檔案。然後，您可以插入符合 格式化 CSV 檔案 中格式化需求的使用者資訊。

下載 CSV 檔案標頭 (主控台)

使用下列程序下載 CSV 標頭檔案。

下載 CSV 檔案標頭 (AWS CLI)

若要取得正確標頭的清單，請從匯入使用者下的使用者選單中，選取建立匯入任務。在下列對話方塊中，選取template.csv連結以下載具有使用者集區屬性的範本檔案。

您也可以執行下列 CLI 命令，其中 USER_POOL_ID 是您要匯入使用者的使用者集區的使用者集區識別符：

aws cognito-idp get-csv-header --user-pool-id "USER_POOL_ID"

回應範例：

{
    "CSVHeader": [
        "name",
        "given_name",
        "family_name",
        "middle_name",
        "nickname",
        "preferred_username",
        "profile",
        "picture",
        "website",
        "email",
        "email_verified",
        "gender",
        "birthdate",
        "zoneinfo",
        "locale",
        "phone_number",
        "phone_number_verified",
        "address",
        "updated_at",
        "cognito:mfa_enabled",
        "cognito:username"
    ],
    "UserPoolId": "USER_POOL_ID"
}

格式化 CSV 檔案

下載的使用者匯入 CSV 標頭檔案，如下字串所示：它也包含您新增到使用者集區中的任何自訂屬性。

cognito:username,name,given_name,family_name,middle_name,nickname,preferred_username,profile,picture,website,email,email_verified,gender,birthdate,zoneinfo,locale,phone_number,phone_number_verified,address,updated_at,cognito:mfa_enabled

編輯 CSV 檔案，以使其包含此標頭以及使用者的屬性值，並依照下列規則將其格式化：

下列清單是沒有自訂屬性之使用者集區的 CSV 匯入檔案範例。您的使用者集區結構描述可能與此範例不同。此時您必須在從使用者集區下載的 CSV 範本中提供測試值。

cognito:username,name,given_name,family_name,middle_name,nickname,preferred_username,profile,picture,website,email,email_verified,gender,birthdate,zoneinfo,locale,phone_number,phone_number_verified,address,updated_at,cognito:mfa_enabled
John,,John,Doe,,,,,,,johndoe@example.com,TRUE,,02/01/1985,,,+12345550100,TRUE,123 Any Street,,FALSE
Jane,,Jane,Roe,,,,,,,janeroe@example.com,TRUE,,01/01/1985,,,+12345550199,TRUE,100 Main Street,,FALSE

建立及執行 Amazon Cognito 使用者集區匯入任務

本節說明如何使用 Amazon Cognito 主控台和 AWS Command Line Interface () 來建立和執行使用者集區匯入任務AWS CLI。

從 CSV 檔案匯入使用者 (主控台)

下列程序說明如何從 CSV 檔案匯入使用者。

匯入使用者 (AWS CLI)

下列 CLI 命令可用來將使用者匯入使用者集區中：

若要取得這些命令的命令列選項清單，請使用 help 命令列選項。例如：

aws cognito-idp get-csv-header help

建立使用者匯入任務

在您建立 CSV 檔案之後，請執行下列 CLI 命令來建立使用者匯入任務，其中 JOB_NAME 是您為任務選擇的名稱，USER_POOL_ID 是新使用者會新增至其中的使用者集區 ID，而 ROLE_ARN 是您在 建立 CloudWatch Logs IAM 角色 中收到的角色 ARN：

aws cognito-idp create-user-import-job --job-name "JOB_NAME" --user-pool-id "USER_POOL_ID" --cloud-watch-logs-role-arn "ROLE_ARN"

在回應中傳回的 PRE_SIGNED_URL 有效時間為 15 分鐘。之後就會過期，而您必須建立新的使用者匯入任務來取得新的 URL。

{
    "UserImportJob": {
        "Status": "Created",
        "SkippedUsers": 0,
        "UserPoolId": "USER_POOL_ID",
        "ImportedUsers": 0,
        "JobName": "JOB_NAME",
        "JobId": "JOB_ID",
        "PreSignedUrl": "PRE_SIGNED_URL",
        "CloudWatchLogsRoleArn": "ROLE_ARN",
        "FailedUsers": 0,
        "CreationDate": 1470957431.965
    }
}

使用者匯入任務的狀態值

在對使用者匯入命令的回應中，您會看到下列其中一個 Status值：

上傳 CSV 檔案

您可以使用下列 curl 命令，將包含使用者資料的 CSV 檔案上傳至您從 create-user-import-job 命令的回應取得的預先簽章的 URL。

curl -v -T "PATH_TO_CSV_FILE" -H "x-amz-server-side-encryption:aws:kms" "PRE_SIGNED_URL"

在此命令的輸出中，尋找這個句子："We are completely uploaded and fine"。這個句子指出已成功上傳檔案。在您執行匯入任務之後，您的使用者集區不會保留匯入檔案中的資訊。它們完成或過期後，Amazon Cognito 會刪除您上傳的 CSV 檔案。

描述使用者匯入任務

若要取得使用者匯入任務的描述，請使用下列命令，其中 USER_POOL_ID 是您的使用者集區 ID，而 JOB_ID 是您建立使用者匯入任務時所傳回的任務 ID。

aws cognito-idp describe-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"

{
    "UserImportJob": {
        "Status": "Created",
        "SkippedUsers": 0,
        "UserPoolId": "USER_POOL_ID",
        "ImportedUsers": 0,
        "JobName": "JOB_NAME",
        "JobId": "JOB_ID",
        "PreSignedUrl": "PRE_SIGNED_URL",
        "CloudWatchLogsRoleArn":"ROLE_ARN",
        "FailedUsers": 0,
        "CreationDate": 1470957431.965
    }
}

在上述輸出範例中，PRE_SIGNED_URL 是您上傳 CSV 檔案的 URL。ROLE_ARN 是您建立角色時，所收到的 CloudWatch Logs 角色 ARN。

列出您的使用者匯入任務

若要列出您的使用者匯入任務，請使用下列命令：

aws cognito-idp list-user-import-jobs --user-pool-id "USER_POOL_ID" --max-results 2

{
    "UserImportJobs": [
        {
            "Status": "Created",
            "SkippedUsers": 0,
            "UserPoolId": "USER_POOL_ID",
            "ImportedUsers": 0,
            "JobName": "JOB_NAME",
            "JobId": "JOB_ID",
            "PreSignedUrl":"PRE_SIGNED_URL",
            "CloudWatchLogsRoleArn":"ROLE_ARN",
            "FailedUsers": 0,
            "CreationDate": 1470957431.965
        },
        {
            "CompletionDate": 1470954227.701,
            "StartDate": 1470954226.086,
            "Status": "Failed",
            "UserPoolId": "USER_POOL_ID",
            "ImportedUsers": 0,
            "SkippedUsers": 0,
            "JobName": "JOB_NAME",
            "CompletionMessage": "Too many users have failed or been skipped during the import.",
            "JobId": "JOB_ID",
            "PreSignedUrl":"PRE_SIGNED_URL",
            "CloudWatchLogsRoleArn":"ROLE_ARN",
            "FailedUsers": 5,
            "CreationDate": 1470953929.313
        }
    ],
    "PaginationToken": "PAGINATION_TOKEN"
}

任務會依時間順序列出，從最後建立排到最先建立。第二個任務之後的 PAGINATION_TOKEN 字串表示此列出命令還有其他結果。若要列出其他結果，請使用 --pagination-token選項，如下所示：

aws cognito-idp list-user-import-jobs --user-pool-id "USER_POOL_ID" --max-results 10 --pagination-token "PAGINATION_TOKEN"

啟動使用者匯入任務

若要啟動使用者匯入任務，請使用下列命令：

aws cognito-idp start-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"

每個帳戶一次只能有一個匯入任務處於作用中狀態。

{
    "UserImportJob": {
        "Status": "Pending",
        "StartDate": 1470957851.483,
        "UserPoolId": "USER_POOL_ID",
        "ImportedUsers": 0,
        "SkippedUsers": 0,
        "JobName": "JOB_NAME",
        "JobId": "JOB_ID",
        "PreSignedUrl":"PRE_SIGNED_URL",
        "CloudWatchLogsRoleArn": "ROLE_ARN",
        "FailedUsers": 0,
        "CreationDate": 1470957431.965
    }
}

停止使用者匯入任務

若要在使用者匯入任務進行時將其停止，請使用下列命令。停止任務後，就無法再重新啟動。

aws cognito-idp stop-user-import-job --user-pool-id "USER_POOL_ID" --job-id "JOB_ID"

{
    "UserImportJob": {
        "CompletionDate": 1470958050.571,
        "StartDate": 1470958047.797,
        "Status": "Stopped",
        "UserPoolId": "USER_POOL_ID",
        "ImportedUsers": 0,
        "SkippedUsers": 0,
        "JobName": "JOB_NAME",
        "CompletionMessage": "The Import Job was stopped by the developer.",
        "JobId": "JOB_ID",
        "PreSignedUrl":"PRE_SIGNED_URL",
        "CloudWatchLogsRoleArn": "ROLE_ARN",
        "FailedUsers": 0,
        "CreationDate": 1470957972.387
    }
}

在 CloudWatch 主控台中檢視使用者集區匯入結果

您可以在 Amazon CloudWatch 主控台中檢視匯入任務的結果。

檢視結果

下列步驟說明如何檢視使用者集區匯入結果。

解譯結果

成功匯入的使用者狀態會設為 "PasswordReset"。

在下列情況下，將不會匯入使用者，但匯入任務會繼續：

在下列情況下，匯入任務會失敗：

需要匯入的使用者重設密碼

如果您的使用者集區只提供以密碼為基礎的登入，使用者必須在匯入後重設密碼。第一次登入時，他們可以輸入任何密碼。Amazon Cognito 會提示他們在 API 回應中輸入來自您應用程式的登入請求中輸入新密碼。

如果您的使用者集區具有無密碼身分驗證因素，Amazon Cognito 會預設為匯入使用者的身分驗證因素。系統不會提示他們輸入新密碼，而且可以立即使用無密碼電子郵件或 SMS OTP 登入。您也可以提示使用者設定密碼，讓他們可以完成其他登入方法，例如 username-password 和 passkey。下列條件適用於使用者匯入後的無密碼登入。

如需無密碼身分驗證的詳細資訊，包括如何設定以及如何在應用程式中建構身分驗證流程，請參閱 使用 Amazon Cognito 使用者集區進行身分驗證。

下列程序說明在您匯入 CSV 檔案RESET_REQUIRED後， 中具有本機使用者的自訂登入機制使用者體驗。如果您的使用者使用受管登入來登入，請指示他們選取忘記密碼？ 選項，提供來自其電子郵件或文字訊息的代碼，並設定密碼。

使用密碼雜湊匯入使用者

當您將使用者從現有的身分驗證系統遷移至 Amazon Cognito 時，您可以匯入其密碼雜湊及其使用者屬性。然後，您的使用者可以使用現有的密碼立即登入，而無需重設密碼。使用者第一次登入後，Amazon Cognito 會透明地將其登入資料遷移至原生 Amazon Cognito 身分驗證系統。

密碼雜湊匯入的運作方式

使用密碼雜湊匯入，您可以遷移使用者，同時保留其使用現有密碼登入的能力。匯入程序的運作方式如下：

支援的密碼雜湊演算法

Amazon Cognito 支援下列用於匯入的密碼雜湊演算法：

如果密碼雜湊的參數值超過上列上限，則該使用者的匯入會失敗。在匯入之前，請檢閱來源系統的密碼雜湊組態，以確保相容性。

將密碼雜湊新增至 CSV 檔案

當您下載用於使用者匯入的 CSV 範本時，範本會包含 password_hash欄。將您要以現有密碼匯入之使用者的密碼雜湊值填入此欄。

cognito:username,email,email_verified,phone_number,phone_number_verified,password_hash
alejandro_rosalez,alejandro_rosalez@example.com,TRUE,+12345550100,TRUE,$2b$10$CtA.Rcu/szzn9U00wpUjOuN3vrgJRZycv4aOzcP3GzqzO8UDPEFq6
mary_major,mary_major@example.com,TRUE,+12345550199,TRUE,$2b$10$CtA.Rcu/szzn9U00wpUjOuN3vrgJRZycv4aOzcP3GzqzO8UDPEFq6

使用密碼雜湊建立匯入任務 (AWS CLI)

若要匯入具有密碼雜湊的使用者，您必須在建立匯入任務時指定密碼雜湊演算法。匯入任務中的所有使用者都必須使用相同的演算法。

使用下列 AWS Command Line Interface 命令來建立具有密碼雜湊的匯入任務。--password-hashing-algorithm 參數指定用來在 CSV 檔案中建立密碼雜湊的演算法。

aws cognito-idp create-user-import-job \
    --job-name "JOB_NAME" \
    --user-pool-id "USER_POOL_ID" \
    --cloud-watch-logs-role-arn "ROLE_ARN" \
    --password-hashing-algorithm BCRYPT

將 BCRYPT 取代為其中一個支援的演算法：BCRYPT、ARGON2ID、 SCRYPT或 PBKDF2_SHA256。

{
    "UserImportJob": {
        "Status": "Created",
        "SkippedUsers": 0,
        "UserPoolId": "USER_POOL_ID",
        "ImportedUsers": 0,
        "JobName": "JOB_NAME",
        "JobId": "JOB_ID",
        "PreSignedUrl": "PRE_SIGNED_URL",
        "CloudWatchLogsRoleArn": "ROLE_ARN",
        "PasswordHashingAlgorithm": "BCRYPT",
        "FailedUsers": 0,
        "CreationDate": 1470957431.965
    }
}

回應包含 欄位，PasswordHashingAlgorithm確認您指定的演算法。將 CSV 檔案上傳至預先簽章的 URL，並啟動任務，如中所述上傳 CSV 檔案。

匯入密碼雜湊後的使用者體驗

使用密碼雜湊匯入的使用者具有下列體驗：

對密碼雜湊匯入錯誤進行故障診斷

如果使用者的密碼雜湊匯入失敗，Amazon Cognito 會在 Amazon CloudWatch Logs 日誌中記錄失敗。常見的錯誤案例包括：

當使用者的密碼雜湊匯入失敗時，Amazon Cognito 不會建立使用者。匯入任務中的其他使用者會繼續處理。檢閱您的 Amazon CloudWatch Logs 日誌，以識別哪些使用者失敗，以及每次失敗的原因。

密碼雜湊匯入的安全考量

Amazon Cognito 會將其他安全措施套用至匯入的密碼雜湊：