ユーザープール属性 - Amazon Cognito
標準属性ユーザー名および優先ユーザー名ログイン属性のカスタマイズカスタム属性属性の権限と範囲

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

ユーザープール属性

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

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

注記

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

標準属性

Amazon Cognito は、[OpenID Connect の仕様] に基づいて、以下の標準属性セットをすべてのユーザーに割り当てます。標準属性値およびカスタム属性値は、デフォルトでは最大 2048 文字の任意の文字列ですが、一部の属性値には形式の制限があります。

標準属性は以下のとおりです。

  • address

  • birthdate

  • email

  • family_name

  • gender

  • given_name

  • locale

  • middle_name

  • name

  • nickname

  • phone_number

  • picture

  • preferred_username

  • profile

  • sub

  • updated_at

  • website

  • zoneinfo

sub を除き、標準属性はすべてのユーザーに対してデフォルトでオプションとなります。属性を必須にする場合は、ユーザープールの作成プロセスで、属性の横にある [必須] チェックボックスをオンにします。Amazon Cognito は、各ユーザーの sub 属性に一意のユーザー識別子の値を割り当てます。検証できるのは E メールと phone_number 属性だけです。

注記

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

標準属性の詳細と形式の制限
birthdate

値は、YYYY-MM-DD 形式で有効な 10 文字の日付にする必要があります。

email

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

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

値は、@ 記号とドメインを含む標準の電子メール形式に従った有効な E メールアドレス文字列で、長さは 2048 文字までです。

phone_number

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

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

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

重要

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

preferred_username

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

sub

sub 属性に基づいてユーザーをインデックス化して検索します。sub 属性は、各ユーザープール内で一意のユーザー識別子です。ユーザーは phone_number や email などの属性を変更できます。sub 属性には固定値が含まれています。ユーザーの検索の詳細については、「ユーザーアカウントの管理と検索」を参照してください。

必須属性を表示する

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

注記

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

必須属性を表示する

  1. の Amazon Cognito に移動します AWS Management Console。コンソールでプロンプトが表示されたら、 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 は再利用できますが、削除されて使用されなくなった場合のみです。username 属性の文字列制約の詳細については、SignUp「API リクエストのユーザー名プロパティ」を参照してください。

ログイン属性のカスタマイズ

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

重要

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

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

要件 エイリアス属性 ユーザー名属性
ユーザーには複数のサインイン属性があります Yes¹ No²
ユーザーは、サインインする前に E メールアドレスまたは電話番号を確認する必要があります はい いいえ
重複する E メールアドレスまたは電話番号でユーザーをサインアップし、UsernameExistsExceptionエラーを防ぐ3 はい いいえ
複数のユーザーに同じ E メールアドレスまたは電話番号属性値を割り当てることができます あり⁴ いいえ

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

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

³ ユーザーが登録したメールアドレスや電話番号が重複している可能性があるが、ユーザー名がない場合、ユーザープールで UsernameExistsException エラーが生成されません。この動作はユーザー名存在エラーを防ぐとは無関係です。これはサインイン操作には適用されますが、サインアップ操作には適用されません。

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

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

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

注記

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

エイリアスとして 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 メールアドレス

  • 検証済みの電話番号

  • 優先ユーザー名

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

重要

ユーザープールがエイリアスによるサインインをサポートしている場合、ユーザーを認証または検索するときに、サインイン属性のいずれかを使用してユーザーを特定することは避けてください。固定値のユーザー識別子 sub は、ユーザーのアイデンティティを示す唯一の一貫した指標です。

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

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

  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. [ユーザー名の要件] で、[優先ユーザー名を使用したサインインを許可する] を選択して、ユーザーがサインイン時に代替ユーザー名を設定できるようにします。

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

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

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

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

注記

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

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

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: プレフィックスを必要とします。

ユーザープールを作成するときに、 の SchemaAttributesプロパティにデベロッパー属性を追加することもできますCreateUserPool。開発者属性には dev: プレフィックスがあります。ユーザーのデベロッパー属性は、 AWS 認証情報でのみ変更できます。開発者属性はレガシー機能であり、Amazon Cognito がアプリケーションクライアントの読み取り/書き込み権限と置き換えました。

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

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

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

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

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

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

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

    • 名前を入力します。

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

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

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

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

  6. [変更を保存] を選択します。

属性の権限と範囲

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

ベストプラクティスとして、アプリケーションクライアントを作成するときに属性の読み取りおよび書き込みアクセス許可を指定します。アプリケーションのオペレーションに必要な最小限のユーザー属性セットへのアクセス権をアプリケーションクライアントに付与します。

注記

DescribeUserPoolClient は、デフォルト以外のアプリケーションクライアントのアクセス許可を設定するWriteAttributes場合にのみ、 ReadAttributesと の値を返します。

属性権限を更新するには (AWS Management Console)

  1. の Amazon Cognito に移動します AWS Management Console。コンソールでプロンプトが表示されたら、 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] (変更の保存) を選択します。

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

アプリごとに、属性を読み取り可能または書き込み可能とマークできます。これは、標準属性とカスタム属性の両方に当てはまります。アプリは、読み取り可能としてマークした属性の値を取得したり、書き込み可能としてマークした属性の値を設定または変更したりできます。書き込み権限のない属性の値をアプリが設定しようとすると、Amazon Cognito が NotAuthorizedException を返します。GetUser リクエストには、アプリケーションクライアントクレームを含むアクセストークンが含まれます。Amazon Cognito は、アプリケーションクライアントが読み取ることができる属性の値のみを返します。アプリからのユーザーの ID トークンには、読み取り可能な属性に対応するクレームのみが含まれます。すべてのアプリケーションクライアントは、ユーザープールの必須属性を書き込むことができます。Amazon Cognito ユーザープール API リクエストで属性の値を設定できるのは、まだ値が設定されていない必須属性の値も指定する場合のみに限られます。

カスタム属性の読み取り書き込みアクセス許可にはそれぞれ異なる機能があります。ユーザープールの変更可能な属性または変更不可能な属性として作成でき、どのアプリクライアントでも読み取りまたは書き込み属性として設定できます。

変更不可能なカスタム属性は、ユーザー作成時に 1 回だけ更新できます。変更不可能な属性には以下のメソッドを入力できます。

  • SignUp: ユーザーは、変更不可能なカスタム属性への書き込みアクセス許可を持つアプリクライアントにサインアップします。その属性の値を提供します。

  • サードパーティ IdP でのサインイン: ユーザーは、変更不可能なカスタム属性への書き込みアクセス許可を持つアプリクライアントにサインインします。IdP のユーザープール設定には、提供されたクレームを変更不可能な属性にマップするルールがあります。

  • AdminCreateUser: 変更不可能な属性の値を指定します。

アプリケーションクライアントに割り当てることができるスコープについては、「スコープ、M2M 、およびリソースサーバーによる API 認証」を参照してください。

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