Manage Email/Password Users - React Native SDK

Set up @realm/react Providers

Components wrapped by AppProvider can access the useApp and useAuth hooks. These components only render if AppProvider successfully connects to your App Services backend.

Components wrapped by UserProvider can access authenticated users with the useUser hook. These components only render if your app has an authenticated user

To configure user authentication:

1. Wrap all components that need to access App Services in AppProvider.

2. Inside of AppProvider, wrap all components that you want to have access to an authenticated user with UserProvider.

3. In UserProvider, include a fallback prop with a component that logs a user in. The app renders this component if there is no authenticated user.

import React from 'react';
import {AppProvider, UserProvider} from '@realm/react';
// Fallback log in component that's defined in another file.
import {LogIn} from './Login';
export const LoginExample = () => {
  return (
    <ScrollView>
      <AppProvider id={APP_ID}>
        {/* If there is no authenticated user, mount the
         `fallback` component. When user successfully
          authenticates, the app unmounts the `fallback`
          component (in this case, the `LogIn` component). */}
        <UserProvider fallback={LogIn}>
          {/* Components inside UserProvider have access
            to the user. These components only mount if
            there's an authenticated user. */}
          <UserInformation />
        </UserProvider>
      </AppProvider>
    </ScrollView>
  );
};

Log In with a Fallback Component

Users must have a registered email/password account before they can log in. After a user logs in, all components wrapped in UserProvider have access to an instance of that user object through the useUser hook.

To log a user in with email and password:

1. Register user if they aren't already.

2. Destructure logIn and result from the useEmailPasswordAuth hook.

3. Pass the user's email and password to LogIn() as an object.

4. Handle the result.

export const LoginWithEmail = () => {
  const {logIn, result} = useEmailPasswordAuth();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const performLogin = () => {
    logIn({email, password});
  };
  // Handle `result`...
};

Resend a Confirmation Email

If the provider is configured to send a confirmation email, Atlas App Services automatically sends a confirmation email when a user registers. The email contains a link to the configured Email Confirmation URL with a token that is valid for 30 minutes. If a user does not follow the link and confirm within that period, they must request a new confirmation email.

To resend a confirmation email:

1. Destructure resendConfirmationEmail and result from the useEmailPasswordAuth hook.

2. Pass the user's email to resendConfirmationEmail() as an object.

3. Handle confirmation based on result.

const ResendUserConfirmationEmail = () => {
  const {resendConfirmationEmail, result} = useEmailPasswordAuth();
  const [email, setEmail] = useState('');
  const performResendConfirmationEmail = () => {
    resendConfirmationEmail({email});
  };
  // Handle `result`...
}

Retry a User Confirmation Function

You can rerun your custom confirmation function if needed.

To retry a user confirmation function:

1. Destructure retryCustomConfirmation and result from the useEmailPasswordAuth hook.

2. Pass the user's email to retryCustomConfirmation() as an object.

3. Handle confirmation based on result.

const RetryCustomUserConfirmation = () => {
  const {retryCustomConfirmation, result} = useEmailPasswordAuth();
  const [email, setEmail] = useState('');
  const performRetryCustomConfirmation = () => {
    retryCustomConfirmation({email});
  };
  // Handle `result`...
}

Reset Password with Email

You can send password reset emails to confirm users' identities. You must configure your App Services App to send a password reset email. Mobile applications can handle password resets directly in the app. Configure deep linking in Android or universal links in iOS.

The token and tokenId values from password reset emails are valid for 30 minutes. If users don't visit the email's Password Reset URL in that time, the values expire and users must request another password reset email.

To reset a password with email:

1. In App Services, make sure Password Reset Method is set to Send a password reset email.

2. In your client code, destructure sendResetPasswordEmail, resetPassword, and result from the useEmailPasswordAuth hook.

3. Pass the user's email to sendResetPasswordEmail() as an object.

4. Extract the token and tokenId values from the reset email password URL.

5. Pass the new user password, token, and tokenId to resetPassword() as an object.

const SendResetPasswordEmailButton = ({email}: {email: string}) => {
  const [errorMessage, setErrorMessage] = useState('');
  const {sendResetPasswordEmail, result} = useEmailPasswordAuth();
  const performSendResetPasswordEmail = () => {
    sendResetPasswordEmail({email: email});
  };
  // Handle `result`...
};

interface ResetPasswordButtonProps {
  password: string;
  token: string;
  tokenId: string;
}
const ResetPasswordButton = ({
  password,
  token,
  tokenId,
}: ResetPasswordButtonProps) => {
  const [errorMessage, setErrorMessage] = useState('');
  const {resetPassword, result} = useEmailPasswordAuth();
  const performPasswordReset = () => {
    resetPassword({token, tokenId, password});
  };
  // Handle `result`...
};

Call a Password Reset Function

You can call an App Services Function that you define to handle password resets. You must configure your App Services App to run a password reset function.

This function can take a username, a password, and any number of additional arguments. You can use these arguments to specify details like security question answers or other challenges that the user should pass to successfully complete a password reset.

On the App Services side, you define the custom password reset function that runs when you call this method. That function should return one of three possible statuses:

• fail

• pending

• success

A fail status is treated as an error. The SDK method callResetPasswordFunction() does not take return values, so it does not return a pending or success status to the client.

To call a password reset function:

1. In App Services, create a password reset function.

2. In App Services, make sure Password Reset Method is set to Run a password reset function and point it to your new function.

3. In your client code, destructure callResetPasswordFunction and result from the useEmailPasswordAuth hook.

4. Pass the user's email and password to callResetPasswordFunction() as an object, followed by any other arguments you defined for your custom function.

const ResetPasswordWithFunction = () => {
  const {callResetPasswordFunction, result} = useEmailPasswordAuth();
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const performResetPassword = () => {
    callResetPasswordFunction({email, password}, "extraArg1", "extraArg2");
  };
}

interface ResetPasswordButtonProps {
  password: string;
  token: string;
  tokenId: string;
}
const ResetPasswordButton = ({
  password,
  token,
  tokenId,
}: ResetPasswordButtonProps) => {
  const [errorMessage, setErrorMessage] = useState('');
  const {resetPassword, result} = useEmailPasswordAuth();
  const performPasswordReset = () => {
    resetPassword({token, tokenId, password});
  };
  // Handle `result`...
};