Description

EzAccounts

User account management system in NodeJs made easy. EzAccounts provides a starter NodeJs server that allows you to build your own sites.

Many sites need the ability to have users create accounts, log in, log out, change their password, etc. When building your own sites, you need to code all that stuff, quite often, before you can get to the meat of what your site actually does. And it is cumbersome too.

… Well, not any more! With EzAccounts, it is plug and play. You do not need to worry about writing the code that deals with user accounts. Simply use the starter server, which has all that baked in, and start coding the main stuff on your site!

Features

• Token based authentication
• Role based authorisation
• Credit card payments via Stripe
• Sign Up for Accounts
  • Sends email to user, with activation instructions
• Activate Account
  • Sends email to user confirming that account is active
• Change Password for Account
• Log In to Account
• Log Out of Account
• Change Roles on Account
• All based on JSON APIs
  • Response in JSON
  • No need for web pages
  • Ideal for single page applications
  • Ideal for native apps
• Uses MongoDB
• Easy configuration, and easy modification
• Well documented
  • Descriptive comments that document exactly what is happening
• Well tested
  • Comprehensive integration tests: 68 scenarios
  • Comprehensive code coverage: 88% coverage

Deprecation notice

tl;dr= Get the newer edition instead: OKAccounts.

EzAccounts has gone through a complete rewrite.

EzAccounts was originally written when NodeJs v0.10.x was the current and most popular version of NodeJs deployed in production. Since then, however, the NodeJs community has made huge moves. NodeJs was forked as io.js, which released 3 major versions, and then io.js and NodeJs were merged together, and have released 2 more major versions.

Javascript’s language specification itself has also gone through a major change. ECMAScript 5 (ES5) was the current version of Javascript, but now it is ECMASCript 6 (ES6), introducing many new features.

Along with these major changes, the libraries available in NodeJs have been completely rewritten, and completely new ones have emerged and come into prominence; and a notable one has been Koa, which is a successor – in spirit – to express. This library makes extensive use of generator functions and yield statements – which are new and introduced in ECMAScript 6 – and have made writing asynchronous code much cleaner and easier to understand.

In light of all of these developments, EzAccounts has been rewritten from scratch, and the new edition comes with a new name: OKAccounts.

If you are currently using EzAccounts, you should strongly consider switching to OKAccounts, for the reasons listed above. You should continue using EzAccounts if you are:

• restricted to using NodeJs v0.10.x, or
• restricted to using ECMAScript 5, or
• some other legacy code related reason.

Issues/ Requests

Please let me know in the Comments section for this item.

If you have a new test case in mind, or feel like one of the tests could be improved, please submit a pull request to, or create an issue ticket at, ezaccounts-tests.

Licence

This module is available dual licenced under

• the Envato Regular Licence dated 30 April 2014
• the Envato Extended Licence dated 30 April 2014

As such, this module is not available from the npm registry. Instead of npm installing this, you must copy the folder to the appropriate location.

Please purchase the regular licence if you wish to use this in an application that does not charge end users, and purchase the extended licence if you wish to use this in an application that does charge end users. Read the full details of the licences from the pages above.

The tests for this module are a separate project, and available under GPLv3. They are only included as part of this distribution as a convenience.

Author

Brendan Graetz

• bguiz.com
• @bguiz on twitter
• @bguiz on github

If you already own EzAccounts, read on

Installation

First, install some prerequisites:

• NodeJs and npm.
  • You should use NodeJs >= v0.10.29 && < v0.11.x
  • Follow instructions here.
• MongoDB.
  • You should use MongoDB >= v2.4.9 && < v3.0.x
  • Follow instructions here.
• OpenSSL.
  • Should be preloaded on most systems, otherwise, follow instructions here.

Next, in the folder where you have this module installed, run:

npm install

Usage

Configuration Settings

Configure the app.

cp config-settings.js.template config-settings.js

Then edit config-settings.js, to customise it for your site. Look at the defaults variable in config.js, and use that as a reference for what you should include in config-settings.js.

HTTP or HTTPS

Next, you will need to obtain SSL certificates in order to run your site over HTTPS. To do this, you will need to use openssl commands in the terminal, or purchase them from a certificate authority. Note that when users visit HTTPS sites using self-signed SSL certificates, warning messages will be displayed in the browser.

For your convenience, a pair of self-signed SSL certificates have been provided, private-key.pem, and public-key.pem. These are just so that you can get started quickly, and they should never be used in production.

To purchase SSL certificates from a certificate authority, follow this guide.

To create self-signed SSL certificates:

openssl genrsa -out private-key.pem 1024
openssl req -new -key private-key.pem -out certificate-request.csr
#This command is interactive, you will be prompted for various details about the owner of the certificate
openssl x509 -req -in certificate-request.csr -signkey private-key.pem -out public-key.pem

If you do not wish to do this, you can serve your site over HTTP instead. While this is OK for development purposes, you certainly should not be doing this in production. To do this edit config-settings.js and set config.server.https to false.

Note that SSL certificates expire with time, and it is good practice to set up an automated reminder/ notification in a calendar app such as Google Calendar or iCal, that lets you know that you need to deploy a new certificate. Your certificate authority might have a reminder feature for this, be sure to look out for that.

Run the server

Now run the server.

node start

Lastly, visit http://0.0.0.0:3000/ in your browser, or, if you are on Windows visit http://localhost:3000/ in your browser, and you should be served any static files placed in client/dist.

Use any HTTP agent to hit the various API end points, some common ones are:

• Command line HTTP rest clients
  • curl
• Browser plugin HTTP REST clients
  • Postman (Chrome/ Chromium)
  • RESTClient (Firefox)
• Standalone desktop application HTTP REST clients
  • Fiddler
  • Charles

Quality Assurance

Quality assurance is provided through a combination of integration testing and code coverage.

Firstly, edit tests/config-settings.js. Change the values for payments.stripeApiKeyPrivate and stripeApiKeyPublic, to match your own test Stripe API keys. You should now be able to run your tests.

To run the integration tests:

npm run test

To run the code coverage:

npm run coverage
firefox blanket.html
# chrome-browser blanket.html # OR any other browser

The tests are are open source, and available at github.com/bguiz/ezaccounts-tests. They have been included here as a convenience.

If you would like to use the tests directly from the source:

rm -rf tests
git clone [email protected]:bguiz/ezaccounts-tests.git tests

Fin

That’s all folks!