ユーザープール属性
属性は、名前、E メールアドレス、電話番号など、個々のユーザーを識別できる各種情報です。新しいユーザープールにはデフォルトの標準属性のセットがあります。AWS Management Consoleのユーザープール定義には、カスタム属性を追加することもできます。このトピックでは、それらの属性について詳しく説明し、ユーザープールの設定のヒントを示します。
ユーザーに関するすべての情報を属性に保存しないでください。例えば、使用統計やゲームスコアなどの頻繁に変化するユーザーデータは、Amazon Cognito Sync または Amazon DynamoDB などの個別のデータストアに保存してください。
Amazon Cognito は、[OpenID Connect specification]
-
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 を使用して、属性値を追加できます。
必須属性を表示する
以下の手順に従って、特定のユーザープールに必要な属性を表示します。
ユーザープールを作成した後は、必須の属性を変更することはできません。
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 メールアドレス
-
検証済みの電話番号
-
優先ユーザー名
これらのエイリアスはユーザーがサインアップした後に変更できます。
エイリアスを使用してサインインできるように、ユーザープールを作成する場合は、次の手順を含めます。
ユーザー名として E メールアドレスまたは電話番号でユーザーがサインアップする場合、E メールアドレスのみ、電話番号のみ、またはいずれか一方でもサインアップできるようにするかを選択することができます。
ユーザー名属性を選択するには、ユーザープールを作成するときに、サインインオプションとして [User name] (ユーザー名) を選択しないでください。
E メールまたは電話番号は一意である必要があり、別のユーザーによって既に使用されていてはなりません。これを検証する必要はありません。ユーザーが E メールアドレスまたは電話番号を使用してサインアップした後、ユーザーは同じ E メールアドレスまたは電話番号を使用して新しいアカウントを作成することはできません。ユーザーは既存のアカウントを (必要に応じてパスワードをリセットして) 再利用できるだけです。ただし、ユーザーは E メールアドレスまたは電話番号を新しい E メールアドレスまたは電話番号に変更できます。E メールアドレスまたは電話番号が既に使用中ではない場合は、それが新しいユーザー名となります。
ユーザーが E メールアドレスをユーザー名として使用してサインアップした場合、ユーザー名を別の E メールアドレスに変更できますが、電話番号に変更することはできません。電話番号でサインアップする場合は、ユーザー名を別の電話番号を変更できますが、E メールアドレスに変更することはできません。
次のステップを使用して、ユーザープール作成のプロセス中に、E メールアドレスまたは電話番号を使用したサインアップおよびサインインをセットアップします。
E メールアドレスまたは電話番号をユーザープールの必須属性としてマークする必要はありません。
アプリケーションでオプション 2 を実装する
-
CreateUserPool
API を呼び出してユーザープールを作成します。UserNameAttributes
パラメータをphone_number
、email
、またはphone_number | email
に設定します。 -
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:
プレフィックスを必要とします。
以下の手順を使用して、新しくカスタム属性を作成します。
各アプリクライアントで、各ユーザー属性に読み取りと書き込み権限を設定できます。これにより、ユーザー用に保存する各属性の読み取りおよび変更に必要なアプリによるアクセスを制御できます。例えば、ユーザーが有料サービスを利用しているお客様であるかどうかを示すカスタム属性があるとします。アプリでこの属性は表示できますが、直接変更することはできません。代わりに、管理ツールまたはバックグラウンドプロセスを使用してこの属性を更新します。ユーザー属性の権限は、Amazon Cognito コンソール、Amazon Cognito API、または AWS CLI から設定できます。デフォルトでは、新しいカスタム属性を利用する前に、読み取り/書き込みの許可を設定する必要があります。Amazon Cognito コンソールで新しいアプリケーションクライアントを作成すると、デフォルトでは、すべての標準属性とカスタム属性に対する読み取り/書き込み許可がアプリケーションに付与されます。アプリケーションに対する情報を必要な量のみに制限するには、アプリケーションが必要とするスコープのサブセットを選択します。
カスタム属性を使用して、アプリクライアントごとに以上の手順を繰り返します。
アプリごとに、属性を読み取り可能または書き込み可能とマークできます。これは、標準属性とカスタム属性の両方に当てはまります。アプリは、読み取り可能とマークされた属性を読み取ることができ、書き込み可能とマークされた属性を書き込むことができます。アプリが書き込み可能ではない属性を更新しようとすると、アプリは NotAuthorizedException
例外を取得します。GetUser を呼び出したアプリは、そのアプリが読み取り可能な属性のみ受け取ります。アプリからのユーザーの ID トークンには、読み取り可能な属性に対応するクレームのみが含まれます。ユーザープールの必須属性は常に書き込み可能です。AWS CLI または管理 API を使用して書き込み可能な属性を設定したが、必須属性を指定しない場合、InvalidParameterException
例外が返されます。
ユーザープールを作成した後、属性の権限と範囲を変更できます。