Manage user profiles

User profile management helps you keep your applications secure while also personalizing your app experiences. In this guide we will review how you can enable your users to personalize their profile and verify their contact information. This includes outlining how you can set up user attributes, verify them, and allow your users to delete them when necessary.

If you have not yet created an Amplify (Gen 2) app, visit the quickstart.

Set up user attributes

User attributes such as email address and phone number help you identify individual users. Defining the user attributes you include for your user profiles makes user data easy to manage at scale. This information will help you personalize user journeys, tailor content, provide intuitive account control, and more. You can capture information upfront during sign-up or enable your users to update their profile after sign-up. In this section we take a closer look at working with user attributes and how to set them up and manage them.

Add standard attributes

You can build a user profile for your users by adding OIDC standard user attributes using the amplify/auth/resource.ts file. Amazon Cognito has a set of default standard attributes that follow this standard.

Learn more

Review standard attributes options

There are many user attributes available to use by default in Cognito. Their definitions are based on the OpenID Connect specification:

address
birthdate
email
family_name
gender
given_name
locale
middle_name
name
nickname
phone_number
picture
preferred_username
profile
zoneinfo
updated_at
website

For more information, visit the AWS documentation for Amazon Cognito with a list of all the standard attributes.

The following is an example on how to add a user attribute to your authentication resources.

1// amplify/auth/resource.ts
2import { defineAuth } from '@aws-amplify/backend';
3
4export const auth = defineAuth({
5  loginWith: {
6    email: true,
7  },
8+ userAttributes: {
9+   birthdate: {
10+     required: false,
11+     immutable: true,
12+   },
13+ },
14});

By default, any attributes that you add to your amplify/auth/resource.ts file are set to not required and mutable. You can change this behavior by overriding it as shown in the following example.

1import { Auth } from '@aws-amplify/backend';
2
3export const auth = defineAuth({
4  loginWith: {
5    email: true
6  },
7  // highlight-start
8  userAttributes: {
9    // require the attribute be provided during sign-up
10    preferredUsername: {
11      required: true
12    },
13    // do not allow changing of an attribute's value
14    birthdate: {
15      immutable: true
16    }
17  }
18  // highlight-end
19});

You can also create user attributes during sign-up or when the user is authenticated. To do this as part of sign-up you can pass them in the userAttributes object of the signUp API:

1import { signUp } from 'aws-amplify/auth';
2
3async function handleSignUp() {
4  try {
5    await signUp({
6      username: 'jdoe',
7      password: 'mysecurerandompassword#123',
8      options: {
9        userAttributes: {
10          email: 'me@domain.com',
11          phone_number: '+12128601234', // E.164 number convention
12          given_name: 'Jane',
13          family_name: 'Doe',
14          nickname: 'Jane'
15        }
16      }
17    });
18  } catch (e) {
19    console.log(e);
20  }
21}

Configure custom user attributes

Custom attributes can be passed in with the userAttributes option of the signUp API:

1signUp({
2  username: 'jdoe',
3  password: 'mysecurerandompassword#123',
4  options: {
5    userAttributes: {
6      'custom:attribute_name_1': 'attribute_value_1',
7      'custom:attribute_name_2': 'attribute_value_2',
8      'custom:attribute_name_3': 'attribute_value_3'
9    }
10  }
11});

The backend authentication resource authored using defineAuth does not currently support adding custom attributes. If you wish to add custom attributes you will need to define them using overrides.

Retrieve user attributes

You can then retrieve user attributes for your users to read in their profile. This helps you personalize their frontend experience as well as control what they will see.

You can retrieve a user's latest attributes using the fetchUserAttributes API.

1import { fetchUserAttributes } from 'aws-amplify/auth';
2
3async function handleFetchUserAttributes() {
4  try {
5    const userAttributes = await fetchUserAttributes();
6    console.log(userAttributes);
7  } catch (error) {
8    console.log(error);
9  }
10}

Enable users to update, verify, and delete specific attributes

You can enable your users to update, verify, and delete specific user attributes as their information changes over time. These attributes are enabled as writable when you update the Specify write attributes in your Auth configuration.

Update user attribute

Invoke the updateUserAttribute API to create or update existing user attributes.

1import {
2  updateUserAttribute,
3  type UpdateUserAttributeOutput
4} from 'aws-amplify/auth';
5
6async function handleUpdateUserAttribute(attributeKey: string, value: string) {
7  try {
8    const output = await updateUserAttribute({
9      userAttribute: {
10        attributeKey,
11        value
12      }
13    });
14    handleUpdateUserAttributeNextSteps(output);
15  } catch (error) {
16    console.log(error);
17  }
18}
19
20function handleUpdateUserAttributeNextSteps(output: UpdateUserAttributeOutput) {
21  const { nextStep } = output;
22
23  switch (nextStep.updateAttributeStep) {
24    case 'CONFIRM_ATTRIBUTE_WITH_CODE':
25      const codeDeliveryDetails = nextStep.codeDeliveryDetails;
26      console.log(
27        `Confirmation code was sent to ${codeDeliveryDetails?.deliveryMedium}.`
28      );
29      // Collect the confirmation code from the user and pass to confirmUserAttribute.
30      break;
31    case 'DONE':
32      console.log(`attribute was successfully updated.`);
33      break;
34  }
35}

Note: If you change an attribute that requires confirmation (i.e. email or phone_number), the user will receive a confirmation code either to their email or cellphone. This code can be used with the confirmUserAttribute API to confirm the change.

Update user attributes

Invoke the updateUserAttributes API to create or update multiple existing user attributes.

1import {
2  updateUserAttributes,
3  type UpdateUserAttributesOutput
4} from 'aws-amplify/auth';
5
6async function handleUpdateEmailAndNameAttributes(
7  updatedEmail: string,
8  updatedName: string
9) {
10  try {
11    const attributes = await updateUserAttributes({
12      userAttributes: {
13        email: updatedEmail,
14        name: updatedName
15      }
16    });
17    // handle next steps
18  } catch (error) {
19    console.log(error);
20  }
21}

Verify user attribute

Some attributes require confirmation for the attribute update to complete. If the attribute needs to be confirmed, part of the result of the updateUserAttribute or updateUserAttributes APIs will be CONFIRM_ATTRIBUTE_WITH_CODE. A confirmation code will be sent to the delivery medium mentioned in the delivery details. When the user gets the confirmation code, you can present a UI to the user to enter the code and invoke the confirmUserAttribute API with their input:

1import {
2  confirmUserAttribute,
3  type ConfirmUserAttributeInput
4} from 'aws-amplify/auth';
5
6async function handleConfirmUserAttribute({
7  userAttributeKey,
8  confirmationCode
9}: ConfirmUserAttributeInput) {
10  try {
11    await confirmUserAttribute({ userAttributeKey, confirmationCode });
12  } catch (error) {
13    console.log(error);
14  }
15}

Send user attribute verification code

If an attribute needs to be verified while the user is authenticated, invoke the sendUserAttributeVerificationCode API as shown below:

1import {
2  sendUserAttributeVerificationCode,
3  type VerifiableUserAttributeKey
4} from 'aws-amplify/auth';
5
6async function handleSendUserAttributeVerificationCode(
7  key: VerifiableUserAttributeKey
8) {
9  try {
10    await sendUserAttributeVerificationCode({
11      userAttributeKey: key
12    });
13  } catch (error) {
14    console.log(error);
15  }
16}

Delete user attributes

The deleteUserAttributes API allows to delete one or more user attributes.

1import {
2  deleteUserAttributes,
3  type DeleteUserAttributesInput
4} from 'aws-amplify/auth';
5
6async function handleDeleteUserAttributes(
7  keys: DeleteUserAttributesInput['userAttributeKeys']
8) {
9  try {
10    await deleteUserAttributes({
11      userAttributeKeys: ['custom:my_custom_attribute', ...keys]
12    });
13  } catch (error) {
14    console.log(error);
15  }
16}

By following the above steps your users can now update, verify, and delete specific user attributes as their information changes over time.

Conclusion

Congratulations! You finished the Manage user profiles guide and your users can now review and customize their profile information.

Next steps

Now that you completed setting up user profile management, you may also want to add some additional features. We recommend: