Mengimpor pengguna ke kumpulan pengguna dari file CSV

Ketika Anda memiliki penyimpanan identitas eksternal dan waktu untuk menyiapkan kumpulan pengguna Anda untuk pengguna lokal baru, impor pengguna massal dari file nilai yang dipisahkan koma (CSV) dapat menjadi opsi berbiaya rendah dan murah untuk migrasi ke kumpulan pengguna Amazon Cognito. Impor file CSV adalah proses mengunduh dan mengisi file template, lalu menyerahkan file ke kumpulan pengguna Anda dalam pekerjaan impor. Anda dapat menggunakan impor CSV untuk membuat pengguna pengujian dengan cepat. Anda juga dapat mengisi file secara terprogram 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 algoritme hashing kata sandi selama pembuatan pekerjaan impor dan menyertakan hash kata sandi dalam file CSV Anda, Amazon Cognito mengimpor pengguna dengan kata sandi yang ada. Pengguna ini dibuat dengan CONFIRMED status dan dapat langsung masuk tanpa mengatur ulang kata sandi mereka. Untuk informasi selengkapnya, lihat Mengimpor pengguna dengan hash kata sandi.

Cara paling rendah 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 email atau SMS kata sandi satu kali (OTP) 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 AdminSetUserPasswordAPI yang menetapkan Permanent parameter. true Impor CSV tidak berkontribusi pada pengguna aktif bulanan (MAUs) yang ditagih di kumpulan pengguna Anda. Namun, operasi pengaturan ulang kata sandi memang menghasilkan UI. Untuk mengelola biaya ketika Anda mengimpor sejumlah besar pengguna dengan kata sandi yang mungkin tidak segera aktif, siapkan aplikasi Anda untuk meminta pengguna untuk kata sandi baru saat mereka masuk dan menerima RESET_REQUIRED tantangan.

Membuat peran IAM CloudWatch Log

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

Membuat file CSV impor pengguna

Sebelum dapat mengimpor pengguna yang sudah ada ke kumpulan pengguna, Anda harus membuat file nilai 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 menyisipkan informasi pengguna yang cocok 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 templat dengan atribut kumpulan pengguna Anda.

Anda juga dapat menjalankan perintah CLI berikut, di mana USER_POOL_ID adalah pengidentifikasi 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 apa pun 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 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
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 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, JOB_NAME di mana nama yang Anda pilih untuk pekerjaan ituUSER_POOL_ID, adalah ID kumpulan pengguna untuk kumpulan pengguna tempat pengguna baru akan ditambahkan, ROLE_ARN dan merupakan peran ARN yang Anda terima di: Membuat peran IAM CloudWatch Log

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 respons 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 ditentukan sebelumnya yang Anda peroleh dari respons perintah. create-user-import-job

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 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 USER_POOL_ID mana ID kumpulan pengguna Anda, dan JOB_ID 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, URL tempat PRE_SIGNED_URL Anda mengunggah file CSV. ROLE_ARNIni adalah peran CloudWatch Log ARN yang Anda terima saat Anda membuat peran.

Cantumkan 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 hasilnya

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

Menafsirkan hasil

Pengguna yang berhasil diimpor memiliki status mereka 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 untuk permintaan masuk dari aplikasi Anda.

Jika kumpulan pengguna Anda memiliki faktor autentikasi tanpa kata sandi, Amazon Cognito akan menjadi 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 mengatur kata sandi sehingga mereka dapat menyelesaikan metode masuk lainnya seperti username-password dan passkey. Ketentuan berikut berlaku untuk login tanpa kata sandi setelah impor pengguna.

Untuk informasi selengkapnya tentang otentikasi tanpa kata sandi termasuk cara mengaturnya dan cara membuat alur otentikasi dalam 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 Lupa kata sandi? pilihan, memberikan kode dari email atau pesan teks mereka, dan mengatur password.

Mengimpor pengguna dengan hash kata sandi

Saat memigrasikan pengguna dari sistem autentikasi yang ada ke Amazon Cognito, Anda dapat mengimpor hash kata sandi mereka beserta atribut penggunanya. 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 memigrasikan pengguna sambil mempertahankan kemampuan mereka untuk masuk dengan kata sandi yang ada. Proses impor berfungsi 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 dalam 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,, SCRYPTARGON2ID, 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
    }
}

Responsnya mencakup PasswordHashingAlgorithm bidang yang mengonfirmasi algoritma yang Anda tentukan. Unggah file CSV Anda ke URL yang telah ditentukan sebelumnya dan mulai pekerjaan seperti yang dijelaskan di. Mengunggah 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 dalam log CloudWatch Amazon Log Anda. Skenario kesalahan umum meliputi:

Ketika impor hash kata sandi gagal untuk pengguna, Amazon Cognito tidak membuat pengguna. Pengguna lain dalam pekerjaan impor terus diproses. Tinjau CloudWatch log Amazon Log 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: