Two factor auth

Implementing two factor authentication with Tensei

For added security, you may want to add two-factor authentication to your application. Two-factor authentication is implemented using speakeasy.

Enable Two factor auth

First, you need to install the @tensei/two-factor-auth package. This package installs speakeasy and provides the routes and functions for two-factor authentication.

yarn add @tensei/two-factor-auth

# Or using npm
npm install @tensei/two-factor-auth

To enable this feature, you may call the twoFactorAuth() method on the auth plugin instance:

const { auth } = require('@tensei/auth')
const { tensei } = require('@tensei/core')

tensei()
    .plugins([
        auth()
            .twoFactorAuth()
            .plugin()
    ])

This generates new types for the GraphQL API:

input disable_user_two_factor_auth_input {
  token: Int!
}

input confirm_enable_user_two_factor_auth_input {
  token: Int!
}

type enable_user_two_factor_auth_response {
  dataURL: String!
}

extend type Mutation {
    enable_user_two_factor_auth: enable_user_two_factor_auth_response!
    disable_user_two_factor_auth(object: disable_user_two_factor_auth_input!): user!
    confirm_user_enable_two_factor_auth(object: confirm_enable_user_two_factor_auth_input!): user!
}

If you're using REST, it also generates the following endpoints:

  • POST auth/two-factor/enable to enable two factor authentication for a user account. This needs confirmation.
  • POST auth/two-factor/confirm to confirm the previous enable request. This requires a valid two-factor token from the user's authenticator mobile application.
  • post auth/two-factor/disable to disable two-factor authentication for a user account. This also requires a valid two-factor token.

Two-factor flow

  • First, a user logins in to your application. By default, two-factor authentication is disabled.

  • You need to inform the user to download one of the two-factor authentication mobile applications such as Authy or Google Authenticator.

  • The user clicks on Enable. At this point, you make a call to the enable_user_two_factor_auth mutation or POST auth/two-factor/enable endpoint.

  • This endpoint returns a base64 data URL. You need to render this as an image, and instruct the user to scan this image using the mobile app downloaded earlier.

  • The mobile application should correctly display a two-factor token that expires every few seconds.

  • Your client-side application at this point should ask the user provide a valid token to confirm two-factor authentication.

  • As a final step, you need to call the confirm_user_enable_two_factor_auth mutation or POST auth/two-factor/confirm endpoint with the two-factor token. The auth plugin will enable two-factor authentication for this user.