Mengimpor pengguna ke kumpulan pengguna dari file CSV

Jika Anda memiliki penyimpanan identitas eksternal dan waktu untuk menyiapkan kumpulan pengguna untuk pengguna lokal baru, impor pengguna massal dari file nilai yang dipisahkan koma (CSV) dapat menjadi opsi berupaya rendah dan berbiaya rendah untuk migrasi ke kumpulan pengguna Amazon Cognito. Impor file CSV adalah proses mengunduh dan mengisi file template, kemudian menyerahkan file ke kumpulan pengguna Anda dalam pekerjaan impor. Anda dapat menggunakan impor CSV untuk membuat pengguna uji dengan cepat. Anda juga dapat secara terprogram mengisi file dengan permintaan API baca ke penyimpanan identitas eksternal Anda, diikuti dengan mengurai detail dan atributnya ke dalam operasi penulisan ke file.

Secara default, proses impor menetapkan nilai untuk semua atribut pengguna kecuali kata sandi. Ini berarti pengguna Anda harus mengubah kata sandi mereka saat pertama kali mereka masuk. Pengguna Anda berada dalam RESET_REQUIRED keadaan saat diimpor menggunakan metode ini.

Atau, Anda dapat mengimpor pengguna dengan hash kata sandi yang ada. Saat Anda menentukan algoritma hashing kata sandi selama pembuatan pekerjaan impor dan menyertakan hash kata sandi dalam file CSV Anda, Amazon Cognito akan mengimpor pengguna dengan kata sandi yang ada. Pengguna ini dibuat dengan CONFIRMED status dan dapat segera masuk tanpa mengatur ulang kata sandi mereka. Untuk informasi selengkapnya, lihat Mengimpor pengguna dengan hash kata sandi.

Cara terendah untuk mengimpor pengguna dari CSV adalah dengan mengaktifkan login tanpa kata sandi di kumpulan pengguna Anda. Dengan atribut alamat email dan nomor telepon serta konfigurasi kumpulan pengguna yang tepat, pengguna dapat masuk dengan kata sandi satu kali (OTP) email atau SMS segera setelah pekerjaan impor Anda selesai. Untuk informasi selengkapnya, lihat Mengharuskan pengguna yang diimpor untuk mengatur ulang kata sandi mereka.

Anda juga dapat mengatur kata sandi pengguna Anda dengan permintaan AdminSetUserPassword API yang menetapkan Permanent parameter ketrue. Impor CSV tidak berkontribusi pada pengguna aktif bulanan (MAU) yang ditagih di kumpulan pengguna Anda. Namun, operasi reset kata sandi memang menghasilkan MAU. Untuk mengelola biaya saat Anda mengimpor sejumlah besar pengguna dengan kata sandi yang mungkin tidak segera aktif, atur aplikasi Anda untuk meminta pengguna memasukkan kata sandi baru saat mereka masuk dan menerima RESET_REQUIRED tantangan.

Membuat peran CloudWatch Logs IAM

Jika Anda menggunakan Amazon COGNITO CLI atau API, maka Anda perlu membuat peran CloudWatch IAM. Prosedur berikut menjelaskan cara membuat peran IAM yang dapat digunakan Amazon Cognito untuk menulis hasil pekerjaan impor Anda ke CloudWatch Log.

Membuat file CSV impor pengguna

Sebelum Anda dapat mengimpor pengguna yang sudah ada ke kumpulan pengguna, Anda harus membuat file nilai yang dipisahkan koma (CSV) yang berisi pengguna yang ingin Anda impor, dan atributnya. Dari kumpulan pengguna, Anda dapat mengambil file impor pengguna dengan header yang mencerminkan skema atribut kumpulan pengguna Anda. Anda kemudian dapat memasukkan informasi pengguna yang sesuai dengan persyaratan pemformatan diMemformat file CSV.

Mengunduh header file CSV (konsol)

Gunakan prosedur berikut untuk mengunduh file header CSV.

Mengunduh header file CSV (AWS CLI)

Untuk mendapatkan daftar header yang benar, dari menu Pengguna di bawah Impor pengguna, pilih Buat pekerjaan impor. Dalam dialog berikut, pilih template.csv tautan untuk mengunduh file template dengan atribut kumpulan pengguna Anda.

Anda juga dapat menjalankan perintah CLI berikut, di mana pen USER_POOL_ID gidentifikasi kumpulan pengguna untuk kumpulan pengguna yang akan Anda impor pengguna ke:

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

Contoh respons:

{
    "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"
}

Memformat file CSV

File header CSV impor pengguna yang diunduh terlihat seperti string berikut. Ini juga mencakup atribut khusus yang telah Anda tambahkan ke kumpulan pengguna Anda.

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

Edit file CSV Anda sehingga menyertakan header ini dan nilai atribut untuk pengguna Anda, dan diformat sesuai dengan aturan berikut:

Daftar berikut adalah contoh file impor CSV untuk kumpulan pengguna tanpa atribut khusus. Skema kumpulan pengguna Anda mungkin berbeda dari contoh ini. Dalam hal ini, Anda harus memberikan nilai pengujian dalam template CSV yang Anda unduh dari kumpulan pengguna.

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

Membuat dan menjalankan pekerjaan impor kumpulan pengguna Amazon Cognito

Bagian ini menjelaskan cara membuat dan menjalankan tugas impor kumpulan pengguna dengan menggunakan konsol Amazon Cognito dan AWS Command Line Interface (AWS CLI).

Mengimpor pengguna dari file CSV (konsol)

Prosedur berikut menjelaskan cara mengimpor pengguna dari file CSV.

Mengimpor pengguna (AWS CLI)

Perintah CLI berikut tersedia untuk mengimpor pengguna ke kolam pengguna:

Untuk mendapatkan daftar opsi baris perintah untuk perintah ini, gunakan opsi baris perintah help. Sebagai contoh:

aws cognito-idp get-csv-header help

Membuat pekerjaan impor pengguna

Setelah Anda membuat file CSV, buat pekerjaan impor pengguna dengan menjalankan perintah CLI berikut, di mana JOB_NAME nama yang Anda pilih untuk pekerjaan, USER_POOL_ID adalah ID kumpulan pengguna untuk kumpulan pengguna tempat pengguna baru akan ditambahkan, dan ROLE_ARN merupakan peran ARN yang Anda terima di: Membuat peran CloudWatch Logs IAM

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

Yang PRE_SIGNED_URL dikembalikan dalam tanggapan berlaku selama 15 menit. Setelah waktu itu, itu akan kedaluwarsa dan Anda harus membuat pekerjaan impor pengguna baru untuk mendapatkan URL baru.

{
    "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
    }
}

Nilai status untuk pekerjaan impor pengguna

Dalam respons terhadap perintah impor pengguna, Anda akan melihat salah satu nilai Status berikut:

Mengunggah file CSV

Gunakan curl perintah berikut untuk mengunggah file CSV yang berisi data pengguna Anda ke URL yang telah ditandatangani sebelumnya yang Anda peroleh dari respons create-user-import-job perintah.

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

Dalam output dari perintah ini, cari frasa "We are completely uploaded and fine". Frasa ini menunjukkan bahwa file telah berhasil diunggah. Kumpulan pengguna Anda tidak menyimpan informasi dalam file impor setelah Anda menjalankan pekerjaan impor. Setelah selesai atau kedaluwarsa, Amazon Cognito menghapus file CSV yang Anda unggah.

Menjelaskan pekerjaan impor pengguna

Untuk mendapatkan deskripsi pekerjaan impor pengguna Anda, gunakan perintah berikut, di mana USER_POOL_ID ID kumpulan pengguna Anda, dan JOB_ID merupakan ID pekerjaan yang dikembalikan saat Anda membuat pekerjaan impor pengguna.

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
    }
}

Pada output sampel sebelumnya, PRE_SIGNED_URL adalah URL tempat Anda mengunggah file CSV. Ini ROLE_ARN adalah peran CloudWatch Logs ARN yang Anda terima saat Anda membuat peran.

Mendaftarkan pekerjaan impor pengguna Anda

Untuk membuat daftar pekerjaan impor pengguna Anda, gunakan perintah berikut:

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"
}

Pekerjaan terdaftar dalam urutan kronologis dari yang terakhir dibuat hingga yang pertama dibuat. PAGINATION_TOKENString setelah pekerjaan kedua menunjukkan bahwa ada hasil tambahan untuk perintah daftar ini. Untuk membuat daftar hasil tambahan, gunakan opsi --pagination-token sebagai berikut:

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

Memulai pekerjaan impor pengguna

Untuk memulai pekerjaan impor pengguna, gunakan perintah berikut:

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

Hanya satu tugas impor yang dapat aktif pada satu waktu per akun.

{
    "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
    }
}

Menghentikan pekerjaan impor pengguna

Untuk menghentikan pekerjaan impor pengguna saat sedang berlangsung, gunakan perintah berikut. Setelah Anda menghentikan pekerjaan, itu tidak dapat dimulai ulang.

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
    }
}

Melihat hasil impor kumpulan pengguna di CloudWatch konsol

Anda dapat melihat hasil pekerjaan impor Anda di CloudWatch konsol Amazon.

Melihat hasil

Langkah-langkah berikut menjelaskan cara melihat hasil impor kolam pengguna.

Menafsirkan hasil

Pengguna yang berhasil diimpor memiliki status disetel ke "PasswordReset”.

Dalam kasus berikut, pengguna tidak akan diimpor, tetapi pekerjaan impor akan dilanjutkan:

Dalam kasus berikut, pekerjaan impor akan gagal:

Mengharuskan pengguna yang diimpor untuk mengatur ulang kata sandi mereka

