add docs for auth custom attribute support (#7846)

* add docs for auth custom attribute support * Update src/pages/[platform]/build-a-backend/auth/concepts/user-attributes/index.mdx * correct heading order * fix broken links * add mobile platform to concepts page for user attributes
aws-amplify · Jul 26, 2024 · ab3d9e9 · ab3d9e9
1 parent a4e7b13
commit ab3d9e9
Show file tree

Hide file tree

Showing 3 changed files with 90 additions and 64 deletions.
diff --git a/src/pages/[platform]/build-a-backend/auth/concepts/user-attributes/index.mdx b/src/pages/[platform]/build-a-backend/auth/concepts/user-attributes/index.mdx
@@ -4,14 +4,14 @@ export const meta = {
   title: 'User attributes',
   description: 'Learn more about what Amplify Auth provisions and supports',
   platforms: [
-    // 'android',
+    'android',
     'angular',
-    // 'flutter',
+    'flutter',
     'javascript',
     'nextjs',
     'react',
-    // 'react-native',
-    // 'swift',
+    'react-native',
+    'swift',
     'vue'
   ]
 };
@@ -28,10 +28,16 @@ export function getStaticProps() {
   };
 }
 
-Amplify Auth stores user profile information in user attributes. When the default method for user sign-in, Amplify Auth will automatically configure an `email` or `phone_number` attribute that is required for sign-in.
+Amplify Auth stores user profile information in user attributes. When the default method for user sign-in, Amplify Auth will automatically configure an `email` or `phoneNumber` attribute that is required for sign-in.
 
 {/* what standard attributes are */}
-To extend a user profile beyond the default `email` or `phone_number` attribute that is automatically configured when specified in your auth resource's `loginWith` property, you can configure attributes with the `userAttributes` property:
+To extend a user profile beyond the default `email` or `phoneNumber` attribute that is automatically configured when specified in your auth resource's `loginWith` property, you can configure attributes with the `userAttributes` property:
+
+<Callout warning>
+
+**Warning**: After you create your auth resource, you cannot switch an attribute between required and not required.
+
+</Callout>
 
 ```ts title="amplify/auth/resource.ts"
 import { defineAuth } from "@aws-amplify/backend"
@@ -53,16 +59,61 @@ export const auth = defineAuth({
 })
 ```
 
+## Standard attributes
+
 User attributes are defined as [Cognito Standard Attributes](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html#cognito-user-pools-standard-attributes). Attributes can be configured to be _required_ for user sign-up in addition to whether the values are _mutable_. When configuring your resource to allow your users to login with `email`, an email must be specified for user sign-up and cannot be changed later. However additional attributes can be configured to be optional, and mutable after sign-up.
 
-<Callout warning>
+## Custom attributes
 
-**Warning**: After you create your auth resource, you cannot switch an attribute between required and not required.
+In addition to the provided standard attributes, you can configure [Custom Attributes](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html#user-pool-settings-custom-attributes). These are attributes that are typically unique to your use case, such as a tenant ID or a user's display name. Custom attributes are identified by the `custom:` prefix:
 
-</Callout>
+```ts title="amplify/auth/resource.ts"
+import { defineAuth } from "@aws-amplify/backend"
+
+export const auth = defineAuth({
+  loginWith: {
+    // this configures a required "email" attribute
+    email: true,
+  },
+  userAttributes: {
+    // highlight-start
+    "custom:display_name": {
+      dataType: "String",
+      mutable: true,
+      maxLen: 16,
+      minLen: 1,
+    },
+    "custom:favorite_number": {
+      dataType: "Number",
+      mutable: true,
+      min: 1,
+      max: 100,
+    },
+    "custom:is_beta_user": {
+      dataType: "Boolean",
+      mutable: true,
+    },
+    "custom:started_free_trial": {
+      dataType: "DateTime",
+      mutable: true,
+    },
+    // highlight-end
+  },
+})
+```
+
+Unlike standard attributes, custom attributes cannot natively be required for sign-up, however can be codified to require some value by [validating user attributes upon sign-up with a pre sign-up trigger](/[platform]/build-a-backend/functions/examples/user-attribute-validation/).
+
+Custom attributes can also be configured with specific data types. The following data types are supported:
+
+- `String`
+- `Number`
+- `Boolean`
+- `DateTime`
 
-In addition to the provided standard attributes, you can configure [Custom Attributes](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-settings-attributes.html#user-pool-settings-custom-attributes). These are attributes that are typically unique to your use case, such as a tenant ID. Currently Amplify Auth does not support custom attributes in the `userAttributes` property, however you can [configure your auth resource to accept custom attributes using the AWS Cloud Development Kit (AWS CDK)](/[platform]/build-a-backend/auth/modify-resources-with-cdk/#custom-attributes).
+Shown in the snippet above, `String` and `Number` can be assigned minimum and maximum constraints. This is useful to defer simple validations to the underlying service, although does not extend to complex validations such as matching against a regular expression.
 
-### Next steps
+## Next steps
 
+- [Learn how attributes are surfaced to tokens](/[platform]/build-a-backend/auth/concepts/tokens-and-credentials/)
 - [Learn how to manage your user attributes](/[platform]/build-a-backend/auth/connect-your-frontend/manage-user-attributes)
diff --git a/...rm]/build-a-backend/auth/connect-your-frontend/manage-user-attributes/index.mdx b/...rm]/build-a-backend/auth/connect-your-frontend/manage-user-attributes/index.mdx
@@ -31,7 +31,7 @@ export function getStaticProps() {
 User attributes such as email address, 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 customers to update their profile after sign-up. In this section we take a closer look at working with user attributes, how to set them up and manage them.
 
 <InlineFilter filters={['javascript', 'angular', 'react', 'vue', 'react-native', 'nextjs']}>
-### Pass user attributes during sign-up
+## Pass user attributes during sign-up
 
 You can 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:
 
@@ -55,28 +55,28 @@ await signUp({
 </InlineFilter>
 
 <InlineFilter filters={['javascript', 'angular', 'react', 'vue', 'react-native', 'nextjs', 'flutter', 'swift']}>
-### Configure custom user attributes during sign-up
+
+## Configure custom user attributes during sign-up
 
 Custom attributes can be passed in with the `userAttributes` option of the `signUp` API:
 
 <InlineFilter filters={['javascript', 'angular', 'react', 'vue', 'react-native', 'nextjs']}>
-```javascript
+
+```ts
 import { signUp } from "aws-amplify/auth";
 
 await signUp({
-  username: 'jdoe',
-  password: 'mysecurerandompassword#123',
+  username: 'john.doe@example.com',
+  password: 'hunter2',
   options: {
     userAttributes: {
-      'custom:attribute_name_1': 'attribute_value_1',
-      'custom:attribute_name_2': 'attribute_value_2',
-      'custom:attribute_name_3': 'attribute_value_3'
+      'custom:display_name': 'john_doe123',
     }
   }
 });
 ```
-</InlineFilter>
 
+</InlineFilter>
 <InlineFilter filters={['flutter']}>
 
 ```dart
@@ -100,8 +100,8 @@ Future<void> _signUp({
   );
 }
 ```
-</InlineFilter>
 
+</InlineFilter>
 <InlineFilter filters={['swift']}>
 
 ```swift
@@ -127,25 +127,26 @@ func signUp(username: String, password: String, email: String) async {
     }
 }
 ```
+
 </InlineFilter>
 </InlineFilter>
 
-### Retrieve user attributes
+## Retrieve user attributes
 
 You can retrieve user attributes for your users to read in their profile using the `fetchUserAttributes` API. This helps you personalize their frontend experience as well as control what they will see.
 
 <InlineFilter filters={['javascript', 'angular', 'react', 'vue', 'react-native', 'nextjs']}>
-```javascript
+
+```ts
 import { fetchUserAttributes } from 'aws-amplify/auth';
 
 await fetchUserAttributes();
 ```
-</InlineFilter>
 
+</InlineFilter>
 <InlineFilter filters={['swift']}>
 
 <BlockSwitcher>
-
 <Block name="Async/Await">
 
 ```swift
@@ -162,7 +163,6 @@ func fetchAttributes() async {
 ```
 
 </Block>
-
 <Block name="Combine">
 
 ```swift
@@ -181,11 +181,11 @@ func fetchAttributes() -> AnyCancellable {
 ```
 
 </Block>
-
 </BlockSwitcher>
-</InlineFilter>
 
+</InlineFilter>
 <InlineFilter filters={['android']}>
+
 <BlockSwitcher>
 <Block name="Java">
 
@@ -233,9 +233,10 @@ RxAmplify.Auth.fetchUserAttributes()
 
 </Block>
 </BlockSwitcher>
-</InlineFilter>
 
+</InlineFilter>
 <InlineFilter filters={['flutter']}>
+
 ```dart
 Future<void> fetchCurrentUserAttributes() async {
   try {
@@ -248,10 +249,10 @@ Future<void> fetchCurrentUserAttributes() async {
   }
 }
 ```
-</InlineFilter>
 
+</InlineFilter>
 
-### Update user attribute
+## Update user attribute
 
 You can use the `updateUserAttribute` API to create or update existing user attributes.
 
@@ -538,7 +539,7 @@ Future<void> updateUserAttributes() async {
 </InlineFilter>
 
 <InlineFilter filters={['javascript', 'angular', 'react', 'vue', 'react-native', 'nextjs', 'android']}>
-### Update user attributes
+## Update user attributes
 
 You can use the `updateUserAttributes` API to create or update multiple existing user attributes.
 
@@ -608,7 +609,7 @@ RxAmplify.Auth.updateUserAttributes(attributes)
 </InlineFilter>
 </InlineFilter>
 
-### Verify user attribute
+## Verify user attribute
 
 <InlineFilter filters={['javascript', 'angular', 'react', 'vue', 'react-native', 'nextjs', 'flutter', 'android']}>
 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:
@@ -744,7 +745,7 @@ Future<void> verifyAttributeUpdate() async {
 </InlineFilter>
 
 
-### Send user attribute verification code
+## Send user attribute verification code
 
 If an attribute needs to be verified while the user is authenticated, invoke the `sendUserAttributeVerificationCode` API as shown below:
 
@@ -877,7 +878,7 @@ Future<void> resendVerificationCode() async {
 </InlineFilter>
 
 <InlineFilter filters={['javascript', 'angular', 'react', 'vue', 'react-native', 'nextjs']}>
-### Delete user attributes
+## Delete user attributes
 
 The `deleteUserAttributes` API allows to delete one or more user attributes.
 
@@ -901,7 +902,7 @@ async function handleDeleteUserAttributes(
 ```
 </InlineFilter>
 
-#### Next Steps 
+## Next Steps 
 
-- [Set up password change and recovery](/[platform]/build-a-backend/auth/manage-users/manage-passwords/)
-- [Set up custom attributes](/[platform]/build-a-backend/auth/modify-resources-with-cdk/#custom-attributes)
+- [Learn how to set up password change and recovery](/[platform]/build-a-backend/auth/manage-users/manage-passwords/)
+- [Learn how to set up custom attributes](/[platform]/build-a-backend/auth/concepts/user-attributes#custom-attributes)
diff --git a/src/pages/[platform]/build-a-backend/auth/modify-resources-with-cdk/index.mdx b/src/pages/[platform]/build-a-backend/auth/modify-resources-with-cdk/index.mdx
@@ -57,32 +57,6 @@ cfnUserPool.policies = {
 };
 ```
 
-## Custom Attributes
-
-The following code will allow you to add custom attributes using the [Userpool schema](https://docs.aws.amazon.com/cdk/api/v1/docs/@aws-cdk_aws-cognito.CfnUserPool.html#schema) property with the L1 `cfnUserPool` construct.
-
-```ts title="amplify/backend.ts"
-import { defineBackend } from '@aws-amplify/backend';
-import { auth } from './auth/resource';
-import { data } from './data/resource';
-
-const backend = defineBackend({
-  auth,
-  data
-});
-
-// extract L1 CfnUserPool resources
-const { cfnUserPool } = backend.auth.resources.cfnResources;
-// update the schema property to add custom attributes
-if (Array.isArray(cfnUserPool.schema)) {
-  cfnUserPool.schema.push({
-    name: 'policyName',
-    attributeDataType: 'Boolean',
-    developerOnlyAttribute: true,
-  });
-}
-```
-
 {/* token validity */}
 {/* BYO custom idp construct */}
 {/* extend auth/unauth roles */}