Importazione di utenti nel bacino d'utenza da un file CSV

Se disponi di un archivio di identità esterno e hai tempo a disposizione per preparare il pool di utenti per nuovi utenti locali, l'importazione in blocco di utenti da un file con valori separati da virgole (CSV) può essere un'opzione semplice ed economica per la migrazione a un pool di utenti di Amazon Cognito. L'importazione di un file CSV consiste nel scaricare e compilare un file modello, per poi consegnarlo al gruppo di utenti in un processo di importazione. Puoi utilizzare un'importazione CSV per creare rapidamente utenti di prova. Puoi anche compilare a livello di codice il file con richieste API di lettura al tuo archivio di identità esterno, quindi analizzarne i dettagli e gli attributi in operazioni di scrittura sul file.

Per impostazione predefinita, il processo di importazione imposta i valori per tutti gli attributi utente tranne la password. Questo significa che i tuoi utenti devono cambiare le loro password dopo il primo accesso. Gli utenti sono in uno RESET_REQUIRED stato quando vengono importati con questo metodo.

In alternativa, puoi importare gli utenti con gli hash delle password esistenti. Quando specifichi un algoritmo di hashing delle password durante la creazione del processo di importazione e includi gli hash delle password nel tuo file CSV, Amazon Cognito importa gli utenti con le password esistenti. Questi utenti vengono creati con uno CONFIRMED stato e possono accedere immediatamente senza reimpostare le password. Per ulteriori informazioni, consulta Importazione di utenti con hash di password.

Il modo più semplice per importare utenti da un file CSV consiste nell'attivare l'accesso senza password nel tuo pool di utenti. Grazie agli attributi dell'indirizzo e-mail e del numero di telefono e alla corretta configurazione del pool di utenti, gli utenti possono accedere con password monouso (OTP) e-mail o SMS subito dopo il completamento del processo di importazione. Per ulteriori informazioni, consulta Necessità degli utenti importati di ripristinare le password.

Puoi anche impostare le password degli utenti con una richiesta AdminSetUserPasswordAPI che imposta il parametro su. Permanent true L'importazione di file CSV non contribuisce al numero di utenti attivi mensili (MAU) fatturati nel tuo pool di utenti. Tuttavia, le operazioni di reimpostazione della password generano MAU. Per gestire i costi quando importi un gran numero di utenti con password che potrebbero non essere immediatamente attivi, configura l'applicazione in modo che richieda agli utenti una nuova password quando accedono e ricevono la sfida. RESET_REQUIRED

Creazione del ruolo CloudWatch Logs IAM

Se utilizzi la CLI o l'API di Amazon Cognito, devi creare un ruolo IAM. CloudWatch La procedura seguente descrive come creare un ruolo IAM che Amazon Cognito può utilizzare per scrivere i risultati del processo di importazione in Logs. CloudWatch

Creazione di un file CSV di importazione degli utenti

Prima di poter importare gli utenti esistenti nel pool di utenti, è necessario creare un file CSV contenente gli utenti che si desidera importare e i relativi attributi. Dal pool di utenti, è possibile recuperare un file di importazione utente con intestazioni che riflettono lo schema di attributi del pool di utenti. È quindi possibile inserire le informazioni utente che soddisfano i requisiti di formattazione in Formattazione del file CSV.

Download dell'intestazione del file CSV (console)

Utilizza la seguente procedura per scaricare il file di intestazione CSV.

Scaricamento dell'intestazione del file CSV (AWS CLI)

Per ottenere un elenco delle intestazioni corrette, dal menu Utenti in Importa utenti, seleziona Crea processo di importazione. Nella finestra di dialogo che segue, seleziona il template.csv link per scaricare un file modello con gli attributi del tuo pool di utenti.

Puoi anche eseguire il seguente comando CLI, USER_POOL_ID dov'è l'identificatore del pool di utenti per il pool di utenti in cui importerai gli utenti:

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

Risposta di esempio:

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

Formattazione del file CSV

L'aspetto del file di intestazione CSV di importazione degli utenti scaricato è il seguente: Include anche eventuali attributi personalizzati aggiunti al pool di utenti.

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

Modificare il file CSV, in modo che includa questa intestazione e i valori di attributo per gli utenti. Il file viene formattato in base ai seguenti criteri:

L'elenco seguente è un esempio di file di importazione CSV per un pool di utenti senza attributi personalizzati. Lo schema del pool di utenti potrebbe differire da questo esempio. In tal caso, è necessario fornire valori di test nel modello CSV scaricato dal pool di utenti.

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

Creazione ed esecuzione del processo di importazione del bacino d'utenza di Amazon Cognito

Questa sezione descrive come creare ed eseguire il processo di importazione del pool di utenti utilizzando la console Amazon Cognito e AWS Command Line Interface ()AWS CLI.

Importazione di utenti da un file CSV (console)

Nella procedura seguente viene descritto come importare gli utenti dal file CSV.

Importazione di utenti (AWS CLI)

I seguenti comandi della CLI sono disponibili per importare gli utenti in un bacino d'utenza:

Per l'elenco delle opzioni della riga di comando per questi comandi, utilizza l'opzione help della riga di comando. Ad esempio:

aws cognito-idp get-csv-header help

Creazione di un processo di importazione degli utenti

Dopo aver creato il file CSV, crea un processo di importazione utenti eseguendo il seguente comando CLI, JOB_NAME dove è il nome che scegli per il processoUSER_POOL_ID, l'ID del pool di utenti per il pool di utenti a cui verranno aggiunti i nuovi utenti ROLE_ARN e il ruolo ARN in cui hai ricevuto: Creazione del ruolo 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"

Il valore PRE_SIGNED_URL restituito nella risposta è valido per 15 minuti. Dopo questo lasso di tempo scadrà e, a quel punto, è necessario creare un processo di importazione degli utenti per ottenere un nuovo 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
    }
}

Valori di stato per un processo di importazione degli utenti

Nelle risposte ai comandi di importazione degli utenti, visualizzerai uno dei seguenti valori Status:

Caricamento del file CSV

Utilizza il seguente comando curl per caricare il file CSV contenente i dati dell'utente nell'URL prefirmato che hai ottenuto dalla risposta del comando create-user-import-job.

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

Nell'output di questo comando, cerca la frase "We are completely uploaded and fine". Questa frase indica che il file è stato caricato correttamente. I tuoi pool di utenti non conservano le informazioni nei file di importazione dopo aver eseguito i processi di importazione. Una volta completati o scaduti, Amazon Cognito elimina il file CSV caricato.

Descrizione di un processo di importazione degli utenti

Per ottenere una descrizione del processo di importazione degli utenti, utilizza il seguente comando, dove si USER_POOL_ID trova l'ID del pool di utenti e JOB_ID l'ID del lavoro restituito quando hai creato il processo di importazione degli utenti.

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

Nell'output di esempio precedente, PRE_SIGNED_URL è l'URL in cui hai caricato il file CSV. ROLE_ARNÈ l'ARN del ruolo CloudWatch Logs che hai ricevuto quando hai creato il ruolo.

Elenco dei tuoi processi di importazione degli utenti

Per elencare i tuoi processi di importazione degli utenti, utilizza il comando seguente:

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

I processi sono elencati in ordine cronologico dall'ultimo creato al primo. La PAGINATION_TOKEN stringa dopo il secondo processo indica che ci sono risultati aggiuntivi per questo comando list. Per elencare i risultati aggiuntivi, utilizza l' opzione --pagination-token come segue:

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

Avvio di un processo di importazione degli utenti

Per avviare un processo di importazione degli utenti, utilizza il comando seguente:

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

Può essere attivo soltanto un processo di importazione alla volta per account.

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

Arresto di un processo di importazione degli utenti

Per arrestare un processo di importazione degli utenti mentre è in corso, utilizza il comando seguente. Una volta che hai interrotto il processo, non puoi riavviarlo.

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

Visualizzazione dei risultati di importazione del pool di utenti nella CloudWatch console

Puoi visualizzare i risultati del tuo processo di importazione nella CloudWatch console Amazon.

Visualizzazione dei risultati

I seguenti passaggi descrivono come visualizzare i risultati dell'importazione del bacino d'utenza.

Interpretazione dei risultati

Lo stato degli utenti importati con successo è impostato su "PasswordReset».

Nei seguenti casi, l'utente non verrà importato, ma il processo di importazione proseguirà:

Nei seguenti casi, il processo di importazione fallirà:

Necessità degli utenti importati di ripristinare le password

Se il tuo pool di utenti offre solo l'accesso basato su password, gli utenti devono reimpostare le password dopo l'importazione. La prima volta che accedono, possono inserire qualsiasi password. Amazon Cognito richiede loro di inserire una nuova password nella risposta API alla richiesta di accesso della tua applicazione.

Se il tuo pool di utenti dispone di fattori di autenticazione senza password, Amazon Cognito utilizza per impostazione predefinita quelli per gli utenti importati. Non viene loro richiesta una nuova password e possono accedere immediatamente con un'e-mail o un SMS OTP senza password. Puoi anche richiedere agli utenti di impostare una password in modo che possano completare altri metodi di accesso come nome utente-password e passkey. Le seguenti condizioni si applicano all'accesso senza password dopo l'importazione dell'utente.

Per ulteriori informazioni sull'autenticazione senza password, incluso come configurarla e come costruire il flusso di autenticazione nella tua applicazione, consulta. Autenticazione con pool di utenti Amazon Cognito

La procedura seguente descrive l'esperienza utente in un meccanismo di accesso personalizzato con utenti locali RESET_REQUIRED dopo l'importazione di un file CSV. Se i tuoi utenti accedono con accesso gestito, chiedi loro di selezionare la password dimenticata? opzione, fornisci il codice contenuto nell'e-mail o nel messaggio di testo e imposta una password.

Importazione di utenti con hash di password

Quando esegui la migrazione degli utenti da un sistema di autenticazione esistente ad Amazon Cognito, puoi importare gli hash delle loro password insieme agli attributi utente. I tuoi utenti possono quindi accedere immediatamente con le password esistenti, senza dover reimpostare la password. Dopo che gli utenti accedono per la prima volta, Amazon Cognito migra in modo trasparente le proprie credenziali al sistema di autenticazione nativo di Amazon Cognito.

Come funziona l'importazione di hash delle password

Con l'importazione dell'hash delle password, puoi migrare gli utenti preservando la loro capacità di accedere con le password esistenti. Il processo di importazione funziona come segue:

Algoritmi di hashing delle password supportati

Amazon Cognito supporta i seguenti algoritmi di hashing delle password per l'importazione:

Se l'hash della password ha valori di parametro che superano i limiti massimi sopra elencati, l'importazione non riesce per quell'utente. Controlla la configurazione dell'hashing delle password del sistema di origine prima dell'importazione per garantire la compatibilità.

Aggiungere gli hash delle password al file CSV

Quando scarichi il modello CSV per l'importazione da parte dell'utente, il modello include una colonna. password_hash Compila questa colonna con i valori hash delle password per gli utenti che desideri importare con le password esistenti.

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

Creazione di un processo di importazione con hash di password (AWS CLI)

Per importare utenti con hash di password, è necessario specificare l'algoritmo di hashing delle password quando si crea il processo di importazione. Tutti gli utenti del processo di importazione devono utilizzare lo stesso algoritmo.

Utilizzate il AWS Command Line Interface comando seguente per creare un processo di importazione con hash di password. Il --password-hashing-algorithm parametro specifica l'algoritmo utilizzato per creare gli hash delle password nel file 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

Sostituisci BCRYPT con uno degli algoritmi supportati:BCRYPT,, SCRYPT o. ARGON2ID 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
    }
}

La risposta include il PasswordHashingAlgorithm campo che conferma l'algoritmo specificato. Carica il file CSV nell'URL predefinito e avvia il processo come descritto in. Caricamento del file CSV

Esperienza utente dopo l'importazione dell'hash della password

Gli utenti importati con gli hash delle password hanno la seguente esperienza:

Risoluzione degli errori di importazione dell'hash delle password

Se l'importazione dell'hash della password non riesce per un utente, Amazon Cognito registra l'errore nei log di CloudWatch Amazon Logs. Gli scenari di errore più comuni includono:

Quando l'importazione dell'hash di una password non riesce per un utente, Amazon Cognito non crea l'utente. Gli altri utenti coinvolti nel processo di importazione continuano a essere elaborati. Controlla i log di Amazon CloudWatch Logs per identificare gli utenti che hanno fallito e il motivo di ogni errore.

Considerazioni sulla sicurezza per l'importazione di hash delle password

Amazon Cognito applica misure di sicurezza aggiuntive agli hash delle password importati: