ユーザープール属性 - Amazon Cognito

ユーザープール属性

属性は、名前、E メールアドレス、電話番号など、個々のユーザーを識別できる各種情報です。新しいユーザープールにはデフォルトの標準属性のセットがあります。AWS Management Consoleのユーザープール定義には、カスタム属性を追加することもできます。このトピックでは、それらの属性について詳しく説明し、ユーザープールの設定のヒントを示します。

ユーザーに関するすべての情報を属性に保存しないでください。例えば、使用統計やゲームスコアなどの頻繁に変化するユーザーデータは、Amazon Cognito Sync または Amazon DynamoDB などの個別のデータストアに保存してください。

Amazon Cognito は、[OpenID Connect specification] (OpenID Connect の仕様) にある基づいて、以下の標準属性セットをすべてのユーザーに割り当てます。

  • address

  • birthdate

  • email

  • family_name

  • gender

  • given_name

  • locale

  • middle_name

  • name

  • nickname

  • phone_number

  • picture

  • preferred_username

  • profile

  • updated_at

  • website

  • zoneinfo

これらの属性は、すべてのユーザーに対してオプションの属性として利用できます。属性を必須にする場合は、ユーザープールの作成プロセスで、[Required] (必須) 属性の横にあるチェックボックスをオンにします。

注記

標準属性を必須とマークすると、ユーザーは、属性の値が指定されない限り登録することはできません。ユーザーを作成し、必須属性の値を指定しないようにするには、管理者はAdminCreateUser API を使用できます。ユーザープールを作成した後で、属性を必須と必須ではないの間で切り替えることができません。

標準属性値およびカスタム属性値は、デフォルトでは最大 2048 文字の任意の文字列ですが、updated_at など一部の属性値には形式の制限があります。[E メール] および [電話] のみ検証できます。

注記

ドキュメントや標準によっては、属性をメンバーと呼んでいます。

これらのフィールドに関するその他の注意事項を次に示します。

E メール

ユーザーおよび管理者は、E メールアドレスの値を確認できます。

適切な AWS アカウント 許可を持つ管理者は、ユーザーの E メールアドレスを変更し、それを検証済みとしてマークできます。AdminUpdateUserAttributes API または admin-update-user-attributes AWS Command Line Interface (AWS CLI) コマンドを使用して、E メールアドレスを検証済みとしてマークします。このコマンドを使用すると、管理者はemail_verified 属性を true に変更できます。AWS Management Console の [Users] (ユーザー) タブでユーザーを編集して、E メールアドレスを検証済みとしてマークすることもできます。

phone

SMS 多要素認証 (MFA) がアクティブである場合、ユーザーは電話番号を入力する必要があります。詳細については、「ユーザープールに MFA を追加します」を参照してください。

ユーザーおよび管理者は、電話番号の値を確認できます。

適切な AWS アカウント 許可を持つ管理者が、ユーザーの電話番号を変更して、それを検証済みとしてマークできます。AdminUpdateUserAttributes API または admin-update-user-attributes AWS CLI コマンドを使用して、電話番号を検証済みとしてマークします。このコマンドを使用すると、管理者は、phone_number_verified 属性を true に変更できます。AWS Management Console の [Users] (ユーザー) タブでユーザーを編集して、電話番号を検証済みとしてマークすることもできます。

重要

電話番号は次の形式に従う必要があります: 電話番号は、プラス記号 (+) から始めて国番号がその後に続く必要があります。電話番号には、プラス記号 (+) および数値のみを含めることができます。値をサービスに送信する前に、電話番号から括弧、スペース、ハイフン (-) などの他の文字を削除してください。例えば、米国の電話番号は +14325551212 の形式に従っています。

preferred_username

preferred_username は、必要に応じて、またはエイリアスとして選択できますが、両方を選択することはできません。preferred_username がエイリアスである場合、ユーザーを確認した後、UpdateUserAttributes API を使用して、属性値を追加できます。

必須属性を表示する

以下の手順に従って、特定のユーザープールに必要な属性を表示します。

注記

ユーザープールを作成した後は、必須の属性を変更することはできません。

Original console
必須属性を表示する

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [Manage User Pools] (ユーザープールの管理) を選択します。

  3. [Your User Pools] (ユーザープール) ページからユーザープールを選択します。

  4. 左側のナビゲーションメニューで [Attributes] (属性) を選択します。

  5. [Which standard attributes are required?] (必須の標準的な属性はどれですか?) で、ユーザープールの必須属性が表示されます。

New console
必須属性を表示する

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [User Pools] (ユーザープール) を選択します。

  3. リストから存在するユーザープールを 1 つ選択します。

  4. [Sign-up experience] (サインアップエクスペリエンス) タブを選択します。

  5. [Required attributes] (必須の属性) セクションで、ユーザープールの必須属性が表示されます。

username 値は個別の属性であり、name 属性とは異なります。各ユーザーには、username 属性があります。Amazon Cognito は、フェデレーティッドユーザーのユーザー名を自動的に生成します。Amazon Cognito ディレクトリにネイティブユーザーを作成するには、username 属性を指定する必要があります。ユーザーを作成した後で、username 属性の値を変更することはできません。

デベロッパーは、preferred_username 属性を使用して、変更可能なユーザー名をユーザーに付与できます。詳細については、「ログイン属性のカスタマイズ」を参照してください。

お客様のアプリケーションでユーザー名が不要の場合は、ユーザーにユーザー名を指定するように求める必要はありません。アプリでユーザー用の一意のユーザー名をバックグラウンドで作成できます。例えば、E メールアドレスとパスワードを登録しそれを使用してサインインするようにユーザーに求める場合は便利です。詳細については、「ログイン属性のカスタマイズ」を参照してください。

username はユーザープール内で一意である必要があります。username は再利用できますが、削除されて使用されなくなった場合のみです。

ユーザープールを作成するときに、ユーザーが E メールアドレスまたは電話番号をユーザー名として使用してサインアップおよびサインインできるようにする場合は、ユーザー名属性を設定できます。また、エイリアス属性を設定してユーザーに選択肢を与えることもできます。ユーザーがサインアップするときに複数の属性を含めて、ユーザー名、優先ユーザー名、E メールアドレス、または電話番号でサインインできます。

重要

ユーザープールを作成した後は、この設定を変更することはできません。

エイリアス属性とユーザー名属性の選択方法

要件 エイリアス属性 ユーザー名属性
Users have multiple sign-in attributes Yes¹ No²
Users must verify email address or phone number before they can sign in with it Yes No
Prevent UsernameExistsException when user signs up Yes No
Can assign the same sign-in attribute to more than one user Yes³ No

¹ 使用可能なサインイン属性は、ユーザー名、E メールアドレス、電話番号、および優先ユーザー名です。

² E メールアドレスおよび電話番号を使用してサインインできます。

³ 属性を確認した最後のユーザーのみが、その属性を使用してサインインできます。

必要に応じて、ユーザーはサインイン時にエイリアスを使用して他の属性を入力できます。デフォルトでは、ユーザーは各自のユーザー名とパスワードでサインインします。ユーザー名はユーザーが変更できない固定値です。属性をエイリアスとしてマーキングすると、ユーザーはユーザー名の代わりにその属性を使用してサインインできます。E メールアドレス、電話番号、および任意ユーザー名属性は、エイリアスレコードとしてマーキングできます。例えば、E メールと電話をユーザープールのエイリアスとして選択すると、そのユーザープールのユーザーは、自分のユーザー名、E メールアドレス、または電話番号とパスワードを使ってサインインできます。

エイリアス属性を選択するには、ユーザープールを作成するときに [User name] (ユーザー名) と 1 つ以上の追加のサインインオプションを選択します。

注記

大文字と小文字を区別しないようにユーザープールを設定すると、ユーザーは小文字または大文字を使用してサインアップ、またはエイリアスを使用してサインインできるようになります。詳細については、Amazon Cognito API リファレンスの「CreateUserPool」を参照してください。

エイリアスとして E メールアドレスを選択した場合、Amazon Cognito は有効な E メールアドレス形式と一致するユーザー名を受け入れません。同様に、電話番号をエイリアスとして選択した場合、Amazon Cognito は、有効な電話番号形式に一致するユーザープールのユーザー名を受け入れません。

注記

エイリアス値は、ユーザープール内で一意にする必要があります。エイリアスがメールアドレスまたは電話番号に設定される場合、指定される値は 1 つのアカウントのみで検証状態になります。サインアップ時に E メールアドレスまたは電話番号をエイリアス値として指定し、別のユーザーがそのエイリアス値を既に使用している場合、登録は成功します。ただし、ユーザーがこの E メール (または電話番号) を持つアカウントを確認して有効なコードを入力しようとする場合、Amazon Cognito は、AliasExistsException エラーを返します。エラーは、この E メールアドレス (または電話番号) を持つアカウントが既に存在していることを示します。この時点で、ユーザーは新しいアカウントの作成を中止して、古いアカウントのパスワードのリセットを試すことができます。ユーザーが新しいアカウントの作成を続行する場合は、アプリは forceAliasCreation オプションを使用して ConfirmSignUp API を呼び出す必要があります。forceAliasCreation を使用する ConfirmSignUp は、エイリアスを前のアカウントから新しく作成されたアカウントに移動し、前のアカウントで未確認の属性をマークします。

ユーザーが電話番号および E メールアドレスを確認した後、電話番号および E メールアドレスのみがユーザーのアクティブエイリアスになります。エイリアスとしてこれらを使用する場合は、E メールアドレスと電話番号の自動確認を選択することをお勧めします。

ユーザーがサインアップするときに、E メールアドレスおよび電話番号の属性の UsernameExistsException エラーを防ぐために、エイリアス属性を選択します。

preferred_username 属性をアクティブにして、username 属性値が変更されていないときに、ユーザーがサインインに使用するユーザー名を変更できるようにします。このユーザーエクスペリエンスをセットアップする場合は、新しい username 値を preferred_username として送信し、エイリアスとして preferred_username を選択します。こうすることで、ユーザーは入力した新しい値でサインインできます。preferred_username がエイリアスとして選択された場合、ユーザーはアカウントが確認されている場合にのみ、値を指定できます。登録時にはこの値は指定できません。

ユーザーがユーザー名を使用してサインアップする場合、ユーザーが次の 1 つ以上のエイリアスを使用してサインインできるかどうかを選択できます。

  • 検証済みの E メールアドレス

  • 検証済みの電話番号

  • 優先ユーザー名

これらのエイリアスはユーザーがサインアップした後に変更できます。

エイリアスを使用してサインインできるように、ユーザープールを作成する場合は、次の手順を含めます。

Original console
エイリアスを使用したサインインをユーザープールで設定する

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [Manage User Pools] (ユーザープールの管理) を選択します。

  3. ページの右上にある [ユーザープールを作成する] を選択します。

  4. ページの左上隅で、[Attributes] (属性) を選択します。

  5. [Attributes] (属性) タブの、[How do you want your end users to sign-in?] (どのようにエンドユーザーがサインインするようにしますか?) で、[Username] (ユーザー名) を選択します。次のいずれかのオプションを選択します。

    • [Also allow sign in with verified email address] (検証済みの E メールアドレスでのサインインも許可): ユーザーが自分の E メールアドレスを使用してサインインすることを許可します。

    • [Also allow sign in with verified phone number] (検証済みの電話番号でのサインインも許可): ユーザーが自分の電話番号を使用してサインインすることを許可します。

    • [Also allow sign in with preferred username] (優先ユーザー名でのサインインも許可): ユーザーが優先ユーザー名を使用してサインインすることを許可します。これはユーザーが変更できるユーザー名です。

  6. [Next step] (次のステップ) をクリックして保存し、ウィザードのすべての手順を完了します。

New console
ユーザーが優先ユーザー名でサインインできるようにユーザープールを設定するには

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [User Pools] (ユーザープール) を選択します。

  3. ページの右上隅にある [Create a user pool] (ユーザープールを作成する) を選択して、ユーザープール作成のウィザードを開始します。

  4. [Configure sign-in experience] (サインインエクスペリエンスを構成する) で、ユーザープールに関連付けるアイデンティティの [Provider types] (プロバイダーのタイプ) を選択します。

  5. [Cognito user pool sign-in options] (Cognito ユーザープールのサインインオプション) で、[User name] (ユーザー名)、[Email] (E メール)、および [Phone number] (電話番号) のお好きな組み合わせを選択します。

  6. [User name requirements] (ユーザー名の要件) で、[Allow users to sign in with a preferred user name] (優先ユーザー名を使用したサインインを許可する) を選択して、ユーザーがサインイン時に代替ユーザー名を設定できるようにします。

  7. [Next] (次へ) をクリックし、ウィザードのすべての手順を完了します。

ユーザー名として E メールアドレスまたは電話番号でユーザーがサインアップする場合、E メールアドレスのみ、電話番号のみ、またはいずれか一方でもサインアップできるようにするかを選択することができます。

ユーザー名属性を選択するには、ユーザープールを作成するときに、サインインオプションとして [User name] (ユーザー名) を選択しないでください。

E メールまたは電話番号は一意である必要があり、別のユーザーによって既に使用されていてはなりません。これを検証する必要はありません。ユーザーが E メールアドレスまたは電話番号を使用してサインアップした後、ユーザーは同じ E メールアドレスまたは電話番号を使用して新しいアカウントを作成することはできません。ユーザーは既存のアカウントを (必要に応じてパスワードをリセットして) 再利用できるだけです。ただし、ユーザーは E メールアドレスまたは電話番号を新しい E メールアドレスまたは電話番号に変更できます。E メールアドレスまたは電話番号が既に使用中ではない場合は、それが新しいユーザー名となります。

注記

ユーザーが E メールアドレスをユーザー名として使用してサインアップした場合、ユーザー名を別の E メールアドレスに変更できますが、電話番号に変更することはできません。電話番号でサインアップする場合は、ユーザー名を別の電話番号を変更できますが、E メールアドレスに変更することはできません。

次のステップを使用して、ユーザープール作成のプロセス中に、E メールアドレスまたは電話番号を使用したサインアップおよびサインインをセットアップします。

Original console
E メールアドレスまたは電話番号を使用したサインアップとサインインをユーザープールで設定するには

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [Manage User Pools] (ユーザープールの管理) を選択します。

  3. ページの右上にある [ユーザープールを作成する] を選択します。

  4. ページの左上隅で、[Attributes] (属性) を選択します。

  5. [Attributes] (属性) タブの、[How do you want your end users to sign-in?] (どのようにエンドユーザーがサインインするようにしますか?) で、[Email address or phone number] (E メールアドレスまたは電話番号) を選択します。次のいずれかのオプションを選択します。

    • [Allow email addresses] (E メールアドレスを許可): ユーザーが E メールをユーザー名として使用してサインアップすることを許可します。

    • [Allow phone numbers] (電話番号を許可): ユーザーが電話番号をユーザー名として使用してサインアップすることを許可します。

    • [Allow both email addresses and phone number (users can choose one)] (E メールアドレスと電話番号の両方を許可 (ユーザーは 1 つを選択できます)): ユーザーがサインアップ時にユーザー名として E メールアドレスまたは電話番号を使用することを許可します。

  6. [Next step] (次のステップ) をクリックして保存し、ウィザードのすべての手順を完了します。

New console
E メールアドレスまたは電話番号を使用したサインアップとサインインをユーザープールで設定するには

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [User Pools] (ユーザープール) を選択します。

  3. ページの右上隅にある [Create a user pool] (ユーザープールを作成する) を選択して、ユーザープール作成のウィザードを開始します。

  4. [Cognito user pool sign-in options] (Cognito ユーザープールのサインインオプション) で、ユーザーがサインインに使用することを許可する属性を表す [Email] (E メール)、および [Phone number] (電話番号) から任意の組み合わせを選択します。

  5. [Next] (次へ) をクリックし、ウィザードの残りのステップを完了します。

注記

E メールアドレスまたは電話番号をユーザープールの必須属性としてマークする必要はありません。

アプリケーションでオプション 2 を実装する

  1. CreateUserPool API を呼び出してユーザープールを作成します。UserNameAttributes パラメータを phone_number、email、または phone_number | email に設定します。

  2. SignUp API を呼び出して、E メールアドレスまたは電話番号を API の username パラメータに渡します。この API によって次の処理が実行されます。

    • [username] 文字列が有効な E メールアドレス形式の場合、ユーザープールは自動的にユーザーの email 属性に username 値を入力します。

    • [username] 文字列が有効な電話番号形式の場合、ユーザープールは自動的にユーザーの phone_number 属性に username 値を入力します。

    • username 文字列形式が E メールアドレスまたは電話番号の形式ではない場合は、SignUp API から例外が返されます。

    • SignUp API によってユーザーの永続的な UUID が生成され、内部でイミュータブルなユーザー名属性として使用されます。この UUID は、ユーザー ID トークン内の sub クレームと同じ値です。

    • username 文字列に含まれている E メールアドレスまたは電話番号が既に使用されている場合、SignUp API によって例外が返されます。

ListUsers API を除くすべての API で、E メールアドレスまたは電話番号をエイリアスとしてユーザー名の代わりに使用できます。ListUsers を呼び出すと、email または phone_number 属性で検索できます。username で検索する場合は、エイリアスではなく、実際のユーザー名を指定する必要があります。

ユーザープールには、カスタム属性を最大 50 まで追加できます。カスタム属性の最小長または最大長を指定できます。ただし、すべてのカスタム属性の最大長は 2048 文字以下にする必要があります。

各カスタム属性には以下の特徴があります。

  • 文字列または数値として定義できます。Amazon Cognito は ID トークンにカスタム属性値を文字列としてのみ書き込みます。

  • ユーザーが属性の値を提供することを要求することはできません。

  • ユーザープールに追加した後で、削除または変更することはできません。

  • 属性名の文字長は、Amazon Cognito が受け入れる制限内です。詳細については、「Amazon Cognito のクォータ」を参照してください。

  • 変更可能またはイミュータブルとすることができます。ユーザーを作成するときに、イミュータブル属性に値を書き込むことができます。アプリクライアントがその属性に対する書き込み権限を持っている場合、変更可能な属性の値を変更できます。詳細については、「属性の権限と範囲」を参照してください。

注記

コードおよび ロールベースアクセスコントロール のルールの設定で、カスタム属性は標準属性と区別するために、custom: プレフィックスを必要とします。

以下の手順を使用して、新しくカスタム属性を作成します。

Original console
コンソールを介してカスタム属性を追加するには

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [Manage User Pools] (ユーザープールの管理) を選択します。

  3. [ユーザープール] ページで、設定するユーザープールを選択します。

  4. 左のナビゲーションバーから [Attributes] (属性) を選択します。

  5. [Do you want to add custom attributes?] (カスタム属性を追加しますか?) の下で [Add custom attribute] (カスタム属性の追加) を選択します。

  6. 新しい属性に関する以下の詳細情報を入力します。

    • 名前を入力します。

    • [Type] (タイプ) (文字列または数値) を選択します。

    • 最小文字列の長さまたは数値を入力します。

    • 最大文字列の長さまたは数値を入力します。

    • ユーザーが初期値を設定した後で、カスタム属性の値を変更する権限をユーザーに付与する場合は、[Mutable] (変更可能) を選択します。

  7. [Save changes] (変更の保存) をクリックします。

New console
コンソールを使用してカスタム属性を追加する

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [User Pools] (ユーザープール) を選択します。

  3. リストから存在するユーザープールを 1 つ選択します。

  4. [Sign-up experience] (サインアップエクスペリエンス) タブをクリックして、[Custom attributes] (カスタム属性) セクションで、[Add custom attributes] (カスタム属性を追加する) を選択します。

  5. [Add custom attributes] (カスタム属性を追加する) のページで、新しい属性に関する以下の詳細情報を入力します。

    • 名前を入力します。

    • [Type] (タイプ) (文字列または数値) を選択します。

    • 最小文字列の長さまたは数値を入力します。

    • 最大文字列の長さまたは数値を入力します。

    • ユーザーが初期値を設定した後で、カスタム属性の値を変更する権限をユーザーに付与する場合は、[Mutable] (変更可能) を選択します。

  6. [Save changes] (変更の保存) をクリックします。

各アプリクライアントで、各ユーザー属性に読み取りと書き込み権限を設定できます。これにより、ユーザー用に保存する各属性の読み取りおよび変更に必要なアプリによるアクセスを制御できます。例えば、ユーザーが有料サービスを利用しているお客様であるかどうかを示すカスタム属性があるとします。アプリでこの属性は表示できますが、直接変更することはできません。代わりに、管理ツールまたはバックグラウンドプロセスを使用してこの属性を更新します。ユーザー属性の権限は、Amazon Cognito コンソール、Amazon Cognito API、または AWS CLI から設定できます。デフォルトでは、新しいカスタム属性を利用する前に、読み取り/書き込みの許可を設定する必要があります。Amazon Cognito コンソールで新しいアプリケーションクライアントを作成すると、デフォルトでは、すべての標準属性とカスタム属性に対する読み取り/書き込み許可がアプリケーションに付与されます。アプリケーションに対する情報を必要な量のみに制限するには、アプリケーションが必要とするスコープのサブセットを選択します。

Original console
コンソールを介して属性の権限を更新するには

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [Manage User Pools] (ユーザープールの管理) を選択します。

  3. [ユーザープール] ページで、設定するユーザープールを選択します。

  4. 左のナビゲーションバーで、[App clients] (アプリクライアント) を選択します。

  5. 更新するアプリクライアントの [Show Details] (詳細を表示) を選択します。

  6. ページの最下部で、[Set attribute read and write permissions] (属性の読み込みおよび書き込みアクセス権限を設定する) をクリックし、読み込みおよび書き込みアクセス権限を設定します。

  7. [アプリクライアントの変更を保存する] を選択します。

New console
コンソールを介して属性の権限を更新するには

  1. AWS Management Console の Amazon Cognito に移動します。コンソールからプロンプトが表示されたら、AWS 認証情報を入力します。

  2. [User Pools] (ユーザープール) を選択します。

  3. リストから既存するユーザープールを 1 つ選択します。

  4. [App integration] (アプリケーションの統合) タブ、[App clients] (アプリケーションクライアント) セクションで、リストからアプリケーションクライアントを選択します。

  5. [Attribute read and write permissions] (属性の読み込みおよび書き込みアクセス許可) セクションで、[Edit] (編集) を選択します。

  6. [Edit attribute read and write permissions] (属性の読み込みおよび書き込みアクセス権限を編集) ページで、読み取りおよび書き込み権限を設定し、[Save changes] (変更の保存) を選択します。

カスタム属性を使用して、アプリクライアントごとに以上の手順を繰り返します。

アプリごとに、属性を読み取り可能または書き込み可能とマークできます。これは、標準属性とカスタム属性の両方に当てはまります。アプリは、読み取り可能とマークされた属性を読み取ることができ、書き込み可能とマークされた属性を書き込むことができます。アプリが書き込み可能ではない属性を更新しようとすると、アプリは NotAuthorizedException 例外を取得します。GetUser を呼び出したアプリは、そのアプリが読み取り可能な属性のみ受け取ります。アプリからのユーザーの ID トークンには、読み取り可能な属性に対応するクレームのみが含まれます。ユーザープールの必須属性は常に書き込み可能です。AWS CLI または管理 API を使用して書き込み可能な属性を設定したが、必須属性を指定しない場合、InvalidParameterException 例外が返されます。

ユーザープールを作成した後、属性の権限と範囲を変更できます。