メニュー
Amazon Cognito
開発者ガイド (Version 最終更新日: 2017 年 8 月 26 日)

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

すべてのユーザープールで「標準属性」と呼ばれる一連のデフォルトの属性を取得します。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 ~ 20 文字です。

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

注記

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

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

email

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

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

phone

電話番号は多要素認証 (MFA) を有効にした場合に要求されます。詳細については、「Multi-factor Authentication (MFA)」を参照してください。

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

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

重要

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

preferred_username

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

 

標準属性を編集するには

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

    重要

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

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

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

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

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

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

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

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

  • 検証済みの電話番号

  • 優先ユーザー名

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

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

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

  1. [Attributes] タブの、[How do you want your end users to sign-up and sign-in?] で、[Username] を選択します。

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

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

    • Also allow sign in with verified phone number: ユーザーが自分の電話番号を使用してサインインすることを許可します。

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

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

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

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

注記

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

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

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

  1. [Attributes] タブの、[How do you want your end users to sign-up and sign-in?] で、[Email address or phone number] を選択します。

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

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

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

    • Allow both email addresses and phone number (users can choose one): ユーザーがサインアップ中にユーザー名として 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~20 文字の任意の文字列です。

カスタム属性は、ユーザープールに追加された後は削除や変更はできません。

注記

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

カスタム属性を追加するには

  1. カスタム属性を追加する場合は、[Do you want to use custom attributes?] セクションを開き、[Add custom attribute] を選択します。

  2. カスタム属性ごとに、データの (文字列か数値か)、名前最小長最大長などのプロパティを指定できます。

  3. ユーザーが提供したカスタム属性の値を、後で変更することを許可するには、[Mutable] を選択します。

  4. より多くの属性を追加するには、[Add another attribute] を選択します。

属性の権限と範囲

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

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

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