Como importar usuários para grupos de usuários com base em um arquivo CSV

Quando você tem um repositório de identidade externo e tem tempo para preparar seu grupo de usuários para novos usuários locais, a importação em massa de usuários de um arquivo de valores separados por vírgula (CSV) pode ser uma opção simplificada e econômica para a migração para um grupo de usuários do Amazon Cognito. A importação de um arquivo CSV é um processo de baixar e preencher um arquivo de modelo e, em seguida, entregar o arquivo ao seu grupo de usuários em um trabalho de importação. Você pode usar uma importação de CSV para criar rapidamente usuários de teste. Você também pode preencher programaticamente o arquivo com solicitações da API de leitura para seu repositório de identidade externo e, em seguida, analisar seus detalhes e atributos em operações de gravação no arquivo.

Por padrão, o processo de importação define valores para todos os atributos do usuário, exceto a senha. Isso significa que os usuários devem alterar suas senhas na primeira vez em que fizerem login. Seus usuários estão em estado RESET_REQUIRED quando são importados por esse método.

Como alternativa, você pode importar usuários com seus hashes de senha existentes. Quando você especifica um algoritmo de hash de senha durante a criação do trabalho de importação e inclui hashes de senha em seu arquivo CSV, o Amazon Cognito importa os usuários com suas senhas existentes. Esses usuários são criados com um CONFIRMED status e podem entrar imediatamente sem redefinir suas senhas. Para obter mais informações, consulte Importação de usuários com hashes de senha.

A maneira mais simples de importar usuários de um CSV é ativar o login sem senha no grupo de usuários. Com atributos de endereço de e-mail e número de telefone e a configuração correta do grupo de usuários, os usuários podem fazer login com senhas de uso único (OTPs) enviadas por e-mail ou SMS imediatamente após a conclusão do trabalho de importação. Para obter mais informações, consulte Solicitação de redefinição de senha aos usuários importados.

Também é possível definir as senhas dos usuários com uma solicitação de API AdminSetUserPassword que define o parâmetro Permanent como true. A importação de CSV não contribui para a cobrança de usuários ativos mensais (MAUs) em seu grupo de usuários. No entanto, as operações de redefinição de senha geram MAUs. Para gerenciar os custos ao importar um grande número de usuários com senhas que podem não estar imediatamente ativos, configure a aplicação para solicitar aos usuários uma nova senha quando eles fizerem login e receberem o desafio RESET_REQUIRED.

Criação da função do CloudWatch Logs IAM

Se você estiver usando a CLI ou a API do Amazon Cognito, precisará criar uma função do IAM. CloudWatch O procedimento a seguir descreve como criar uma função do IAM que o Amazon Cognito pode usar para gravar os resultados do seu trabalho de importação no Logs. CloudWatch

Criar o arquivo CSV de importação do usuário

Antes de poder importar os usuários existentes para o grupo de usuários, é necessário criar um arquivo de valores separados por vírgula (CSV) que contenha os usuários que você deseja importar e os atributos deles. No grupo de usuários, é possível recuperar um arquivo de importação de usuários com cabeçalhos que refletem o esquema de atributos do grupo de usuários. Depois, você pode inserir informações do usuário que correspondam aos requisitos de formatação em Formatar o arquivo CSV.

Baixar o cabeçalho do arquivo CSV (console)

Use o procedimento a seguir para baixar o arquivo de cabeçalho CSV.

Baixando o cabeçalho do arquivo CSV (AWS CLI)

Para obter uma lista dos cabeçalhos corretos, no menu Usuários, em Importar usuários, selecione Criar trabalho de importação. Na caixa de diálogo a seguir, selecione o link template.csv para baixar um arquivo de modelo com os atributos do grupo de usuários.

Você também pode executar o seguinte comando da CLI, onde USER_POOL_ID está o identificador do grupo de usuários para o qual você importará usuários:

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

Resposta de exemplo:

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

Formatar o arquivo CSV

O arquivo de cabeçalho CSV de importação de usuários baixado se parece com a string a seguir. Ele também inclui os atributos personalizados que você adicionou ao grupo de usuários.

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

Edite o arquivo CSV para que ele inclua esse cabeçalho e os valores de atributo dos usuários e seja formatado de acordo com as seguintes regras:

A lista a seguir é um exemplo de arquivo de importação CSV para um grupo de usuários sem atributos personalizados. Seu esquema do grupo de usuários pode ser diferente deste exemplo. Nesse caso, você deve fornecer valores de teste no modelo CSV baixado do seu grupo de usuários.

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

Como criar e executar o trabalho de importação do grupo de usuários do Amazon Cognito

Esta seção descreve como criar e executar o trabalho de importação do grupo de usuários usando o console do Amazon Cognito e o AWS Command Line Interface ()AWS CLI.

Importar usuários de um arquivo CSV (console)

O procedimento a seguir descreve como importar os usuários do arquivo CSV.

Importação de usuários (AWS CLI)

Os comandos da CLI a seguir estão disponíveis para importar usuários para um grupo de usuários:

Para obter a lista de opções de linha de comando desses comandos, use a opção de linha de comando help. Por exemplo:

aws cognito-idp get-csv-header help

Como criar um trabalho de importação de usuário

Depois de criar seu arquivo CSV, crie um trabalho de importação de usuários executando o seguinte comando da CLI, JOB_NAME onde está o nome que você está escolhendo para o trabalhoUSER_POOL_ID, o ID do grupo de usuários ao qual os novos usuários serão adicionados ROLE_ARN e o ARN da função que você recebeu em: Criação da função do 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"

O PRE_SIGNED_URL retorno na resposta é válido por 15 minutos. Após esse tempo, ele expirará e você deverá criar um novo trabalho de importação de usuário para obter um novo 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
    }
}

Valores de status de um trabalho de importação de usuário

Nas respostas aos comandos de importação de usuário, você verá um dos seguintes valores de Status:

Fazer upload do arquivo CSV

Use o comando curl a seguir para fazer upload do arquivo CSV que contém os dados do usuário no URL pré-assinado que você obteve da resposta do comando create-user-import-job.

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

Na saída deste comando, procure a frase "We are completely uploaded and fine". Essa frase indica que o upload do arquivo foi realizado com êxito. Os grupos de usuários não mantêm as informações nos arquivos de importação depois que você executa os trabalhos de importação. Depois que eles forem concluídos ou expirarem, o Amazon Cognito excluirá seu arquivo CSV carregado.

Como descrever um trabalho de importação de usuário

Para obter uma descrição do seu trabalho de importação de usuários, use o comando a seguir, onde USER_POOL_ID está o ID do grupo de usuários e JOB_ID o ID do trabalho que foi retornado quando você criou o trabalho de importação de usuários.

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

No exemplo de saída anterior, PRE_SIGNED_URL é o URL para o qual você carregou o arquivo CSV. Esse ROLE_ARN é o ARN da função de CloudWatch registros que você recebeu ao criar a função.

Como listar os trabalhos de importação de usuário

Para listar os trabalhos de importação de usuário, use o comando a seguir:

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

Os trabalhos são listados em ordem cronológica, do último criado ao primeiro. A PAGINATION_TOKEN string após o segundo trabalho indica que há resultados adicionais para esse comando de lista. Para listar os resultados adicionais, use a opção --pagination-token opção da seguinte forma:

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

Como iniciar um trabalho de importação de usuário

Para iniciar um trabalho de importação de usuário, use o seguinte comando:

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

Somente um trabalho de importação pode ser ativado por vez por conta.

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

Como interromper um trabalho de importação de usuário

Para interromper um trabalho de importação de usuário em andamento, use o comando a seguir. Após interromper o trabalho, ele não poderá ser reiniciado.

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

Visualizando os resultados da importação do grupo de usuários no CloudWatch console

Você pode ver os resultados do seu trabalho de importação no CloudWatch console da Amazon.

Como visualizar os resultados

As etapas a seguir descrevem como exibir os resultados de importação de grupo de usuários.

Como interpretar os resultados

Usuários importados com sucesso têm seu status definido como "PasswordReset”.

Nos casos a seguir, o usuário não será importado, mas o trabalho de importação continuará:

Nos casos a seguir, o trabalho de importação apresentará falha:

Solicitação de redefinição de senha aos usuários importados

Se o grupo de usuários oferecer somente login baseado em senha, os usuários deverão redefinir as senhas após a importação. Na primeira vez que fizerem login, poderão inserir qualquer senha. O Amazon Cognito solicita que eles insiram uma nova senha na resposta da API à solicitação de login da sua aplicação.

Se o grupo de usuários tiver fatores de autenticação sem senha, o Amazon Cognito os usará como padrão para usuários importados. Eles não serão solicitados a criar uma nova senha e poderão fazer login imediatamente com uma OTP enviada por e-mail ou SMS, sem senha. Você também poderá solicitar que os usuários definam uma senha para poderem usar outros métodos de login, como nome de usuário e senha ou chave de acesso. As condições a seguir se aplicam ao login sem senha após a importação do usuário.

Para saber mais sobre a autenticação sem senha, incluindo como configurá-la e como criar o fluxo de autenticação em sua aplicação, consulte Autenticação com grupos de usuários do Amazon Cognito.

O procedimento a seguir descreve a experiência do usuário em um mecanismo de login personalizado com usuários locais em um RESET_REQUIRED após a importação de um arquivo CSV. Se seus usuários fizerem login com login gerenciado, instrua-os a selecionar a opção Esqueceu a senha?, informe o código deles por e-mail ou mensagem de texto e defina uma senha.

Importação de usuários com hashes de senha

Ao migrar usuários de um sistema de autenticação existente para o Amazon Cognito, você pode importar seus hashes de senha junto com seus atributos de usuário. Seus usuários podem então entrar imediatamente com suas senhas existentes, sem redefinição de senha. Depois que os usuários se conectam pela primeira vez, o Amazon Cognito migra de forma transparente suas credenciais para o sistema de autenticação nativo do Amazon Cognito.

Como funciona a importação de hash de senha

Com a importação de hash de senha, você pode migrar usuários enquanto preserva a capacidade deles de fazer login com as senhas existentes. O processo de importação funciona da seguinte forma:

Algoritmos de hashing de senha compatíveis

O Amazon Cognito oferece suporte aos seguintes algoritmos de hash de senha para importação:

Se o hash de sua senha tiver valores de parâmetros que excedam os limites máximos listados acima, a importação falhará para esse usuário. Revise a configuração de hash de senha do seu sistema de origem antes de importar para garantir a compatibilidade.

Adicionar hashes de senha ao seu arquivo CSV

Quando você baixa o modelo CSV para importação do usuário, o modelo inclui uma password_hash coluna. Preencha essa coluna com os valores de hash da senha dos usuários que você deseja importar com as senhas existentes.

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

Criação de um trabalho de importação com hashes de senha (AWS CLI)

Para importar usuários com hashes de senha, você deve especificar o algoritmo de hash de senha ao criar o trabalho de importação. Todos os usuários na tarefa de importação devem usar o mesmo algoritmo.

Use o AWS Command Line Interface comando a seguir para criar um trabalho de importação com hashes de senha. O --password-hashing-algorithm parâmetro especifica o algoritmo usado para criar os hashes de senha no seu arquivo 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

BCRYPTSubstitua por um dos algoritmos compatíveis:BCRYPT,SCRYPT,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
    }
}

A resposta inclui o PasswordHashingAlgorithm campo confirmando o algoritmo que você especificou. Faça o upload do arquivo CSV para o URL pré-assinado e inicie o trabalho conforme descrito em. Fazer upload do arquivo CSV

Experiência do usuário após a importação de hash de senha

Os usuários importados com hashes de senha têm a seguinte experiência:

Solução de problemas de erros de importação de hash de senha

Se uma importação de hash de senha falhar para um usuário, o Amazon Cognito registrará a falha nos seus registros do CloudWatch Amazon Logs. Os cenários de erro comuns incluem:

Quando uma importação de hash de senha falha para um usuário, o Amazon Cognito não cria o usuário. Outros usuários na tarefa de importação continuam sendo processados. Revise seus CloudWatch registros do Amazon Logs para identificar quais usuários falharam e o motivo de cada falha.

Considerações de segurança para importação de hash de senha

O Amazon Cognito aplica medidas de segurança adicionais aos hashes de senha importados: