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.

O processo de importação define valores para todos os atributos de usuário, exceto password. Não há suporte para a importação de senha, pois as melhores práticas de segurança exigem que as senhas não estejam disponíveis como texto sem formatação, e não oferecemos suporte à importação de hashes. 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.

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 entrar 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.

Criar o perfil do IAM do CloudWatch Logs

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

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.

Baixar 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, em que USER_POOL_ID é 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"

Exemplo de resposta:

{
    "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 a 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.

Como importar 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

Após criar o arquivo CSV, crie um trabalho de importação de usuário executando o seguinte comando da CLI, no qual JOB_NAME é o nome que você está escolhendo para o trabalho, USER_POOL_ID é o ID do grupo de usuários no qual os novos usuários serão adicionados e ROLE_ARN é o ARN do perfil que você recebeu em Criar o perfil do IAM do 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"

O PRE_SIGNED_URL retornado 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 trabalho de importação de usuário, use o comando a seguir, em que USER_POOL_ID é o ID do grupo de usuários e JOB_ID é o job ID retornado quando você criou o trabalho de importação de usuário.

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

Na saída de exemplo anterior, o PRE_SIGNED_URL é o URL no qual você fez upload do arquivo CSV. O ROLE_ARN é o ARN de função do CloudWatch Logs que você recebeu quando criou 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 string PAGINATION_TOKEN após o segundo trabalho indica que há outros resultados para esse comando de listagem. 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
    }
}

Como visualizar os resultados de importação de grupo de usuários no console do CloudWatch

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

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

O status dos usuários importados com êxito é 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 suas 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 obter mais informações 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?, forneça o código de seu e-mail ou mensagem de texto e defina uma senha.