Importieren von Benutzern aus einer CSV-Datei in Benutzerpools

Wenn Sie über einen externen Identitätsspeicher verfügen und Zeit haben, Ihren Benutzerpool für neue lokale Benutzer vorzubereiten, kann ein Massenimport von Benutzern aus einer CSV-Datei (Comma-Separated Values) eine einfache und kostengünstige Option für eine Migration zu einem Amazon Cognito Cognito-Benutzerpool sein. Ein CSV-Dateiimport ist ein Vorgang, bei dem eine Vorlagendatei heruntergeladen und gefüllt wird. Anschließend wird die Datei in einem Importjob an Ihren Benutzerpool übergeben. Sie können einen CSV-Import verwenden, um schnell Testbenutzer zu erstellen. Sie können die Datei auch programmgesteuert mit API-Leseanforderungen an Ihren externen Identitätsspeicher füllen und anschließend deren Details und Attribute analysieren, um Schreibvorgänge in die Datei durchzuführen.

Standardmäßig legt der Importvorgang Werte für alle Benutzerattribute mit Ausnahme des Kennworts fest. Das bedeutet, dass Ihre Benutzer ihre Passwörter ändern müssen, wenn er sich das erste Mal anmelden. Ihre Benutzer befinden sich in einem RESET_REQUIRED Zustand, wenn sie mit dieser Methode importiert wurden.

Alternativ können Sie Benutzer mit ihren vorhandenen Passwort-Hashes importieren. Wenn Sie bei der Erstellung des Importauftrags einen Passwort-Hashing-Algorithmus angeben und Passwort-Hashes in Ihre CSV-Datei aufnehmen, importiert Amazon Cognito die Benutzer mit ihren vorhandenen Passwörtern. Diese Benutzer werden mit einem CONFIRMED Status erstellt und können sich sofort anmelden, ohne ihre Passwörter zurückzusetzen. Weitere Informationen finden Sie unter Benutzer mit Passwort-Hashes importieren.

Der einfachste Weg, Benutzer aus einer CSV-Datei zu importieren, besteht darin, die passwortlose Anmeldung in Ihrem Benutzerpool zu aktivieren. Mit den Attributen E-Mail-Adresse und Telefonnummer und der richtigen Benutzerpool-Konfiguration können sich Benutzer sofort nach Abschluss Ihres Importvorgangs mit E-Mail- oder SMS-Einmalpasswörtern (OTPs) anmelden. Weitere Informationen finden Sie unter Von importierten Benutzer verlangen, dass sie ihre Passwörter zurücksetzen.

Sie können die Passwörter Ihrer Benutzer auch mit einer AdminSetUserPasswordAPI-Anfrage festlegen, die den Permanent Parameter auf true festlegt. Der CSV-Import trägt nicht zu den in Rechnung gestellten monatlichen aktiven Benutzern (MAUs) in Ihrem Benutzerpool bei. Bei Vorgängen zum Zurücksetzen von Passwörtern werden jedoch MAUs generiert. Um die Kosten zu minimieren, wenn Sie eine große Anzahl von Benutzern mit einem Kennwort importieren, die möglicherweise nicht sofort aktiv sind, richten Sie Ihre Anwendung so ein, dass Benutzer bei der Anmeldung und beim Empfang der Aufforderung zur Eingabe eines neuen Kennworts aufgefordert werden. RESET_REQUIRED

Die IAM-Rolle „ CloudWatch Logs“ erstellen

Wenn Sie die Amazon Cognito CLI oder API verwenden, müssen Sie eine CloudWatch IAM-Rolle erstellen. Das folgende Verfahren beschreibt, wie Sie eine IAM-Rolle erstellen, mit der Amazon Cognito die Ergebnisse Ihres Importauftrags in Logs schreiben kann. CloudWatch

Erstellen der CSV-Datei für den Benutzerimport

Bevor Sie vorhandene Benutzer in Ihren Benutzerpool importieren können, müssen Sie eine Datei mit durch Kommas getrennten Werten (CSV-Datei) erstellen, die die zu importierenden Benutzer und ihre Attribute enthält. Aus Ihrem Benutzerpool können Sie eine Benutzerimportdatei mit Headern abrufen, die das Attributschema Ihres Benutzerpools widerspiegeln. Anschließend können Sie Benutzerinformationen einfügen, die den Formatierungsanforderungen im Abschnitt Formatieren der CSV-Datei entsprechen.

Herunterladen des CSV-Datei-Headers (Konsole)

Gehen Sie wie folgt vor, um die CSV-Header-Datei herunterzuladen.

Der Header der CSV-Datei wird heruntergeladen (AWS CLI)

Um eine Liste der richtigen Header zu erhalten, wählen Sie im Menü Benutzer unter Benutzer importieren die Option Importjob erstellen aus. Wählen Sie im folgenden Dialogfeld den template.csv Link zum Herunterladen einer Vorlagendatei mit Ihren Benutzerpool-Attributen aus.

Sie können auch den folgenden CLI-Befehl ausführen, der die Benutzerpool-ID für den Benutzerpool enthält, in USER_POOL_ID den Sie Benutzer importieren werden:

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

Beispielantwort:

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

Formatieren der CSV-Datei

Die heruntergeladene CSV-Header-Datei für den Benutzerimport sieht wie die folgende Zeichenfolge aus. Sie enthält auch benutzerdefinierte Attribute, die Sie Ihrem Benutzerpool hinzugefügt haben.

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

Bearbeiten Sie Ihre CSV-Datei, sodass sie diesen Header und die Attributwerte für Ihre Benutzer enthält und gemäß den folgenden Regeln formatiert ist:

Die folgende Liste ist ein Beispiel für eine CSV-Importdatei für einen Benutzerpool ohne benutzerdefinierte Attribute. Ihr Benutzerpool-Schema kann sich von diesem Beispiel unterscheiden. In diesem Fall müssen Sie Testwerte in der CSV-Vorlage angeben, die Sie aus Ihrem Benutzerpool herunterladen.

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

Erstellen und Ausführen des Amazon-Cognito-Benutzerpool-Importauftrags

In diesem Abschnitt wird beschrieben, wie Sie den Benutzerpool-Importauftrag mithilfe der Amazon Cognito Cognito-Konsole und der AWS Command Line Interface (AWS CLI) erstellen und ausführen.

Importieren von Benutzern aus einer CSV-Datei (Konsole)

Im folgenden Verfahren wird beschrieben, wie Sie Benutzer aus der CSV-Datei importieren.

Benutzer importieren (AWS CLI)

Die folgenden CLI-Befehle sind für den Import von Benutzern in einen Benutzerpool verfügbar:

Um die Liste der Befehlszeilen-Optionen für diese Befehle zu erhalten, verwenden Sie die Befehlszeilen-Option help. Beispiel:

aws cognito-idp get-csv-header help

Erstellen eines Benutzer-Importauftrags

Nachdem Sie Ihre CSV-Datei erstellt haben, erstellen Sie einen Benutzerimportauftrag, indem Sie den folgenden CLI-Befehl ausführen. Dabei JOB_NAME stehen der Name, den Sie für den Job wählen, USER_POOL_ID die Benutzerpool-ID für den Benutzerpool, dem die neuen Benutzer hinzugefügt werden, und ROLE_ARN der Rollen-ARN, in dem Sie erhalten habenDie IAM-Rolle „ CloudWatch Logs“ erstellen:

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

Der in der Antwort PRE_SIGNED_URL zurückgegebene Wert ist 15 Minuten gültig. Nach dieser Zeit läuft sie ab, und Sie müssen einen neuen Benutzer-Importauftrag erstellen, um eine neue URL zu erhalten.

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

Statuswerte für einen Benutzer-Importauftrag

In den Antworten auf Ihre Benutzer-Importbefehle sehen Sie einen der folgenden Status-Werte:

Hochladen der CSV-Datei

Verwenden Sie den folgenden curl-Befehl zum Hochladen der CSV-Datei mit Ihren Benutzerdaten auf die vorsignierte URL, die Sie aus der Antwort des create-user-import-job-Befehls erhalten haben.

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

In der Ausgabe dieses Befehls suchen Sie die Zeichenfolge "We are completely uploaded and fine". Diese Phrase gibt an, dass die Datei erfolgreich hochgeladen wurde. Ihre Benutzerpools behalten die Informationen in Ihren Importdateien nicht bei, nachdem Sie Ihre Importjobs ausgeführt haben. Nachdem sie abgeschlossen sind oder abgelaufen sind, löscht Amazon Cognito Ihre hochgeladene CSV-Datei.

Beschreiben eines Benutzer-Importauftrags

Um eine Beschreibung Ihres Benutzerimport-Jobs zu erhalten, verwenden Sie den folgenden Befehl. Dabei USER_POOL_ID steht Ihre Benutzerpool-ID und JOB_ID die Job-ID, die bei der Erstellung des Benutzerimport-Jobs zurückgegeben wurde.

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

In der vorherigen Beispielausgabe PRE_SIGNED_URL ist dies die URL, zu der Sie die CSV-Datei hochgeladen haben. Das ROLE_ARN ist der ARN der CloudWatch Logs-Rolle, den Sie bei der Erstellung der Rolle erhalten haben.

Auflisten Ihrer Benutzer-Importaufträge

Zum Auflisten Ihrer Benutzer-Importaufträge verwenden Sie den folgenden Befehl:

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

Aufträge werden in chronologischer Reihenfolge vom zuletzt erstellten bis zum zuerst erstellten aufgelistet. Die PAGINATION_TOKEN Zeichenfolge nach dem zweiten Job gibt an, dass für diesen Listenbefehl zusätzliche Ergebnisse vorliegen. Um die zusätzlichen Ergebnisse aufzulisten, verwenden Sie die Option --pagination-token wie folgt:

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

Starten eines Benutzer-Importauftrags

Zum Starten eines Benutzer-Importauftrags verwenden Sie den folgenden Befehl:

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

Nur ein Importauftrag kann jeweils aktiv sein.

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

Anhalten eines Benutzer-Importauftrags

Zum Anhalten eines Benutzer-Importauftrags, während dieser ausgeführt wird, verwenden Sie den folgenden Befehl. Nachdem Sie den Auftrag angehalten haben, kann er nicht neu gestartet werden.

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

Die Importergebnisse des Benutzerpools in der CloudWatch Konsole anzeigen

Sie können die Ergebnisse Ihres Importauftrags in der CloudWatch Amazon-Konsole einsehen.

Anzeigen der Ergebnisse

In den folgenden Schritten wird beschrieben, wie Sie die Benutzerpool-Importergebnisse anzeigen.

Interpretieren der Ergebnisse

Der Status von erfolgreich importierten Benutzern ist auf "PasswordReset" gesetzt.

In den folgenden Fällen wird der Benutzer nicht importiert, der Importauftrag wird jedoch fortgesetzt:

In den folgenden Fällen schlägt der Importauftrag fehl:

Von importierten Benutzer verlangen, dass sie ihre Passwörter zurücksetzen

Wenn Ihr Benutzerpool nur die kennwortbasierte Anmeldung anbietet, müssen Benutzer ihre Passwörter nach dem Import zurücksetzen. Bei der ersten Anmeldung können sie ein beliebiges Passwort eingeben. Amazon Cognito fordert sie auf, in der API-Antwort auf die Anmeldeanfrage Ihrer Anwendung ein neues Passwort einzugeben.

Wenn Ihr Benutzerpool kennwortlose Authentifizierungsfaktoren hat, verwendet Amazon Cognito standardmäßig die für importierte Benutzer. Sie werden nicht zur Eingabe eines neuen Passworts aufgefordert und können sich sofort mit einem passwortlosen E-Mail- oder SMS-OTP anmelden. Sie können Benutzer auch auffordern, ein Passwort festzulegen, damit sie andere Anmeldemethoden wie Benutzername/Passwort und Hauptschlüssel verwenden können. Die folgenden Bedingungen gelten für die kennwortlose Anmeldung nach dem Benutzerimport.

Weitere Informationen zur kennwortlosen Authentifizierung, einschließlich deren Einrichtung und Aufbau des Authentifizierungsablaufs in Ihrer Anwendung, finden Sie unter. Authentifizierung mit Amazon Cognito Cognito-Benutzerpools

