@konmuc/authc v1.0.3

@konmuc/authc

This package provides an authentication layer for the konmuc website.

Warning: This is work in progress

@konmuc/authc has the following features:

• Provides an express middleware based on mongodb for securing apis.
• Comes with built in REST resources for user managment with login, logout and signup support.
• Uses JWT (JSON Web Token) as token mechanism.
• Allows multiple clients per user.

Installation

To use this package in an express application, execute the following command:

npm install @konmuc/authc --save

Before continuing it is recommended to install also the following express packages:

npm install express body-parser mongoose --save

Usage

In the server setup script, first import the middleware and the user managment resources.

// other app imports
...

// import the @konmuc/authc dependencies
import express from 'express';
import mongoose from 'mongoose';
import bodyParser from 'body-parser';

// import the @konmuc/authc middleware and router
import authc from '@konmuc/authc';
import authcRouter from '@konmuc/authc/router';

// app setup goes here
...

Then connect to mongodb and configure express to use the @konmuc/authc authentication layer.

mongoose.connect('mongodb://localhost/authc')
    .then(() => {
        // create express app
        const app = express();

        // register json middleware
        app.use(bodyParser.json()):

        // register @konmuc/authcRouter with user managment support
        app.use('/', authcRouter);

        // register @konmuc/authc middleware
        app.use(authc({ secret: APP_SECRET }));

        // remaining app setup
        ...

        // start express app
        app.listen(PORT, () => { console.log(`Listening on ${PORT}.`); });
    });

Middelware API

@konmuc/authc(options)

The authc middleware can be configured by the following options:

Example:

import authc from '@konmuc/authc';

// create the middleware
const middleware = authc({
    secret: APP_SECRET, // the required APP_SECRET
    accessTokenExpiration: { minutes: 15 }, // override the defalt acces token expiration
    accessTokenPayload: ({ email }) => { email } // only possible if the UserSchema was extend by an email property.
});

// hook the middleware
app.use(middleware);

@konmuc/authc/schema/UserSchema

The default mongoose user schema used by @konmuc/authc comes with a minimum set of immutable properties. These proprties are listed in the following table.

In some cases an application needs more parameters assigned to a user. Therefore the underlying mongoose user schema used by @konmuc/authc can be extended. To configure the user schema, an application can use the @konmuc/authc/schemas/UserSchema modules configure method.

// import the UserSchema modules configure method
import UserSchema from '@konmuc/authc/schemas/UserSchema';

// extend the default user schema with an email field.
UserSchema.configure({
    email: {
        type: String,
    }
});

Authentication Workflow

The authentication mechanism is based on the access token and refresh token pattern. The authentication process follows the following workflow:

1. A user sends its credentials (username and password) to the /signin resource. If a user has no credentials yet, the user needs to register using the /signup resource.

2. If the credentials where valid, the /signin resource responded with the following parameters as json:

   • accessToken: A token, which authenticates the user.
   • expiresIn: Indicates in seconds, when the inquired accessToken will be invalidated.
   • refreshToken: A client can use the refreshToken to request a new accessToken.
   • clientId: A clientId, which is assigned to the refreshToken.

3. On any further request to a secured api, a client need to send the previously inquired accessToken. The accessToken must be send via the query string, the request body or the x-access-token header.

4. Before an accessToken will expire, a client can use the refreshToken to request a new accessToken via the /token resource.

5. To singout a user, a client need to send the clientId and the username via the /signout resource.

Authentication REST-API

/signup

The /signup-Resource allows to register a new user for an application.

Request

method: POST

Content-Type: application/json

Response

Content-Type: application/json

/signin

The /signin-Resource allows an already registered user to log in to the application.

Request

method: POST

Content-Type: application/json

Response

Content-Type: application/json

/token

The /token-Resource allows an application to inquire a new access token for a registered user.

Request

method: POST

Content-Type: application/json

Response

Content-Type: application/json

/signout

The /signout-Resource allows an application to log out an logged in user.

Request

method: POST

Content-Type: application/json

Response

Content-Type: application/json

Testing

The @konmuc/authc package use intern as test runner.

To run the tests first run

npm install

Then execute

npm run test