Importation d'utilisateurs dans des groupes d'utilisateurs depuis un fichier CSV

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 CSV (valeurs séparées par des virgules) 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 fichier CSV 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 importation CSV pour créer rapidement des utilisateurs de test. Vous pouvez également remplir le fichier par programmation avec des requêtes d'API 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.

Par défaut, le processus d'importation définit les valeurs de tous les attributs utilisateur à l'exception du mot de passe. 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 également importer des utilisateurs avec leur hachage de mot de passe existant. Lorsque vous spécifiez un algorithme de hachage de mot de passe lors de la création d'une tâche d'importation et que vous incluez des hachages de mots de passe dans votre fichier CSV, Amazon Cognito importe les utilisateurs avec leurs mots de passe existants. Ces utilisateurs sont dotés d'un CONFIRMED statut et peuvent se connecter immédiatement sans avoir à réinitialiser leur mot de passe. Pour de plus amples informations, veuillez consulter Importation d'utilisateurs avec des hachages de mots de passe.

La méthode la plus simple pour importer des utilisateurs depuis un fichier CSV consiste à activer la connexion sans mot de passe dans votre groupe d'utilisateurs. Grâce aux attributs d'adresse e-mail et de numéro de téléphone et à la bonne configuration du pool d'utilisateurs, les utilisateurs peuvent se connecter à l'aide de mots de passe à usage unique (OTP) par e-mail ou SMS immédiatement après la fin de votre tâche d'importation. Pour de plus amples informations, veuillez consulter Obligation pour les utilisateurs importés de réinitialiser leur mot de passe.

Vous pouvez également définir les mots de passe de vos utilisateurs à l'aide d'une demande d'AdminSetUserPasswordAPI dont le Permanent paramètre est défini surtrue. L'importation au format CSV ne contribue pas au nombre d'utilisateurs actifs (MAU) mensuels facturés dans votre groupe d'utilisateurs. Cependant, les opérations de réinitialisation du mot de passe génèrent des MAU. Pour gérer les coûts lorsque vous importez un grand nombre d'utilisateurs dotés d'un mot de passe qui ne sont peut-être pas immédiatement actifs, configurez votre application pour demander aux utilisateurs un nouveau mot de passe lorsqu'ils se connectent et reçoivent le RESET_REQUIRED défi.

Création du rôle CloudWatch Logs IAM

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

Création du fichier CSV d'importation d'utilisateurs

Avant de pouvoir importer des utilisateurs existants dans votre groupe d'utilisateurs, vous devez d'abord créer un fichier CSV (valeurs séparées par des virgules) contenant les utilisateurs que vous souhaitez importer ainsi que 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 Mise en forme du fichier CSV.

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

Utilisez la procédure suivante pour télécharger le fichier d'en-tête CSV.

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

Pour obtenir la liste des en-têtes corrects, dans le menu Utilisateurs, sous Importer des utilisateurs, sélectionnez Créer une tâche d'importation. Dans la boîte de dialogue qui suit, sélectionnez le template.csv lien pour télécharger un fichier modèle contenant les attributs de votre groupe d'utilisateurs.

Vous pouvez également exécuter la commande CLI 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"
}

Mise en forme du fichier CSV

Une fois téléchargé, le fichier d'en-tête CSV d'importation d'utilisateurs 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 fichier CSV de telle sorte qu'il contienne cet en-tête et les valeurs d'attribut pour vos utilisateurs et qu'il soit mis en forme selon les règles suivantes :

La liste suivante est un exemple de fichier d'importation CSV 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 modèle CSV que vous téléchargez à partir de 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 à partir d'un fichier CSV (console)

La procédure suivante montre comment importer les utilisateurs à partir du fichier CSV.

Importation d'utilisateurs (AWS CLI)

Les commandes de CLI suivantes sont disponibles pour l'importation des utilisateurs dans un pool 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 fichier CSV, créez une tâche d'importation d'utilisateurs en exécutant la commande CLI suivante, où JOB_NAME figurent le nom que vous choisissez pour la tâche, USER_POOL_ID l'ID du groupe d'utilisateurs dans lequel les nouveaux utilisateurs seront ajoutés et ROLE_ARN l'ARN du rôle dans lequel vous avez reçu Création du rôle 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"

La PRE_SIGNED_URL valeur renvoyée dans la réponse est valide pendant 15 minutes. Au-delà de ce délai, la valeur expire et vous devez créer une nouvelle tâche d'importation des utilisateurs pour obtenir une nouvelle 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
    }
}

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 commande curl suivante pour charger le fichier CSV contenant vos données utilisateur sur l'URL présignée que vous avez obtenue de la réponse de la commande create-user-import-job.

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. Vos groupes d'utilisateurs ne conservent pas les informations contenues dans vos fichiers d'importation une fois que vous avez exécuté vos tâches d'importation. Une fois qu'ils sont terminés ou expirent, Amazon Cognito supprime le fichier CSV que vous avez chargé.

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

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

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 il s'agit de l'URL vers laquelle vous avez chargé le fichier CSV. ROLE_ARNIl s'agit de l'ARN du rôle CloudWatch Logs que vous avez reçu lors de la création du rôle.

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. La PAGINATION_TOKEN chaîne située après la deuxième tâche 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 d'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

Si votre groupe d'utilisateurs propose uniquement une connexion par mot de passe, les utilisateurs doivent réinitialiser leur mot de passe après son importation. La première fois qu'ils se connectent, ils peuvent saisir n'importe quel mot de passe. Amazon Cognito les invite à saisir un nouveau mot de passe dans la réponse de l'API à la demande de connexion de votre application.

Si votre groupe d'utilisateurs utilise des facteurs d'authentification sans mot de passe, Amazon Cognito utilise par défaut ceux des utilisateurs importés. Ils ne sont pas invités à saisir un nouveau mot de passe et peuvent se connecter immédiatement à l'aide d'un e-mail ou d'un SMS OTP sans mot de passe. Vous pouvez également demander aux utilisateurs de définir un mot de passe afin qu'ils puissent utiliser d'autres méthodes de connexion, telles que le nom d'utilisateur-mot de passe et le mot de passe. Les conditions suivantes s'appliquent à la connexion sans mot de passe après l'importation d'un utilisateur.

Pour plus d'informations sur l'authentification sans mot de passe, notamment sur la façon de la configurer et de créer le flux d'authentification dans votre application, consultez. Authentification auprès des groupes d'utilisateurs Amazon Cognito

La procédure suivante décrit l'expérience utilisateur dans un mécanisme de connexion personnalisé avec des utilisateurs locaux RESET_REQUIRED après l'importation d'un fichier CSV. Si vos utilisateurs se connectent avec un identifiant géré, demandez-leur de sélectionner le mot de passe oublié ? option, fournissez le code de leur e-mail ou de leur message texte et définissez un mot de passe.

Importation d'utilisateurs avec des hachages de mots de passe

Lorsque vous migrez des utilisateurs d'un système d'authentification existant vers Amazon Cognito, vous pouvez importer le hachage de leur mot de passe ainsi que leurs attributs utilisateur. Vos utilisateurs peuvent alors se connecter immédiatement avec leurs mots de passe existants, sans avoir à réinitialiser leur mot de passe. Une fois que les utilisateurs se connectent pour la première fois, Amazon Cognito migre leurs informations d'identification de manière transparente vers le système d'authentification Amazon Cognito natif.

Comment fonctionne l'importation du hachage des mots de passe

Grâce à l'importation par hachage des mots de passe, vous pouvez migrer les utilisateurs tout en préservant leur capacité à se connecter avec leurs mots de passe existants. Le processus d'importation fonctionne comme suit :

algorithmes de hachage de mots de passe pris en charge

Amazon Cognito prend en charge les algorithmes de hachage de mots de passe suivants pour l'importation :

Si le hachage de votre mot de passe comporte des valeurs de paramètres qui dépassent les limites maximales indiquées ci-dessus, l'importation échoue pour cet utilisateur. Vérifiez la configuration du hachage des mots de passe de votre système source avant de procéder à l'importation afin de garantir la compatibilité.

Ajouter des hachages de mots de passe à votre fichier CSV

Lorsque vous téléchargez le modèle CSV pour l'importation par l'utilisateur, le modèle inclut une password_hash colonne. Remplissez cette colonne avec les valeurs de hachage des mots de passe des utilisateurs que vous souhaitez importer avec leurs mots de passe existants.

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

Création d'une tâche d'importation avec des hachages de mots de passe (AWS CLI)

Pour importer des utilisateurs à l'aide d'un hachage de mot de passe, vous devez spécifier l'algorithme de hachage du mot de passe lors de la création de la tâche d'importation. Tous les utilisateurs participant à la tâche d'importation doivent utiliser le même algorithme.

Utilisez la AWS Command Line Interface commande suivante pour créer une tâche d'importation avec des hachages de mots de passe. Le --password-hashing-algorithm paramètre indique l'algorithme utilisé pour créer les hachages de mots de passe dans votre fichier 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

BCRYPTRemplacez-le par l'un des algorithmes pris en charge : BCRYPTSCRYPT,ARGON2ID, ouPBKDF2_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 réponse inclut le PasswordHashingAlgorithm champ confirmant l'algorithme que vous avez spécifié. Téléchargez votre fichier CSV sur l'URL présignée et lancez la tâche comme décrit dansChargement du fichier CSV.

Expérience utilisateur après l'importation du hachage du mot de passe

Les utilisateurs importés avec des mots de passe hachés ont l'expérience suivante :

Résolution des erreurs d'importation par hachage des mots de passe

Si l'importation du hachage du mot de passe échoue pour un utilisateur, Amazon Cognito enregistre l'échec dans vos journaux CloudWatch Amazon Logs. Les scénarios d'erreur courants incluent :

Lorsqu'une importation par hachage de mot de passe échoue pour un utilisateur, Amazon Cognito ne crée pas l'utilisateur. Les autres utilisateurs participant à la tâche d'importation continuent d'être traités. Consultez vos CloudWatch journaux Amazon Logs pour identifier les utilisateurs qui ont échoué et la raison de chaque échec.

Considérations de sécurité pour l'importation du hachage des mots de passe

Amazon Cognito applique des mesures de sécurité supplémentaires aux hachages de mots de passe importés :