Das folgende Verfahren beschreibt die Benutzererfahrung bei einem benutzerdefinierten Anmeldemechanismus mit lokalen Benutzern in einer RESET_REQUIRED nach dem Import einer CSV-Datei. Wenn sich Ihre Benutzer mit verwaltetem Login anmelden, weisen Sie sie an, die Option Passwort vergessen? auszuwählen Option, geben Sie den Code aus ihrer E-Mail oder Textnachricht ein und legen Sie ein Passwort fest.

Benutzer mit Passwort-Hashes importieren

Wenn Sie Benutzer von einem vorhandenen Authentifizierungssystem zu Amazon Cognito migrieren, können Sie ihre Passwort-Hashes zusammen mit ihren Benutzerattributen importieren. Ihre Benutzer können sich dann sofort mit ihren vorhandenen Passwörtern anmelden, ohne dass das Passwort zurückgesetzt werden muss. Nachdem sich Benutzer zum ersten Mal angemeldet haben, migriert Amazon Cognito ihre Anmeldeinformationen transparent in das native Amazon Cognito Cognito-Authentifizierungssystem.

So funktioniert der Passwort-Hash-Import

Mit dem Passwort-Hash-Import können Sie Benutzer migrieren und gleichzeitig ihre Möglichkeit behalten, sich mit ihren vorhandenen Passwörtern anzumelden. Der Importvorgang funktioniert wie folgt:

Unterstützte Algorithmen zum Hashing von Passwörtern

Amazon Cognito unterstützt die folgenden Passwort-Hashing-Algorithmen für den Import:

Wenn Ihr Passwort-Hash Parameterwerte enthält, die die oben aufgeführten Höchstgrenzen überschreiten, schlägt der Import für diesen Benutzer fehl. Überprüfen Sie vor dem Import die Passwort-Hashing-Konfiguration Ihres Quellsystems, um die Kompatibilität sicherzustellen.

Hinzufügen von Passwort-Hashes zu Ihrer CSV-Datei

Wenn Sie die CSV-Vorlage für den Benutzerimport herunterladen, enthält die Vorlage eine password_hash Spalte. Füllen Sie diese Spalte mit den Kennwort-Hashwerten für Benutzer, die Sie importieren möchten, mit ihren vorhandenen Passwörtern aus.

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

Einen Importjob mit Passwort-Hashes erstellen (AWS CLI)

Um Benutzer mit Passwort-Hashes zu importieren, müssen Sie bei der Erstellung des Importjobs den Passwort-Hashing-Algorithmus angeben. Alle Benutzer im Importauftrag müssen denselben Algorithmus verwenden.

Verwenden Sie den folgenden AWS Command Line Interface Befehl, um einen Importjob mit Passwort-Hashes zu erstellen. Der --password-hashing-algorithm Parameter gibt den Algorithmus an, der zum Erstellen der Passwort-Hashes in Ihrer CSV-Datei verwendet wird.

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

BCRYPTErsetzen Sie ihn durch einen der unterstützten Algorithmen:BCRYPT, SCRYPTARGON2ID, oderPBKDF2_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
    }
}

Die Antwort enthält das PasswordHashingAlgorithm Feld, das den von Ihnen angegebenen Algorithmus bestätigt. Laden Sie Ihre CSV-Datei auf die vorsignierte URL hoch und starten Sie den Job wie unter beschriebenHochladen der CSV-Datei.

Benutzererfahrung nach dem Passwort-Hash-Import

Benutzer, die mit Passwort-Hashes importiert wurden, haben folgende Erfahrungen gemacht:

Behebung von Fehlern beim Import von Passwort-Hashs

Wenn ein Passwort-Hash-Import für einen Benutzer fehlschlägt, zeichnet Amazon Cognito den Fehler in Ihren Amazon CloudWatch Logs-Protokollen auf. Zu den häufigsten Fehlerszenarien gehören:

Wenn ein Passwort-Hash-Import für einen Benutzer fehlschlägt, erstellt Amazon Cognito den Benutzer nicht. Andere Benutzer im Importauftrag werden weiterhin verarbeitet. Überprüfen Sie Ihre Amazon CloudWatch Logs-Protokolle, um herauszufinden, welche Benutzer ausgefallen sind und welche Gründe dafür verantwortlich sind.

Sicherheitsüberlegungen beim Import von Passwort-Hashs

Amazon Cognito wendet zusätzliche Sicherheitsmaßnahmen auf importierte Passwort-Hashes an: