2-Factor authentication

Unreleased on Cloud

This feature is not yet released on Cloud, which is on Appwrite 1.4.x. This is a feature available in Appwrite 1.5.x and will be available on Appwrite Cloud later.

Two-factor authentication (2FA) greatly increases the security of your apps by adding additional layers of protection. When 2FA is enabled, a malicious actor needs to compromise multiple authentication factors to gain unauthorized access. Appwrite Authentication lets you easily implement 2FA in your apps, letting you build more securely and quickly.

Looking for 2FA on your Console account?

This page covers 2FA for your app's end-users. If you are looking for 2FA on your Appwrite Console account, please refer to the Console 2FA page.

Appwrite currently allows two factors of authentication. More factors of authentication will be available soon.

Here are the steps to implement 2FA in your application.

1

Enable 2FA on an account

You can enable 2FA on your account by calling account.updateMFA(). You will need to have added more than 1 factors of authentication to an account before the 2FA is enforced.

Initialize your Appwrite SDK's Client and Account.

import { Client, Account } from "appwrite";

const client = new Client();

const account = new Account(client);

client
    .setEndpoint('https://cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
;
const result = await account.updateMFA(true);
2

Initialize login

Begin your login flow with the default authentication method used by your app, for example, email password.

const session = await account.createEmailPasswordSession(
        'email@example.com',         // email
        'password'                   // password
    );
3

Check for two-factor

Upon successful login in the first authentication step, check the status of the login by calling account.get(). If more than one factors are required, you will the error user_more_factors_required. Redirect the user in your app to perform the MFA challenge.

try {
    const response = await account.get();
    console.log(response);
} catch (error) {
    console.log(error);
    if (error.type === `user_more_factors_required`){
        // redirect to perform MFA
    }
    else {
        // handle other errors
    }
}
4

List factors

You can check which factors are enabled for an account using account.listFactors(). The returned object will be formatted like this.

JavaScript
{
    totp: true, // time-based one-time password
    email: false, // email
    phone: true // phone
}
const factors = await account.listFactors();
// redirect based on factors returned.
5

Create challenge

Based on the factors available, initialize an additional auth step. Calling these methods will send a challenge to the user. You will need to save the challenge ID to complete the challenge in a later step.

    6

    Complete challenge

    Once the user receives the challenge code, you can pass the code back to Appwrite to complete the challenge.

    const response = await account.updateChallenge(
            '<CHALLENGE_ID>',            // challengeId
            '<OTP>'                      // otp
        );