Amazon Cognito
開発者ガイド

ユーザープールの属性の設定

すべてのユーザープールで「標準属性」と呼ばれる一連のデフォルトの属性を取得します。AWS マネジメントコンソールのユーザープール定義には、カスタム属性を追加することもできます。このトピックでは、それらの属性について詳しく説明し、ユーザープールの設定のヒントを示します。

属性は、名前、E メール、電話番号など、個々のユーザーを識別できる各種情報です。

ユーザーに関するすべての情報が属性に保存されるわけではありません。たとえば、使用統計やゲームスコアなど、頻繁に変化するユーザーデータは、Amazon Cognito Sync や Amazon DynamoDB など別個のデータストアに保持する必要があります。

標準属性

以下は、ユーザープールのすべてのユーザーに対する標準属性です。これらは OpenID Connect 仕様に従って実装されています。

  • address

  • birthdate

  • email

  • family_name

  • gender

  • given_name

  • locale

  • middle_name

  • name

  • nickname

  • phone_number

  • picture

  • preferred_username

  • profile

  • timezone

  • updated_at

  • website

これらの属性は、すべてのユーザーに対してオプションの属性として利用できます。属性を必須にする場合は、属性の横にあるチェックボックスを選択します。

注記

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

カスタム属性名の長さは 1 ~ 32 文字です。

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

注記

仕様では、属性はメンバーと呼ばれています。

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

email

メールアドレス値は検証できます。

適切な AWS アカウントのアクセス権限を持つ管理者がユーザーのメールを変更しそれを検証済みとしてマークできます。これは、AdminUpdateUserAttributes API または admin-update-user-attributes CLI コマンドを使用して email_verified 属性を true に変更することにより行うことができます。

phone

電話番号は SMS Multi-Factor Authentication (MFA) を有効にした場合に要求されます。詳細については、「多要素認証 (MFA) をユーザープールに追加する」を参照してください。

電話番号の値は検証できます。

適切な AWS アカウントのアクセス権限を持つ管理者がユーザーの電話番号を変更しそれを検証済みとしてマークできます。これは、AdminUpdateUserAttributes API または admin-update-user-attributes CLI コマンドを使用して phone_verified 属性を true に変更することにより行うことができます。

重要

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

preferred_username

preferred_username を必須およびエイリアスの両方として選択することはできません。preferred_username がエイリアスである場合、ユーザーは、UpdateUserAttributes API を使用して確認されると、属性値を追加できます。

 

標準属性を編集するには

  1. [属性] タブで、ユーザー登録に必要な属性を選択します。属性が必須であり、ユーザーがその必須属性を指定しない場合、登録できません。

    重要

    ユーザープールが作成された後に、これらの要件を変更することはできません。詳細については、「ユーザープールの属性の設定」を参照してください。

  2. E メール、電話番号、アドレス、または任意のユーザー名を作成するには、[エイリアス] を選択します。エイリアスの詳細については、「エイリアスの概要」を参照してください。

  3. 続いて「カスタム属性」を作成します。

 

ユーザー名および優先ユーザー名

username 値は個別の属性であり、name 属性とは異なります。username はユーザーを登録するために常に必要であり、ユーザーが作成された後に変更することはできません。

開発者は、preferred_username 属性を使用して、変更可能なユーザー名をユーザーに付与できます。詳細については、「エイリアスの概要」を参照してください。

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

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

エイリアスの概要

エンドユーザーがエイリアスを使用して複数の識別子でサインインする権限を与えることができます。

デフォルトでは、ユーザーは各自のユーザー名とパスワードでサインインします。ユーザー名はユーザーが変更できない固定値です。属性をエイリアスとしてマーキングすると、ユーザーはユーザー名の代わりにその属性を使用してサインインできます。E メールアドレス、電話番号、および任意ユーザー名属性は、エイリアスレコードとしてマーキングできます。

たとえば、E メールと電話をユーザープールのエイリアスとして選択すると、そのユーザープールのユーザーは、自分のユーザー名、E メールアドレス、または電話番号とパスワードを使ってサインインできます。

メールアドレスがエイリアスとして選ばれる場合、ユーザー名を有効な E メール形式と一致させることはできません。同様に、電話番号をエイリアスとして選択した場合は、有効な電話番号パターンに一致するユーザー名はそのユーザープールのサービスで受け入れられません。

注記

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

電話番号およびメールアドレスが確認された後、電話番号およびメールアドレスのみがユーザーのアクティブエイリアスになります。そのため、エイリアスとしてこれらを使用する場合は、メールアドレスと電話番号の自動確認を選択することをお勧めします。preferred_username 属性を使用することで、ユーザーは実際のユーザー名の値が変更できない場合に、自分のユーザー名を変更する利便性を得ることができます。

このユーザーエクスペリエンスを有効にする場合は、新しい username 値を preferred_username として送信し、エイリアスとして preferred_username を選択します。こうすることで、ユーザーは入力した新しい値でサインインできます。

preferred_username がエイリアスとして選択された場合、アカウントが確認されている場合にのみ、値を指定できます。登録時にはこの値は指定できません。

エイリアスを使用したユーザーのサインアップとサインインの簡素化

[属性] コンソール・タブで、ユーザーがサインアップ時に E メールアドレスまたは電話番号をユーザー名として使用してサインアップすることを許可するかどうかを選択できます。

注記

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

オプション 1: ユーザーはユーザー名を使用してサインアップし、ユーザー名またはエイリアスを使用してサインインする

この場合、ユーザーはユーザー名を使用してサインアップします。また、任意でユーザーが次の 1 つ以上のエイリアスを使用してサインインすることを許可できます。

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

  • 検証済みの電話番号

  • 優先ユーザー名

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

次のステップを使用して、エイリアスを使用したサインインを許可するようにユーザープールをコンソールで設定します。

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

  1. [属性] タブの [How do you want your end users to sign-up and sign-in? (どのようにエンドユーザーがサインアップしてサインインするようにしますか)] で、[ユーザー名] を選択します。

  2. 次のいずれかのオプションを選択します。

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

    • [検証済みの電話番号でのサインインも許可]: ユーザーが自分の電話番号を使用してサインインすることを許可します。

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

オプション 2: ユーザーはユーザー名の代わりに E メールまたは電話番号を使用してサインアップおよびサインインする

この場合、ユーザーは E メールアドレスまたは電話番号をユーザー名として使用してサインアップします。E メールアドレスのみ、電話番号のみ、どちらか 1 つを使用したサインアップを許可するかどうかを選択できます。

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

注記

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

次のステップを使用して、E メールまたは電話番号を使用したサインアップおよびサインインを許可するようにユーザープールをコンソールで設定します。

E メールまたは電話番号を使用したサインアップおよびサインインをユーザープールで設定するには

  1. [属性] タブの [How do you want your end users to sign-up and sign-in? (どのようにエンドユーザーがサインアップしてサインインするようにしますか)] で、[E メールアドレスあるいは電話番号] を選択します。

  2. 次のいずれかのオプションを選択します。

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

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

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

注記

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

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

  1. CreateUserPool API を呼び出してユーザープールを作成します。UserNameAttributes パラメータを phone_numberemail、または 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 で検索する場合は、エイリアスではなく実際のユーザー名を指定する必要があります。

カスタム属性

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

各カスタム属性は:

  • 文字列または数値として定義できます。

  • 名前として 1〜32 文字の文字列を使用できます。

  • 必須にすることはできません。

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

注記

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

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

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

  2. 新しい属性ごとに以下を行います。

    1. [カスタム属性を追加しますか?] の下で [別の属性の追加] を選択します。

    2. カスタム属性ごとに、データ (文字列または数値)、名前最小長最大長などのプロパティを選択します。

    3. カスタム属性の値を指定した後で、値を変更することをユーザーに許可する場合は、[変更可能] を選択します。

属性の権限と範囲

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

コンソールを使用して属性のアクセス許可を設定または変更するには

  1. 左のナビゲーションバーから [アプリクライアント] を選択します。

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

  3. [Set the attribute read and write permissions for each attribute (属性ごとに属性の読み取り/書き込みのアクセス許可を設定する)] を選択します。

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

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

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

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