CSV ファイルからユーザープールへのユーザーのインポート

外部 ID ストアがあり、かつ、新しいローカルユーザーのためにユーザープールを準備する時間がある場合、カンマ区切り値 (CSV) ファイルからの一括ユーザーインポートは、Amazon Cognito ユーザープールへの移行のための手間とコストが少ないオプションになります。CSV ファイルインポートは、テンプレートファイルをダウンロードして入力し、インポートジョブのユーザープールにファイルを渡すプロセスです。CSV インポートを使用して、テストユーザーをすばやく作成できます。また、外部 ID ストアへの読み取り API リクエストをプログラムでファイルに入力したうえで、その詳細と属性を解析してファイルへの書き込みオペレーションにすることもできます。

デフォルトでは、インポートプロセスはパスワードを除くすべてのユーザー属性の値を設定します。つまり、ユーザーは最初にサインインした際にパスワードを変更する必要があります。このメソッドを使用してインポートすると、ユーザーは RESET_REQUIRED 状態になります。

または、既存のパスワードハッシュを使用してユーザーをインポートすることもできます。インポートジョブの作成時にパスワードハッシュアルゴリズムを指定し、CSV ファイルにパスワードハッシュを含めると、Amazon Cognito は既存のパスワードを使用してユーザーをインポートします。これらのユーザーは CONFIRMEDステータスで作成され、パスワードをリセットせずにすぐにサインインできます。詳細については、「パスワードハッシュを使用したユーザーのインポート」を参照してください。

CSV からユーザーをインポートする最も簡単な方法は、ユーザープールで [パスワードなしのサインイン] を有効にすることです。E メールアドレスと電話番号の属性、さらにユーザープールの適切な設定により、ユーザーはインポートジョブの完了直後に E メールまたは SMS ワンタイムパスワード (OTP) を使用してサインインできます。詳細については、「インポートされたユーザーにパスワードをリセットするように要求」を参照してください。

AdminSetUserPassword API リクエストで Permanent パラメータを true に設定することで、ユーザーのパスワードを設定することもできます。CSV インポートは、ユーザープール内で請求対象の月間アクティブユーザー (MAU) にはカウントされません。ただし、パスワードリセットオペレーションは MAU を発生させます。パスワードを使用する多数のユーザーをインポートしてもすぐにはアクティブにならない場合、コストを管理するには、ユーザーがサインインして RESET_REQUIRED チャレンジを受け取ったときに、新しいパスワードの入力を求めるようにアプリケーションを設定します。

CloudWatch Logs IAM ロールの作成

Amazon Cognito の CLI または API を使用している場合は、CloudWatch IAM ロールを作成する必要があります。以下の手順では、Amazon Cognito がインポートジョブの結果を CloudWatch Logs に書き込むために使用できる IAM ロールを作成する方法について説明します。

ユーザーインポート CSV ファイルの作成

既存のユーザーをユーザープールにインポートする前に、インポートするユーザーとその属性を含むカンマ区切り値 (CSV) ファイルを作成する必要があります。ユーザープールから、ユーザープールの属性スキーマを反映するヘッダーを含むユーザーインポートファイルを取得できます。その後、CSV ファイルのフォーマット のフォーマット要件に一致するユーザー情報を挿入できます。

CSV ファイルヘッダーのダウンロード (コンソール)

CSV ヘッダーファイルをダウンロードするには、次の手順に従います。

CSV ファイルヘッダーのダウンロード (AWS CLI)

正しいヘッダーのリストを取得するには、[ユーザー] メニューの [ユーザーをインポート] で、[インポートジョブを作成] を選択します。表示されるダイアログで template.csv リンクを選択し、ユーザープール属性を含むテンプレートファイルをダウンロードします。

次の CLI コマンドを実行することもできます。USER_POOL_ID は、ユーザーをインポートする先のユーザープールのユーザープール識別子です。

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

レスポンス例:

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

CSV ファイルのフォーマット

ダウンロードしたユーザーインポート CSV ヘッダーファイルは次の文字列のようになります。ユーザープールに追加したカスタム属性も含まれます。

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

ユーザーのためのこのヘッダーと属性値が含まれ、次のルールに従ってフォーマットされているように CSV ファイルを編集します。

次のリストは、カスタム属性のないユーザープールの CSV インポートファイルの例です。ユーザープールスキーマは、この例とは異なる場合があります。その場合は、ユーザープールからダウンロードした CSV テンプレートにテスト値を入力する必要があります。

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

Amazon Cognito ユーザープールのインポートジョブの作成と実行

このセクションでは、Amazon Cognito コンソールと AWS Command Line Interface () を使用してユーザープールのインポートジョブを作成して実行する方法について説明しますAWS CLI。

CSV ファイルからのユーザーのインポート (コンソール)

次の手順は、CSV ファイルからユーザーをインポートする方法について説明します。

ユーザーのインポート (AWS CLI)

ユーザープールにユーザーをインポートするには、次の CLI コマンドが使用できます:

これらのコマンドに関するコマンドラインオプションのリストを取得するには、help コマンドラインオプションを使用します。次に例を示します。

aws cognito-idp get-csv-header help

ユーザーインポートジョブの作成

CSV ファイルを作成した後、次の CLI コマンドを使用してユーザーインポートジョブを作成します。[JOB_NAME] にはジョブに付ける名前を指定します。[USER_POOL_ID] には以前と同じユーザープール ID を指定します。[ROLE_ARN] には、CloudWatch Logs IAM ロールの作成 で次のとおり受け取ったロール ARN を指定します。

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

レスポンスで返される PRE_SIGNED_URL は 15 分間有効です。この時間以後は無効になり、新規のユーザーインポートジョブを作成して新しい 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
    }
}

ユーザーインポートジョブのステータス値

ユーザーインポートのコマンドに対する応答には、Status を示す次のような値が見つかります。

CSV ファイルのアップロード

以下の curl コマンドを使用して、ユーザーデータが含まれる CSV ファイルを create-user-import-job コマンドのレスポンスから取得した事前署名済みの URL にアップロードします。

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

このコマンドの出力から、次のようなメッセージを見つけます: "We are completely uploaded and fine" このメッセージは、ファイルが正常にアップロードされたことを示します。ユーザープールは、インポートジョブの実行後にインポートファイルに情報を保持しません。完了または期限切れになると、Amazon Cognito は、アップロードした CSV ファイルを削除します。

ユーザーインポートジョブの説明

ユーザーインポートジョブの説明を取得するには、次のコマンドを使用します。USER_POOL_ID はユーザープール ID です。JOB_ID は、ユーザーインポートジョブの作成時に返されたジョブ ID です。

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

前述の例の出力では、PRE_SIGNED_URL は CSV のアップロード先の URL です。ROLE_ARN は、ロールの作成時に受け取った CloudWatch Logs ロール ARN です。

ユーザーインポートジョブを表示する

ユーザーインポートジョブを一覧表示するには、次のコマンドを使用します:

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

ジョブは時系列で、作成が最後から最初の順で表示されます。2 番目のジョブのあとの PAGINATION_TOKEN 文字列は、このリストコマンドについて、まだ結果が残っていることを示します。残りの結果を表示するには、次のように --pagination-token オプションを使用します:

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

ユーザーインポートジョブの開始

ユーザーインポートジョブを開始するには、次のコマンドを使用します:

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

インポートジョブは、アカウントごとに 1 つしかアクティブにできません。

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

ユーザーインポートジョブの停止

ユーザーインポートジョブの進行中に停止するには、次のコマンドを使用します。ジョブを停止すると、再開することはできません。

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

ユーザープールのインポート結果を CloudWatch コンソールに表示

インポートジョブの結果は、Amazon CloudWatch コンソールで表示できます。

結果の表示

次のステップでは、ユーザープールのインポートの結果を表示する方法を説明します。

結果の解釈

正常にインポートしたユーザーは、ステータスが「PasswordReset」に設定済みです。

次の場合、ユーザーはインポートされませんが、インポートジョブは継続します。

以下の場合、インポートジョブは失敗します。

インポートされたユーザーにパスワードをリセットするように要求

ユーザープールがパスワードベースのサインインのみを提供している場合、ユーザーはインポート後にパスワードをリセットする必要があります。初めてサインインするときは、任意のパスワードを入力できます。Amazon Cognito は、アプリケーションからのサインインリクエストに対する API レスポンスで、新しいパスワードを入力するようユーザーに求めます。

ユーザープールにパスワードなしの認証要素がある場合、Amazon Cognito はインポートしたユーザーに対してデフォルトでその認証要素を使用します。ユーザーは、新しいパスワードの入力を求められず、パスワードなしの E メールまたは SMS OTP ですぐにサインインできます。また、ユーザー名パスワードやパスキーなど、他のサインイン方法を完了できるように、ユーザーにパスワードの設定を求めることもできます。ユーザーインポート後のパスワードなしのサインインには、以下の条件が適用されます。

パスワードなしの認証の設定方法や、その認証フローをアプリケーションで構築する方法などの詳細については、「Amazon Cognito ユーザープールによる認証」を参照してください。

次の手順では、CSV ファイルのインポート後、カスタム構築されたログインメカニズムにおける、RESET_REQUIRED のローカルユーザーのユーザーエクスペリエンスについて説明します。ユーザーがマネージドログインでサインインする場合は、[パスワードを忘れた場合] オプションを選択し、E メールまたはテキストメッセージに記載されているコードを入力してパスワードを設定するよう指示します。

パスワードハッシュを使用したユーザーのインポート

既存の認証システムから Amazon Cognito にユーザーを移行すると、ユーザー属性とともにパスワードハッシュをインポートできます。その後、ユーザーはパスワードをリセットすることなく、既存のパスワードですぐにサインインできます。ユーザーが初めてサインインすると、Amazon Cognito は認証情報をネイティブの Amazon Cognito 認証システムに透過的に移行します。

パスワードハッシュのインポートの仕組み

パスワードハッシュのインポートを使用すると、既存のパスワードでサインインする能力を維持しながらユーザーを移行できます。インポートプロセスは次のように機能します。

サポートされているパスワードハッシュアルゴリズム

Amazon Cognito は、インポート用に次のパスワードハッシュアルゴリズムをサポートしています。

パスワードハッシュに上記の上限を超えるパラメータ値がある場合、そのユーザーのインポートは失敗します。インポートする前にソースシステムのパスワードハッシュ設定を確認して、互換性を確認してください。

CSV ファイルにパスワードハッシュを追加する

ユーザーインポート用の CSV テンプレートをダウンロードすると、テンプレートにpassword_hash列が含まれます。この列に、既存のパスワードでインポートするユーザーのパスワードハッシュ値を入力します。

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

パスワードハッシュを使用したインポートジョブの作成 (AWS CLI)

パスワードハッシュを使用してユーザーをインポートするには、インポートジョブを作成するときにパスワードハッシュアルゴリズムを指定する必要があります。インポートジョブのすべてのユーザーは、同じアルゴリズムを使用する必要があります。

次の AWS Command Line Interface コマンドを使用して、パスワードハッシュを使用してインポートジョブを作成します。--password-hashing-algorithm パラメータは、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

BCRYPT を、サポートされているアルゴリズムの 1 つ、BCRYPT、ARGON2ID、または SCRYPTに置き換えますPBKDF2_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
    }
}

レスポンスには、指定したアルゴリズムを確認する PasswordHashingAlgorithm フィールドが含まれます。署名付き URL に CSV ファイルをアップロードし、「」の説明に従ってジョブを開始しますCSV ファイルのアップロード。

パスワードハッシュのインポート後のユーザーエクスペリエンス

パスワードハッシュを使用してインポートされたユーザーには、次のエクスペリエンスがあります。

パスワードハッシュのインポートエラーのトラブルシューティング

ユーザーのパスワードハッシュのインポートが失敗した場合、Amazon Cognito は失敗を Amazon CloudWatch Logs ログに記録します。一般的なエラーシナリオは次のとおりです。

ユーザーのパスワードハッシュのインポートが失敗した場合、Amazon Cognito はユーザーを作成しません。インポートジョブの他のユーザーは引き続き処理されます。Amazon CloudWatch Logs ログを確認して、失敗したユーザーと各失敗の理由を特定します。

パスワードハッシュのインポートに関するセキュリティ上の考慮事項

Amazon Cognito は、インポートされたパスワードハッシュに追加のセキュリティ対策を適用します。