Entra.News Dailydaily.entra.news
Aboutmerill.net
Microsoft Entra ID

Tutorial Native Authentication Single Page App React Sdk Sign Up

25 June 2026Updated+45 / −35 lines

In brief

1. Create *sign-up/components/InitialForm.tsx* file, then paste the code from [sign-up/components/InitialForm.tsx](https://github.com/Azure-Samples/ms-identity-ciam-native-javascript-samples/blob/main/typescript/native-auth/react-nextjs-sample/src/app/sign-up…

Documentation change

  1. Create sign-up/components/InitialForm.tsx file, then paste the code from sign-up/components/InitialForm.tsx. This component displays a form that collects user sign-up attributes.
If you want to let users sign up with a username (alias), add a text input to this form to collect the username (alias) value. For example:

```tsx
<input
    type="text"
    placeholder="Username (alias)"
    value={flatUsername}
    onChange={(e) => setFlatUsername(e.target.value)}
    style={styles.input}
/>
```
  1. Create a sign-up/components/CodeForm.tsx file, then paste the code from sign-up/components/CodeForm.tsx. This component displays a form that collects a one-time passcode sent to the user. You require this form for either email with password or email with one-time passcode authentication method.
  1. Create a sign-up/components/CodeForm.tsx file, then paste the code from sign-up/components/CodeForm.tsx. This component displays a form that collects a one-time passcode sent to the user. You require this form for either email with password or email with one-time passcode authentication method.

  1. If your choice of authentication method is email with password, create a sign-up/components/PasswordForm.tsx file, then paste the code from sign-up/components/PasswordForm.tsx. This component displays a password input form. 

    The SDK's instance method, `signUp()` starts the sign-up flow.

If you want to let users sign up with a username (alias), add a `flatUsername` state to the sign-up page, then include the `flatusername` attribute in the `UserAccountAttributes` you pass to `signUp()`:

```typescript
const [flatUsername, setFlatUsername] = useState("");

const attributes: UserAccountAttributes = {
    displayName: `${firstName} ${lastName}`,
    givenName: firstName,
    surname: lastName,
    jobTitle: jobTitle,
    city: city,
    country: country,
    flatusername: flatUsername,
};
```

After sign-up, the user can sign in by using either their email or their username (alias). When you handle errors for the username (alias), keep in mind that:

- `result.error?.isUserAlreadyExists()` covers a duplicate email *or* a duplicate username (alias). Update the message accordingly, for example, *An account with this email or username already exists*.
- An invalid username (alias) is surfaced through `result.error?.isAttributesValidationFailed()` rather than `result.error?.isInvalidUsername()`. Branch on this method to show a username-specific message.

  • To handle the one-time passcode submission, use the following code snippet. See a full example at sign-up/page.tsx to learn where to place the code snippet:

        return <SignUpResultPage/>;
}

Collect a username (alias) during sign-up

You can let users sign up with a username (alias) in addition to their email. The username (alias) is an alternate sign-in identifier, such as a customer ID, account number, or another value that you choose.

During sign-up, the username (email) is always required as the primary identifier, and the username (alias) doesn't replace it. By default, the username (alias) is optional, though an administrator can configure it as required. Your app always collects the username (email) and collects the alias as an attribute alongside the email. At sign-in, the user can then sign in with either their username (email) or their username (alias). To learn how the Username attribute is configured as optional or required, see Configure the user input types and page layout.

To collect a username (alias) during sign-up:

  1. Make sure the Username built-in user attribute is enabled in your sign-up user flow. For the steps, see Enable username in the sign-in identifier policy.

  2. Add a flatUsername state to the sign-up page, then include the flatusername attribute in the UserAccountAttributes you pass to signUp():

    const [flatUsername, setFlatUsername] = useState("");

const attributes: UserAccountAttributes = {
    displayName: `${firstName} ${lastName}`,
    givenName: firstName,
    surname: lastName,
    jobTitle: jobTitle,
    city: city,
    country: country,
    flatusername: flatUsername,
};

  3. Add an alias input to InitialForm.tsx to collect the username (alias) value:

    <input
    type="text"
    placeholder="Username (alias)"
    value={flatUsername}
    onChange={(e) => setFlatUsername(e.target.value)}
    style={styles.input}
/>

  4. Handle errors related to the username (alias):

    • result.error?.isUserAlreadyExists() covers a duplicate email or a duplicate username (alias). Update the message accordingly, for example, An account with this email or username already exists.
    • An invalid username (alias) is surfaced through result.error?.isAttributesValidationFailed() rather than result.error?.isInvalidUsername(). Branch on this method to show a username-specific message.

Handle sign-up errors

During sign-up, not all actions succeed. For instance, the user might attempt to sign up with an already used email address or submit an invalid email one-time passcode. Make sure you handle errors properly when you: