https://github.com/apostrophecms/login-totp

https://github.com/apostrophecms/login-totp

Last synced: 4 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/apostrophecms/login-totp
• Owner: apostrophecms
• License: mit
• Created: 2022-01-25T16:52:00.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2025-04-02T12:24:19.000Z (about 1 year ago)
• Last Synced: 2025-10-22T18:48:39.472Z (8 months ago)
• Language: JavaScript
• Size: 101 KB
• Stars: 1
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE.md

Awesome Lists containing this project

README

          


  


  
Apostrophe TOTP Login Verification

  


    

      

    

    

      

    

    

      

    

    

      

    

  



This login verification module adds a [TOTP (Time-based One-Time Password)](https://en.wikipedia.org/wiki/Time-based_one-time_password) check when any user logs into the site, compatible with Google Authenticator or any TOTP app.

When activated, it will ask unregistered users to add a token to their app through a QR code. Once done, it will ask users to enter the code provided by their app after the initial login step.

## Installation

To install the module, use the command line to run this command in an Apostrophe project's root directory:

```

npm install @apostrophecms/login-totp

```

## Usage

Instantiate the TOTP login module in the `app.js` file:

```javascript

require('apostrophe')({

  shortName: 'my-project',

  modules: {

    '@apostrophecms/login-totp': {}

  }

});

```

You must configure the `@apostrophecms/login` module with a TOTP secret, as shown. The secret must be **exactly 10 characters long.**

```javascript

// modules/@apostrophecms/login/index.js

module.exports = {

  options: {

    totp: {

      // Should be a random string, exactly 10 characters long

      secret: 'totpsecret'

    }

  }

};

```

> ⚠️ All configuration of TOTP related options is done on the `@apostrophecms/login` module. The `@apostrophecms/login-totp` module is just an "improvement" to that module, so it has no configuration options of its own.

### Resetting TOTP when a user loses their device

If a user loses their device, an admin can edit the appropriate user via the admin bar. Select "Yes" for the "Reset TOTP" field and save the user.

If an admin user loses their own device, they can reset TOTP via a command line task. Pass the username as the sole argument:

```

node app @apostrophecms/user:reset-totp username-goes-here

```

Once TOTP is reset, the user is able to set it up again on their next login.