Benutzer aus einer CSV Datei in Benutzerpools importieren

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 Datei mit kommagetrennten Werten (CSV) 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 und die Datei anschließend in einem Importjob an Ihren Benutzerpool übergeben wird. 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.

Sie können die Passwörter Ihrer Benutzer mit einem festlegen AdminSetUserPasswordAPIAnfrage, die den Permanent Parameter auf setzttrue. CSVDer Import trägt nicht zu den monatlich in Rechnung gestellten aktiven Benutzern (MAUs) in Ihrem Benutzerpool bei. Bei Vorgängen zum Zurücksetzen von Kennwörtern wird jedoch etwas generiert. MAUs Um die Kosten zu senken, wenn Sie eine große Anzahl von Benutzern 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 Rolle „ CloudWatch IAMLogs“ erstellen

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

Erstellen der CSV Benutzerimportdatei

Bevor Sie Ihre vorhandenen Benutzer in Ihren Benutzerpool importieren können, müssen Sie eine Datei mit kommagetrennten Werten (CSV) erstellen, die die Benutzer, die Sie importieren möchten, und deren 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.

Der CSV Datei-Header wird heruntergeladen (Konsole)

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

Der CSV Datei-Header wird heruntergeladen (AWS CLI)

Um eine Liste der richtigen Header zu erhalten, führen Sie den folgenden CLI Befehl aus, wobei USER_POOL_ID ist die Benutzerpool-ID für den Benutzerpool, in 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 Benutzer-Import-Header-Datei 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 so, dass 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.

Benutzer aus einer CSV Datei (Konsole) importieren

Das folgende Verfahren beschreibt, wie Sie die 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, wobei JOB_NAME ist der Name, den Sie für den Job wählen, USER_POOL_ID ist die Benutzerpool-ID für den Benutzerpool, zu dem die neuen Benutzer hinzugefügt werden, und ROLE_ARN ist die Rolle, die ARN Sie erhalten haben inDie Rolle „ CloudWatch IAMLogs“ 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"

Das Tool PRE_SIGNED_URL Die in der Antwort zurückgegebene Antwort ist 15 Minuten gültig. Nach Ablauf dieser Zeit läuft er ab und Sie müssen einen neuen Benutzerimportauftrag erstellen, um einen neuen zu erhaltenURL.

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

Die CSV Datei wird hochgeladen

Verwenden Sie den folgenden curl Befehl, um die CSV Datei mit Ihren Benutzerdaten in die vorsignierte Datei hochzuladenURL, die Sie durch die Antwort auf den Befehl erhalten haben. create-user-import-job

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.

Beschreiben eines Benutzer-Importauftrags

Um eine Beschreibung Ihres Benutzerimport-Jobs zu erhalten, verwenden Sie den folgenden Befehl, wobei USER_POOL_ID ist Ihre Benutzerpool-ID und JOB_ID ist die Job-ID, die zurückgegeben wurde, als Sie den Benutzerimportjob erstellt haben.

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 dasURL, in das Sie die CSV Datei hochgeladen haben. Das Tool ROLE_ARN ist die CloudWatch Logs-RolleARN, die 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. Das Tool PAGINATION_TOKEN Die 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

Bei erfolgreich importierten Benutzern ist der Status 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

Jeder importierte Benutzer, der sich zum ersten Mal anmeldet und ein Passwort eingibt, wird aufgefordert, ein neues Passwort einzugeben. Das folgende Verfahren beschreibt die Benutzererfahrung in einer benutzerdefinierten App mit lokalen Benutzern, nachdem Sie eine CSV Datei importiert haben. Wenn sich Ihre Benutzer bei der gehosteten Benutzeroberfläche anmelden, fordert sie Amazon Cognito bei der ersten Anmeldung auf, ein neues Passwort festzulegen.