Jika kumpulan pengguna Anda hanya menawarkan login berbasis kata sandi, pengguna harus mengatur ulang kata sandi mereka setelah diimpor. Pertama kali mereka masuk, mereka dapat memasukkan kata sandi apa pun. Amazon Cognito meminta mereka untuk memasukkan kata sandi baru dalam respons API terhadap permintaan masuk dari aplikasi Anda.

Jika kumpulan pengguna Anda memiliki faktor otentikasi tanpa kata sandi, Amazon Cognito akan menjadikannya default untuk pengguna yang diimpor. Mereka tidak diminta untuk kata sandi baru, dan dapat langsung masuk dengan email tanpa kata sandi atau SMS OTP. Anda juga dapat meminta pengguna untuk menetapkan kata sandi sehingga mereka dapat menyelesaikan metode masuk lainnya seperti username-password dan kunci sandi. Ketentuan berikut berlaku untuk masuk tanpa kata sandi setelah impor pengguna.

Untuk informasi selengkapnya tentang otentikasi tanpa kata sandi termasuk cara mengaturnya dan cara membuat alur otentikasi di aplikasi Anda, lihat. Otentikasi dengan kumpulan pengguna Amazon Cognito

Prosedur berikut menjelaskan pengalaman pengguna dalam mekanisme login yang dibuat khusus dengan pengguna lokal RESET_REQUIRED setelah Anda mengimpor file CSV. Jika pengguna Anda masuk dengan login terkelola, instruksikan mereka untuk memilih L upa kata sandi? pilihan, berikan kode dari email atau pesan teks mereka, dan atur kata sandi.

Mengimpor pengguna dengan hash kata sandi

Saat Anda memigrasikan pengguna dari sistem otentikasi yang ada ke Amazon Cognito, Anda dapat mengimpor hash kata sandi mereka bersama dengan atribut pengguna mereka. Pengguna Anda kemudian dapat langsung masuk dengan kata sandi yang ada, tanpa pengaturan ulang kata sandi. Setelah pengguna masuk untuk pertama kalinya, Amazon Cognito secara transparan memigrasikan kredensialnya ke sistem otentikasi Amazon Cognito asli.

Cara kerja impor hash kata sandi

Dengan impor hash kata sandi, Anda dapat memigrasi pengguna sambil mempertahankan kemampuan mereka untuk masuk dengan kata sandi yang ada. Proses impor bekerja sebagai berikut:

Algoritma hashing kata sandi yang didukung

Amazon Cognito mendukung algoritma hashing kata sandi berikut untuk impor:

Jika hash kata sandi Anda memiliki nilai parameter yang melebihi batas maksimum yang tercantum di atas, impor gagal untuk pengguna tersebut. Tinjau konfigurasi hashing kata sandi sistem sumber Anda sebelum mengimpor untuk memastikan kompatibilitas.

Menambahkan hash kata sandi ke file CSV Anda

Saat Anda mengunduh template CSV untuk impor pengguna, templat menyertakan password_hash kolom. Isi kolom ini dengan nilai hash kata sandi untuk pengguna yang ingin Anda impor dengan kata sandi yang ada.

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

Membuat pekerjaan impor dengan hash kata sandi (AWS CLI)

Untuk mengimpor pengguna dengan hash kata sandi, Anda harus menentukan algoritma hashing kata sandi saat Anda membuat pekerjaan impor. Semua pengguna dalam pekerjaan impor harus menggunakan algoritma yang sama.

Gunakan AWS Command Line Interface perintah berikut untuk membuat pekerjaan impor dengan hash kata sandi. --password-hashing-algorithmParameter menentukan algoritma yang digunakan untuk membuat hash kata sandi di file CSV Anda.

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

Ganti BCRYPT dengan salah satu algoritma yang didukung:BCRYPT,SCRYPT,ARGON2ID, atauPBKDF2_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
    }
}

Respons mencakup PasswordHashingAlgorithm bidang yang mengonfirmasi algoritma yang Anda tentukan. Unggah file CSV Anda ke URL yang telah ditandatangani sebelumnya dan mulai pekerjaan seperti yang dijelaskan dalamMengunggah file CSV.

Pengalaman pengguna setelah impor hash kata sandi

Pengguna yang diimpor dengan hash kata sandi memiliki pengalaman berikut:

Memecahkan masalah kesalahan impor hash kata sandi

Jika impor hash kata sandi gagal untuk pengguna, Amazon Cognito mencatat kegagalan tersebut di CloudWatch log Amazon Logs Anda. Skenario kesalahan umum meliputi:

Ketika impor hash kata sandi gagal untuk pengguna, Amazon Cognito tidak membuat pengguna tersebut. Pengguna lain dalam pekerjaan impor terus diproses. Tinjau CloudWatch log Amazon Logs Anda untuk mengidentifikasi pengguna mana yang gagal dan alasan setiap kegagalan.

Pertimbangan keamanan untuk impor hash kata sandi

Amazon Cognito menerapkan langkah-langkah keamanan tambahan untuk hash kata sandi yang diimpor: