使用使用者屬性 - Amazon Cognito
標準屬性使用者名稱和偏好的使用者名稱自訂登入屬性自訂屬性屬性許可和範圍

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用使用者屬性

屬性是協助您識別個別使用者的細項資訊，例如名稱、電子郵件地址和電話號碼。新使用者集區具有一組預設的標準屬性。您也可以將自訂屬性新增至 中的使用者集區定義 AWS Management Console。此主題會詳細說明那些屬性，並提供設定使用者集區的秘訣。

請勿將所有的使用者相關資訊都存放在屬性中。例如，將經常變更的使用者資料，例如用量統計資料或遊戲分數，保存在個別的資料存放區中，例如 Amazon Cognito Sync 或 Amazon DynamoDB。

注意

某些文件和標準將屬性稱為成員。

標準屬性

Amazon Cognito 會根據 OpenID Connect 規格為所有使用者指派一組標準屬性。根據預設，標準和自訂屬性值可以是長度上限 2048 個字元的任何字串，但某些屬性值有格式限制。

標準屬性包括：

  • name

  • family_name

  • given_name

  • middle_name

  • nickname

  • preferred_username

  • profile

  • picture

  • website

  • gender

  • birthdate

  • zoneinfo

  • locale

  • updated_at

  • address

  • email

  • phone_number

  • sub

除了 sub，所有使用者的標準屬性預設都是選用的。若要設定為必要屬性，請在使用者集區建立程序期間，勾選屬性旁邊的 Required (必要) 核取方塊。Amazon Cognito 會為每個使用者的 sub 屬性指派唯一的使用者識別碼值。只有 email 和 phone_number 屬性能夠驗證。

標準屬性具有預先定義的屬性，您可以在DescribeUserPool API回應 的 SchemaAttributes 參數中檢視這些屬性。您可以為這些屬性屬性設定自訂值，例如資料類型、可變性和長度限制。若要修改標準屬性，請在CreateUserPool 結構描述參數 中設定其自訂值。結構描述也是您設定必要屬性的地方。當您在 Amazon Cognito 主控台中建立使用者集區時，您無法修改標準屬性的屬性。

注意

將標準屬性標示為 Required (必要) 後，使用者必須提供該屬性的值，才能註冊。若要建立使用者，而不是提供必要屬性的值，管理員可以使用 AdminCreateUser API。建立使用者集區之後，您便無法讓屬性在必要和非必要之間切換。

標準屬性詳細資訊和格式限制
birthdate

值必須是格式為 的有效 10 個字元日期 YYYY-MM-DD。

email

使用者和管理員可以驗證電子郵件地址值。

具有適當 AWS 帳戶 許可的管理員可以變更使用者的電子郵件地址，並將其標記為已驗證。使用 AdminUpdateUserAttributesAPI或 admin-update-user-attributes AWS Command Line Interface （AWS CLI） 命令將電子郵件地址標記為已驗證。管理員可以使用此命令將 email_verified 屬性變更為 true。您也可以在 的使用者索引標籤中編輯使用者 AWS Management Console ，將電子郵件地址標記為已驗證。

值必須是遵循標準電子郵件格式的有效電子郵件地址字串，包含 @ 符號和網域，且長度上限為 2048 個字元。

phone_number

如果SMS多重要素身分驗證 （MFA） 處於作用中狀態，使用者必須提供電話號碼。如需詳細資訊，請參閱MFA 新增至使用者集區。

使用者和管理員可以驗證電話號碼值。

具有適當 AWS 帳戶 許可的管理員可以變更使用者的電話號碼，並將其標記為已驗證。將電話號碼標示為使用 AdminUpdateUserAttributesAPI或 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. 從清單中選擇現有的使用者集區。

  4. 選擇 Sign-up experience (註冊體驗) 標籤。

  5. 在 Required attributes (必要的屬性) 區段中，檢視使用者集區的必要屬性。

使用者名稱和偏好的使用者名稱

username 值是另一個屬性，不同於 name 屬性。每個使用者都有 username 屬性。Amazon Cognito 會自動為聯合身分使用者產生使用者名稱。您必須提供 username 屬性，以便在 Amazon Cognito 目錄中建立本機使用者。在您建立使用者之後，您無法變更 username 屬性。

開發人員可以使用 preferred_username 屬性，以提供使用者可以變更的使用者名稱。如需詳細資訊，請參閱自訂登入屬性。

如果您的應用程式不需要使用者名稱，則不需要求使用者提供。您的應用程式可以在背景為使用者建立唯一的使用者名稱。如果您希望使用者以電子郵件地址和密碼來註冊及登入，這會非常有用。如需詳細資訊，請參閱自訂登入屬性。

username 在使用者集區中必須是唯一的。username 只有在其已遭刪除且不再使用的情況下方可重新使用。如需username屬性的字串限制資訊，請參閱 SignUp API 請求的使用者名稱屬性。

自訂登入屬性

建立使用者集區時，如果您希望使用者以電子郵件地址或電話號碼做為使用者名稱進行註冊和登入，可以設定使用者名稱屬性。或者，您可以設定別名屬性，為使用者提供選項：他們可以在註冊時包含多個屬性，然後以使用者名稱、偏好的使用者名稱、電子郵件地址或電話號碼登入。

重要

建立使用者集區之後，您就無法變更此設定。

如何在別名屬性和使用者名稱屬性之間進行選擇

您的要求 別名屬性 使用者名稱屬性
使用者具有多個登入屬性 是1 No2
使用者必須先驗證電子郵件地址或電話號碼，才能登入 是 否
使用重複的電子郵件地址或電話號碼註冊使用者，並防止UsernameExistsException錯誤3 是 否
可以將相同的電子郵件地址或電話號碼屬性值指派給多個使用者 是⁴ 否

¹ 可用的登入屬性為使用者名稱、電子郵件地址和偏好的使用者名稱。

² 可以使用電子郵件地址或電話號碼登入。

³ 使用者使用可能重複的電子郵件地址或電話號碼註冊，但沒有使用者名稱時，使用者集區不會產生 UsernameExistsException 錯誤。這種行為與防止使用者名稱存在錯誤無關，它適用於登入，但不適用於註冊操作。

⁴ 只有最後一位已驗證屬性的使用者才能使用該屬性登入。

如果您想讓使用者在登入時選擇輸入其使用者名稱或其他屬性值，則可以啟動別名。根據預設，使用者會使用其使用者名稱和密碼來登入。使用者名稱是使用者無法變更的固定值。如果您將屬性標記為別名，使用者就可以使用該屬性代替使用者名稱來登入。您可以將電子郵件地址、電話號碼和偏好的使用者名稱屬性標記為別名。例如，如果您為使用者集區選擇將電子郵件和電話號碼做為別名，該使用者集區中的使用者就可以使用其使用者名稱、電子郵件地址或電話號碼並搭配其密碼來登入。

若要選擇別名屬性，請在建立使用者集區時選取 User name (使用者名稱) 和至少另一個登入選項。

注意

當您將使用者集區設定為不區分大小寫時，使用者可以使用小寫或大寫字母來註冊或使用別名登入。如需詳細資訊，請參閱 Amazon Cognito 使用者集區API參考 CreateUserPool中的 。

如果您選取電子郵件地址做為別名，Amazon Cognito 不會接受與有效電子郵件地址格式相符的使用者名稱。同樣地，如果您選擇電話號碼做為別名，Amazon Cognito 不會接受與有效電話號碼格式相符的使用者集區的使用者名稱。

注意

別名值在使用者集區中必須是唯一的。如果您為電子郵件地址或電話號碼設定別名，所提供的值只能在一個帳戶中是已驗證狀態。註冊期間，如果您的使用者提供電子郵件地址或電話號碼做為別名值，而另一個使用者已使用該別名值，則註冊會成功。不過，當使用者嘗試使用此電子郵件 (或電話號碼) 來確認帳戶，並輸入有效的驗證碼時，Amazon Cognito 會傳回 AliasExistsException 錯誤。該錯誤會向使用者指出使用此電子郵件地址 (或電話號碼) 的帳戶已存在。此時，使用者可以放棄嘗試建立新帳戶，並改為嘗試為舊帳戶重設密碼。如果使用者繼續建立新帳戶，您的應用程式必須使用 ConfirmSignUp API forceAliasCreation選項呼叫 。 會將別名從上一個帳戶ConfirmSignUpforceAliasCreation移至新建立的帳戶，並在上一個帳戶中標記未驗證的屬性。

電話號碼和電子郵件地址只有在經過使用者驗證後，才會成為使用者的作用中別名。如果要使用電子郵件地址和電話號碼做為別名，建議您選擇自動驗證。

選擇別名屬性，以防止使用者註冊時發生電子郵件地址和電話號碼屬性 UsernameExistsException 錯誤。

