Importação de usuários para grupos de usuários a partir de um arquivo CSV

Quando você tem um armazenamento 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 econômica e econômica para uma migração para um grupo de usuários do Amazon Cognito. A importação de CSV arquivo é 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 CSV importação para criar rapidamente usuários de teste. Você também pode preencher programaticamente o arquivo com API solicitações 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 um RESET_REQUIRED estado quando são importados usando esse método.

Você pode definir as senhas de seus usuários com um AdminSetUserPasswordAPIsolicitação que define o Permanent parâmetro comotrue. CSVa importação não contribui para a cobrança mensal de usuários ativos (MAUs) em seu grupo de usuários. No entanto, as operações de redefinição de senha são geradas. MAUs Para gerenciar os custos ao importar um grande número de usuários que podem não estar imediatamente ativos, configure seu aplicativo para solicitar aos usuários uma nova senha quando eles entrarem e receberem o RESET_REQUIRED desafio.

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

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

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

Antes de importar seus usuários existentes para seu grupo de usuários, você deve criar um arquivo de valores (CSV) separados por vírgula que contenha os usuários que você deseja importar e seus atributos. 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 Formatando o arquivo CSV.

Baixando o cabeçalho CSV do arquivo (console)

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

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

Para obter uma lista dos cabeçalhos corretos, execute o seguinte CLI comando, onde 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"

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

Formatando o arquivo CSV

O arquivo de CSV cabeçalho de importação do usuário baixado se parece com a sequência de caracteres 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 seu CSV arquivo para que ele inclua esse cabeçalho e os valores dos atributos para seus usuários e seja formatado de acordo com as seguintes regras:

A lista a seguir é um exemplo de arquivo de CSV importação 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 CSV modelo que você baixa 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.

Importação de usuários de um CSV arquivo (console)

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

Como importar usuários (AWS CLI)

Os CLI comandos 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 CSV arquivo, crie um trabalho de importação de usuários executando o CLI comando a seguir, onde JOB_NAME é o nome que você está escolhendo para o trabalho, USER_POOL_ID é a ID do grupo de usuários ao qual os novos usuários serão adicionados, e ROLE_ARN é a função ARN que você recebeu emCriação da IAM função 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"

A ferramenta PRE_SIGNED_URL retornado na resposta é válido por 15 minutos. Após esse período, ele expirará e você deverá criar um novo trabalho de importação de usuários para obter um novoURL.

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

Fazendo o upload do arquivo CSV

Use o curl comando a seguir para carregar o CSV arquivo contendo os dados do usuário para o arquivo preassinado URL que você obteve da resposta do create-user-import-job comando.

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.

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 é o ID do seu grupo de usuários e JOB_ID é o ID do trabalho que foi retornado quando você criou o trabalho de importação do 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
    }
}

No exemplo de saída anterior, o PRE_SIGNED_URL é URL aquele para o qual você fez o upload CSV do arquivo. A ferramenta ROLE_ARN é a função de CloudWatch registros ARN 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 ferramenta PAGINATION_TOKEN a 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

Na primeira vez que cada usuário importado fizer login e inserir uma senha, será solicitado que ele insira uma nova senha. O procedimento a seguir descreve a experiência do usuário em um aplicativo personalizado com usuários locais após a importação de um CSV arquivo. Se os usuários fizerem login com a interface de usuário hospedada, o Amazon Cognito solicitará que eles definam uma nova senha ao fazerem login pela primeira vez.