Let's MFA

Beautifully simple and free Multi-Factor Authentication (MFA or 2FA) solution for your existing web app. No user migrations. No developer sign-up. Can be completed in 30 minutes.

Use Case

LetsMFA is an add-on to your existing authentication solution (not a replacement). You already have a basic authentication solution, but don't want to pay for MFA features - or don't have an easy way to implement MFA.

This package is meant to be used in server side, and not in client side code.

Security

LetsMFA is the smallest and most secure MFA solution possible.

1. No developer sign-up required, so no account management risks.
2. User data is stored on your servers, and not on LetsMFA servers.
3. LetsMFA uses bank level end-to-end encryption and validations.
4. This library has only a very few high quality dependencies.
5. You define the authentication policy to match your requirements.

Getting Started

1. Install This Package

npm i lets-mfa

2. Generate Keys

These keys are used to ensure proxies and other middlemen can't tamper with the authentication requests.

The private key is a secret! Do not check into version control.

npx lets-mfa generate-keys

2. Create a LetsMFA client

The LetsMFA client can be instantiated once at server start up time, and can be shared across connections.

import { LetsMFA } from "lets-mfa";

// Pseudo code for accessing the keys in the section above.
// Example: read them from environment variables or a file
// KEYS SHOULD NOT BE CHECKED INTO VERSION CONTROL
const {publicKey, privateKey} = getKeys();

const letsMfa = new LetsMFA({

  // The highest level domain you control for the project
  domain: "example.com",

  // The public and private keys read from above. These are strings.
  {
    publicKey,
    privateKey,
  },

  // The URL of the logo to display on the MFA page
  // Ensure this file is served with a CrossOrigin policy
  // that allows it to be loaded by browser when the user
  // views the MFA page on the LetsMFA server
  logoUrl: "http://localhost:4000/static/logo.png",
});

3. Enrollment Flow

For first time users, or users that need to update their MFA settings, use the enroll request flow.

// If your existing auth solution provides a JWT, you can use that.
// Or you can generate a self signed JWT for the user
// This is generally done after the user has completed the first
// factor of authentication (e.g. username/password)
const jwt = await letsMFA.generateSelfSignedJWT(username);

const requestUrl = await letsMFA.generateEnrollRequest(
  // The URL where you will validate the response from LetsMFA (see below)
  "https://example.com/letsmfa",
  jwt
);

// Redirect the user to the requestUrl
res.redirect(302, redirectUrl);

4. Authentication Flow

To authenticate a user that has completed the enroll flow, use the authentication request flow.

// Pseudo code for retrieving a user from the database after they have completed
// the basic authentication method (ex: username/password)
const user = await database.getUser(username);

// If your existing auth solution provides a JWT, you can use that,
// or generate a self signed JWT for the user
// This is generally done after the user has completed the first
// factor of authentication (e.g. username/password)
const jwt = await letsMFA.generateSelfSignedJWT(username);

const requestUrl = await letsMFA.generateAuthenticationRequest(
  // A URL where you will validate the response from LetsMFA (see below)
  "https://example.com/letsmfa",

  // A JWT string that identifies the signed in user
  // you can generate your own jwt like
  jwt,

  // The account value (string) value that was returned from the last
  // enroll or authentication request. See below.
  user.accountVault
);

// Redirect the user to the requestUrl

5. Verify the response

Verifying enroll and authentication responses are generally the same (though you may want to handle them separately). The letsMFA library can validate the response. You must save the "accountVault" value for each user in your database.

// This method will throw an error if there is a problem
const response = await letsMFA.handleAuthResponse(
  // The response URL will receive a "responseToken" query parameter
  // that contains the responseToken from LetsMFA. The client
  // exchanges that token for the encrypted response directly
  // from the LetsMFA server.
  req.query.responseToken as string,

  // LetsMFA returns "nested JWTs". The first layer is automatically
  // validated by the handleAuthResponse method. The second layer JWT
  // is the one you provided during the generateAuthentication or
  // generateEnroll request. Supply here the secret string or public
  // key used to validate that JWT's signature.
  {
    publicKeyOrSecret: letsMFA.getPublicKey(), // or "secret-string-from-other-auth provider"
  }
);

// The following is pseudo code...

// The user is now authenticated with MFA
// You can use the response.sub to identify the user
const user = await database.getUserBySub(response.sub);

// You must save the accountVault value for the user
// so that it can be used on the next authentication request
await database.saveUserAccountVault(user, response.accountVault);

Add SMS

To enable SMS authentication, you need to provide a Twilio account SID, auth token, and from phone number. You can get these from the Twilio console.

These are passed in the AuthPolicy in the LetsMFA Constructor. Here is an example that simply modifies the default auth policy, and adds the required information from environment variables

import { DEFAULT_AUTH_POLICY } from "lets-mfa";

// adopt the default auth policy
const defaultAuthPolicy = DEFAULT_AUTH_POLICY;

// Add SMS provider information to the auth policy
AUTH_POLICY.methods.sms!.provider.twilio = {
  accountSid: process.env.TWILIO_ACCOUNT_SID,
  authToken: process.env.TWILIO_AUTH_TOKEN,
  from: process.env.TWILIO_FROM,
};

// Include your new default auth policy in the LetsMFA constructor
const letsMFA = new LetsMFA({
  ...
  defaultAuthPolicy
  ...
})