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.

Der Importprozess legt Werte für alle Benutzerattribute fest, mit Ausnahme von password. Der Import des Passworts wird nicht unterstützt, da bewährte Methoden für die Sicherheit verlangen, dass Kennwörter nicht als Klartext verfügbar sind, und wir den Import von Hash-Werten nicht unterstützen. 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 werden.

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-Einmalkennwö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 einem festlegen AdminSetUserPasswordAPI-Anfrage, die den Permanent Parameter auf setzttrue. Der CSV-Import trägt nicht zur Abrechnung der monatlich aktiven Nutzer (MAUs) in Ihrem Benutzerpool bei. Bei Vorgängen zum Zurücksetzen von Passwörtern wird jedoch etwas generiert. MAUs Um die Kosten zu senken, 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 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.

Herunterladen des CSV-Datei-Headers (AWS CLI)

Um eine Liste der richtigen Header zu erhalten, führen Sie den folgenden CLI-Befehl aus. Dabei USER_POOL_ID handelt es sich um die Benutzerpool-ID für den Benutzerpool, in den Sie Benutzer importieren möchten:

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.

Importieren von Benutzern (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.