Importation d'utilisateurs dans des groupes d'utilisateurs à partir d'un CSV fichier

Lorsque vous disposez d'un magasin d'identités externe et que vous avez le temps de préparer votre groupe d'utilisateurs pour les nouveaux utilisateurs locaux, l'importation groupée d'utilisateurs à partir d'un fichier de valeurs séparées par des virgules (CSV) peut s'avérer une option peu coûteuse et peu coûteuse pour une migration vers un groupe d'utilisateurs Amazon Cognito. Une importation de CSV fichier consiste à télécharger et à remplir un fichier modèle, puis à le transmettre à votre groupe d'utilisateurs dans le cadre d'une tâche d'importation. Vous pouvez utiliser une CSV importation pour créer rapidement des utilisateurs de test. Vous pouvez également remplir le fichier par programmation avec des API demandes de lecture adressées à votre banque d'identités externe, puis analyser leurs détails et leurs attributs dans le cadre d'opérations d'écriture dans le fichier.

Le processus d'importation définit les valeurs de tous les attributs utilisateur, sauf password (mot de passe). L'importation du mot de passe n'est pas prise en charge, car les bonnes pratiques de sécurité nécessitent que les mots de passe ne soient pas disponibles sous forme de texte brut, et nous ne prenons pas en charge l'importation des hachages. Cela signifie que vos utilisateurs doivent changer leur mot de passe la première fois qu'ils se connectent. Vos utilisateurs sont dans un RESET_REQUIRED état lorsqu'ils sont importés à l'aide de cette méthode.

Vous pouvez définir les mots de passe de vos utilisateurs à l'aide d'un AdminSetUserPasswordAPIdemande qui définit le Permanent paramètre surtrue. CSVl'importation ne contribue pas au nombre d'utilisateurs actifs mensuels facturés (MAUs) de votre groupe d'utilisateurs. Cependant, des opérations de réinitialisation du mot de passe sont générées. MAUs Pour gérer les coûts liés à l'importation d'un grand nombre d'utilisateurs susceptibles de ne pas être immédiatement actifs, configurez votre application pour qu'elle invite les utilisateurs à saisir un nouveau mot de passe lorsqu'ils se connectent et reçoivent le RESET_REQUIRED défi.

Création du IAM rôle CloudWatch Logs

Si vous utilisez Amazon Cognito CLI ouAPI, vous devez créer un CloudWatch IAM rôle. La procédure suivante explique comment créer un IAM rôle qu'Amazon Cognito peut utiliser pour écrire les résultats de votre tâche d'importation dans Logs. CloudWatch

Création du CSV fichier d'importation utilisateur

Avant de pouvoir importer vos utilisateurs existants dans votre groupe d'utilisateurs, vous devez créer un fichier de valeurs séparées par des virgules (CSV) contenant les utilisateurs que vous souhaitez importer et leurs attributs. À partir de votre groupe d'utilisateurs, vous pouvez extraire un fichier d'importation d'utilisateurs dont les en-têtes reflètent le schéma d'attributs de votre groupe d'utilisateurs. Vous pouvez ensuite insérer les informations utilisateur qui répondent aux exigences de mise en forme décrites dans Formatage du CSV fichier.

Téléchargement de l'en-tête CSV du fichier (console)

Pour télécharger le fichier d'CSVen-tête, procédez comme suit.

Téléchargement de l'en-tête CSV du fichier (AWS CLI)

Pour obtenir la liste des en-têtes corrects, exécutez la CLI commande suivante, où USER_POOL_ID est l'identifiant du groupe d'utilisateurs dans lequel vous allez importer des utilisateurs :

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

Exemple de réponse :

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

Formatage du CSV fichier

Le fichier d'CSVen-tête d'importation utilisateur téléchargé ressemble à la chaîne suivante. Il comporte également les attributs personnalisés que vous avez éventuellement ajoutés à votre groupe d'utilisateurs.

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

Modifiez votre CSV fichier afin qu'il inclue cet en-tête et les valeurs d'attribut pour vos utilisateurs, et qu'il soit formaté conformément aux règles suivantes :

La liste suivante est un exemple de fichier CSV d'importation pour un groupe d'utilisateurs sans attributs personnalisés. Le schéma de votre groupe d'utilisateurs peut être différent par rapport à cet exemple. Dans ce cas, vous devez fournir des valeurs de test dans le CSV modèle que vous téléchargez depuis votre groupe d'utilisateurs.

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

Création et exécution de la tâche d'importation de groupe d'utilisateurs Amazon Cognito

Cette section explique comment créer et exécuter la tâche d'importation du groupe d'utilisateurs à l'aide de la console Amazon Cognito et du AWS Command Line Interface ()AWS CLI.

Importation d'utilisateurs depuis un CSV fichier (console)

La procédure suivante décrit comment importer les utilisateurs depuis le CSV fichier.

Importation d'utilisateurs (AWS CLI)

Les CLI commandes suivantes sont disponibles pour importer des utilisateurs dans un groupe d'utilisateurs :

Pour obtenir la liste des options de ligne de commande pour ces commandes, utilisez l'option de ligne de commande help. Par exemple :

aws cognito-idp get-csv-header help

Création d'une tâche d'importation d'utilisateurs

Après avoir créé votre CSV fichier, créez une tâche d'importation utilisateur en exécutant la CLI commande suivante, où JOB_NAME est le nom que vous choisissez pour le poste, USER_POOL_ID est l'ID du groupe d'utilisateurs dans lequel les nouveaux utilisateurs seront ajoutés, et ROLE_ARN est le rôle ARN que vous avez reçu dans Création du IAM rôle CloudWatch Logs :

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

Le PRE_SIGNED_URL renvoyé dans la réponse est valide pendant 15 minutes. Passé ce délai, il expirera et vous devrez créer une nouvelle tâche d'importation utilisateur pour en obtenir une nouvelleURL.

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

Valeurs d'état pour une tâche d'importation d'utilisateurs

Dans les réponses à vos commandes d'importation d'utilisateurs, vous verrez l'une des valeurs Status suivantes :

Chargement du fichier CSV

Utilisez la curl commande suivante pour télécharger le CSV fichier contenant vos données utilisateur sur le fichier présigné URL que vous avez obtenu à partir de la réponse à la create-user-import-job commande.

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

Dans la sortie de cette commande, recherchez l'expression "We are completely uploaded and fine". Cette expression indique que le fichier a été téléchargé avec succès.

Description d'une tâche d'importation d'utilisateurs

Pour obtenir une description de votre tâche d'importation utilisateur, utilisez la commande suivante, où USER_POOL_ID est l'ID de votre groupe d'utilisateurs, et JOB_ID est l'ID de tâche qui a été renvoyé lorsque vous avez créé la tâche d'importation utilisateur.

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

Dans l'exemple de sortie précédent, PRE_SIGNED_URL est URL celui dans lequel vous avez chargé le CSV fichier. Le ROLE_ARN est le rôle CloudWatch Logs ARN que vous avez reçu lors de sa création.

Affichage des tâches d'importation d'utilisateurs

Pour afficher les tâches d'importation d'utilisateurs, utilisez la commande suivante :

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

Les tâches sont affichées par ordre chronologique, depuis la dernière créée jusqu'à la première créée. Le PAGINATION_TOKEN Une chaîne après le deuxième travail indique que cette commande de liste contient des résultats supplémentaires. Pour afficher les résultats supplémentaires, utilisez l'option --pagination-token comme suit :

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

Démarrage d'une tâche d'importation d'utilisateurs

Pour démarrer une tâche d'importation d'utilisateurs, utilisez la commande suivante :

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

Une seule tâche d'importation peut être active à la fois par compte.

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

Arrêt d'une tâche d'importation d'utilisateurs

Pour arrêter une tâche d'importation d'utilisateur alors qu'elle est en cours, utilisez la commande suivante. Une fois que vous avez arrêté la tâche, elle ne peut pas être redémarrée.

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

Affichage des résultats de l'importation du groupe d'utilisateurs dans la CloudWatch console

Vous pouvez consulter les résultats de votre tâche d'importation dans la CloudWatch console Amazon.

Affichage des résultats

Les étapes suivantes expliquent comment afficher les résultats de l'importation du pool d'utilisateurs.

Interprétation des résultats

Le statut des utilisateurs importés avec succès est défini sur « PasswordReset ».

Dans les cas suivants, l'utilisateur n'est pas importé, mais la tâche d'importation se poursuit :

Dans les cas suivants, la tâche d'importation échoue :

Obligation pour les utilisateurs importés de réinitialiser leur mot de passe

Chaque utilisateur importé doit saisir un nouveau mot de passe lors de sa première connexion. La procédure suivante décrit l'expérience utilisateur dans une application personnalisée avec des utilisateurs locaux après l'importation d'un CSV fichier. Si vos utilisateurs se connectent à l'aide de l'interface utilisateur hébergée, Amazon Cognito les invite à définir un nouveau mot de passe lors de leur première connexion.