Authentication

This page contains guides related to authentication and account management.

Overview

Here is a quick explanation of how authentication works in the app

• No sign up page. New accounts can only be created by an admin via the admin dashboard or on the backend
• You can only sign in with an email address that has the domain @borkuafrica.com
• When a user is signed in, they are required to undergo 2FA. The 2FA code is sent to the user's email address
• Upon successful 2FA, we confirm that the user's account has the admin role. If not, they are directed to the unauthorized page
• If the user has the admin role, they are redirected to the admin dashboard

Get logged in user

Use this code to check if a user is logged in. It return a user object if the user is logged in. Otherwise, it throws an error. The User class is an Appwrite model object. For more information on the User class, see the Appwrite documentation.

    try {
        const res = await account.get();
        res.
    } catch (error) {
        if (error instanceof AppwriteException) {
            if (error.type === "user_more_factors_required") {
                // navigate user to verification screen
            }
            else {
                // navigate user to login screen
            }
        } else {
            console.error(error);
            // navigate user to login screen
        }
    }

Sign In

    try {
        await account.createEmailPasswordSession(email, password);
    } catch (error) {
        if (error instanceof AppwriteException) {
            if (error.type === "user_more_factors_required") {
                // this will always get fired if the user has 2FA enabled (which should be true for all admin users)
                // navigate user to verification screen
            }
            else {
                // display error message to user
            }
        } else {
            console.error(error);
            // display error message to user
        }
    }

Request Password Reset

Use this code to send a password reset email to a user. The email parameter is the email address of the user who wants to reset their password.

note

This method is different than the update password method. The update password method is used to change the password of a user who is already logged in. The request password reset method is used to send a password reset email to a user who is not logged in.

    try {
        const baseURL = window.location.origin;
        const url = `${baseURL}/reset-password`;
        
        await  account.createRecovery(email, url);

        // display success message to user
    } catch (error) {
        if (error instanceof AppwriteException) {
            console.error(error.message);
            // display error message to user
        } else {
            console.error(error);
            // display error message to user
        }
    }

info

The url parameter is the URL to which the user will be redirected after clicking the link in the password reset email.

Reset Password

The email sent to the user contains both the secret and userId keys, both of which we will use to verify the user's identity and reset their password.

    try {

        await account.updateRecovery(userId, secret, newPassword);

        // redirect to login page with success message so user can login with new password

    } catch (error) {
        if (error instanceof AppwriteException) {
            console.error(error.message);
            // display error message to user
        } else {
            console.error(error);
            // display error message to user
        }
    }

Init MFA

We use this method to initialize MFA for a user. Choosing the email factor, the user will get a 6-digit code sent to their email adress. It is important to store the challengeId to later verify the code.

    try {
        const res = await account.createMfaChallenge(AuthenticationFactor.Email);
        challengeId = res.$id;

        // display success message to user
    } catch (error) {
        if (error instanceof AppwriteException) {
            console.error(error.message);
            // display error message to user
        } else {
            console.error(error);
            // display error message to user
        }
    }

Complete MFA

Here, we verify the 6-digit code sent to the user's email address

    try {
        await account.updateMfaChallenge(challengeId, otp);

        // display success message to user and navigate to admin dashboard
    } catch (error) {
        if (error instanceof AppwriteException) {
            console.error(error.message);
            // display error message to user
        } else {
            console.error(error);
            // display error message to user
        }
    }

Change Password

Change the password of a logged in user.

warning

We might want to pre-inform users they will be logged out after they change their password.

    try {
        await account.updatePassword(newPassword, oldPassword);
        // display success message to user, redirect to login page for user to login again
    } catch (error) {
        if (error instanceof AppwriteException) {
            console.error(error.message);
            // display error message to user
        } else {
            console.error(error);
            // display error message to user
        }
    }

Sign Out

    try {
        await account.deleteSession("current"); // sign out the current session

        // delete all user data from local storage/shared preferences (if any)

        // call the `deleteTarget` method from the Push Notifications page to delete the user's token from the database and stop receiving notifications

        // redirect to login page for user to login again
    } catch (error) {
        if (error instanceof AppwriteException) {
            console.error(error.message);
            // display error message to user
        } else {
            console.error(error);
            // display error message to user
        }
    }