啟用 preferred_username 屬性，以便您的使用者可以變更用於登入的使用者名稱，而 username 屬性值不會變更。如果您想要設定此使用者體驗，請提交新的 username值做為 preferred_username，並選擇 preferred_username 做為別名。如此一來，使用者就可以使用其輸入的新值來登入。如果您選取 preferred_username 做為別名，則使用者只有在確認帳戶後，才能提供該值。使用者在註冊期間無法提供該值。

當使用者以使用者名稱進行註冊時，您可以選擇使用者是否可以使用下列一或多個別名來登入。

  • 已驗證的電子郵件地址

  • 已驗證的電話號碼

  • 偏好的使用者名稱

使用者完成註冊之後，便可以變更這些別名。

重要

在您的使用者集區支援使用別名登入，且您想授權或查詢使用者時，請勿透過使用者的任何登入屬性來識別您的使用者。固定值使用者識別符 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 (電子郵件) 和 Phone number (電話號碼) 的任意組合。

  6. 在 使用者名稱要求 下，選擇 允許使用以偏好的使用者名稱登入，讓您的使用者可以設定登入時使用的替代使用者名稱。

  7. 選擇 Next (下一步)，然後完成精靈中的所有步驟。

當使用者以電子郵件地址或電話號碼做為使用者名稱進行註冊時，您可以選擇使用者是否可以僅使用電子郵件地址、僅電話號碼或兩者之一來註冊。

若要選擇使用者名稱屬性，請勿在建立使用者集區時選取 使用者名稱 做為登入選項。

電子郵件地址或電話號碼必須是唯一的，而且不能是已由其他使用者所使用。這不需要驗證。使用者以電子郵件地址或電話號碼註冊之後，即無法以相同的電子郵件地址或電話號碼來建立新帳戶。使用者只能重複使用現有的帳戶，並依需要重設帳戶密碼。不過，使用者可以將電子郵件地址或電話號碼變更為新的電子郵件地址或電話號碼。如果電子郵件地址或電話號碼尚未使用，就會變成新的使用者名稱。

注意

如果使用者以電子郵件地址做為使用者名稱來註冊，使用者可以將使用者名稱變更為另一個電子郵件地址，但不能將其變更為電話號碼。如果使用者以電話號碼來註冊，則可以將使用者名稱變更為另一個電話號碼，但不能將其變更為電子郵件地址。

在使用者集區建立程序期間使用下列步驟，以設定使用電子郵件地址或電話號碼來註冊及登入。

將使用者集區設定為以電子郵件地址或電話號碼來註冊及登入

  1. 前往 AWS Management Console中的 Amazon Cognito。如果主控台提示您，請輸入您的 AWS 憑證。

  2. 選擇 User Pools (使用者集區)。

  3. 在頁面右上角，選擇 Create a user pool (建立使用者集區)，以開始建立使用者集區精靈。

  4. 在 Cognito user pool sign-in options (Cognito 使用者集區登入選項) 下，選擇 Email (電子郵件) 和 Phone number (電話號碼) 的任意組合，組合代表使用者可用於登入的屬性。

  5. 選擇 Next (下一步)，然後完成精靈中剩餘的步驟。

注意

您不需要將電子郵件地址或電話號碼標記為使用者集區的必要屬性。

在您的應用程式中實作選項 2

  1. 呼叫 CreateUserPoolAPI以建立您的使用者集區。將 UserNameAttributes 參數設定為 phone_number、email 或 phone_number | email。

  2. 呼叫 ，SignUpAPI並在 的 username 參數中傳遞電子郵件地址或電話號碼API。這會API執行下列動作：

    • 如果 username 字串是有效的電子郵件地址格式，使用者集區就會自動在使用者的 email 屬性中填入 username 值。

    • 如果 username 字串是有效的電話號碼格式，使用者集區會自動在使用者的 phone_number 屬性中填入 username 值。

    • 如果username字串格式不是電子郵件地址或電話號碼格式， SignUpAPI會傳回例外狀況。

    • UUID 會為您的使用者SignUpAPI產生持久性，並在內部將其用作不可變的使用者名稱屬性。這UUID與使用者身分字符中的sub宣告具有相同的值。

    • 如果username字串包含已在使用的電子郵件地址或電話號碼， 會SignUpAPI傳回例外狀況。

您可以使用電子郵件地址或電話號碼作為別名，取代ListUsers除 APIs以外的所有使用者名稱API。當您呼叫 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. 從清單中選擇現有的使用者集區。

  4. 選擇 Sign-up experience (註冊體驗) 索引標籤，然後在 Custom attributes (自訂屬性) 區段中，選擇 Add custom attributes (新增自訂屬性)。

  5. 在 Add custom attributes (新增自訂屬性) 頁面中，提供下列有關新屬性的詳細資訊：

    • 輸入 Name (名稱)。

    • 選取 Type (類型) 為 String (字串) 或 Number (數字)。

    • 輸入 Min (最小) 字串長度或數字值。

    • 輸入 Max (最大) 字串長度或數字值。

    • 如果您想要許可使用者在設定初始值之後，可以變更自訂屬性的值，請選擇 Mutable (可變)。

  6. 選擇 Save changes (儲存變更)。

屬性許可和範圍

針對每個應用程式用戶端，您可以設定每個使用者屬性的讀取和寫入許可。透過這種方式，您可以控制任何應用程式所擁有讀取和修改您為使用者所存放每個屬性的存取權。例如，您有一個自訂屬性指出使用者是否為付費客戶。您的應用程式可能可以看到此屬性，但不能直接變更。反之，您會使用管理工具或背景處理程序來更新此屬性。您可以從 Amazon Cognito 主控台、Amazon Cognito API或 設定使用者屬性的許可 AWS CLI。預設情況下，除非您設定自訂屬性的讀取和寫入許可，否則任何新的自訂屬性都無法使用。根據預設，當您建立新的應用程式用戶端時，您會授予應用程式所有標準和自訂屬性的讀取和寫入許可。若要限制應用程式只能擁有所需的資訊量，請在應用程式用戶端組態中指派特定許可給屬性。

最佳實務是，在建立應用程式用戶端時指定屬性讀取和寫入許可。授予應用程式用戶端存取應用程式操作所需的最低使用者屬性集。

注意

DescribeUserPoolClient 只會在您設定預設值以外的應用程式用戶端許可WriteAttributes時傳回 ReadAttributes和 的值。

若要更新屬性許可 (AWS Management Console)

  1. 前往 中的 Amazon Cognito AWS Management Console。如果主控台提示您，請輸入您的 AWS 憑證。

  2. 選擇 User Pools (使用者集區)。

  3. 從清單中選擇現有的使用者集區。

  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請求中設定屬性的值。

自訂屬性對於讀取和寫入許可擁有不同的功能。您可針對使用者集區建立可變或不可變的屬性，也可以將其設定為任何應用程式用戶端的讀取或寫入屬性。

不可變的自訂屬性可在使用者建立期間更新一次。您可以使用以下方法填入不可變屬性。

  • SignUp：使用者在具有不可變自訂屬性的寫入存取權的應用程式用戶端註冊。使用者會為該屬性提供值。

  • 使用第三方 IdP 登入：使用者在具有不可變自訂屬性的寫入存取權的應用程式用戶端登入。您對於其 IdP 的使用者集區組態設有一項規則，會將提供的宣告映射至不可變屬性。這雖然可行，但並不實用，因為使用者只能登入一次。第一次登入嘗試後，Amazon Cognito 會拒絕嘗試，因為 會將規則對應至現在無法寫入的屬性。

  • AdminCreateUser：您為不可變屬性提供值。

使用範圍屬性許可

在您使用 AWS SDK或 CDK、 REST API或 設定的使用者集區中 AWS CLI，您可以設定具有OIDC範圍 的應用程式用戶端讀取或寫入存取權oidc:profile。oidc:profile 授予對下列標準屬性的讀取或寫入存取權：

  • name

  • family_name

  • given_name

  • middle_name

  • nickname

  • preferred_username

  • profile

  • picture

  • website

  • gender

  • birthdate

  • zoneinfo

  • locale

此清單是OIDC標準屬性減去 email、sub、 phone_number和 address，如OIDC規格 第 2.4 節所定義。如需可指派至應用程式用戶端的範圍相關資訊，請參閱 Scopes、M2M 和 APIs搭配資源伺服器。

若要將應用程式用戶端設定為寫入 oidc:profile範圍內的屬性，請將 值設定為 WriteAttributes oidc:profile，以及您想要允許應用程式在 CreateUserPoolClient或 UpdateUserPoolClientAPI請求中修改的任何其他屬性。同樣地，若要授予這些屬性的讀取存取權，請將 oidc:profile新增至 的值ReadAttributes。

您可以在使用者集區建立之後，變更屬性的許可和範圍。