@frappy/node-authentication

NodeJS Authentication

NodeJS Endpoints and Functionality For Authentication and User Management

• authMiddleware - Express middleware to facilitate authentication and permission checks
• registerEndpoints - Express endpoints to handle login, authentication check and user management

Usage

import { registerEndpoints, authMiddleware } from "@frappy/node-authentication"
import express from "express"
import bodyParser from "body-parser"

const app = express()  // create your express app
app.use(bodyParser.json({ limit: "10mb" }))  // provide JSON parser with 10 MB payload limit

// entirely optional userOptions (see README for defaults)
const options = {
    tokenExpiration: 24 * 60 * 60,  // session expires after one day
    defaultPermissions: ["view"],  // new users (first login) will receive this permission
    apiKeys: true, // use API keys in this app
}

// cache to hold authentication token (will be populated by auth endpoints)
const tokenCache = {}

// register module
registerEndpoints(app, userStore, userTokenStore, tokenCache, options)

// provide some custom endpoint with authentication and permission check
app.get("/my/custom/endpoint", authMiddleware(["view", "manage"], tokenCache), (req, res) => {
    // only enter this, if the user is authenticated and has "manage" and "view" permissions
    res.send({ foo: "bar" })
})

registerEndpoints(app, userStore, userTokenStore, tokenCache, options)

• app - your express app
• userStore a MongoDB or MySQL store providing functions: login, getAll, get, delete, getByUid, count, getByUsername, create and updatePermissions
• userTokenStore optional, a Mongo or MySQL store providing functions: removeExpired, storeToken and getAll. If this is not provided, all tokens will be invalidated on server restart.
• tokenCache a JSON object that will hold auth tokens and their respective owners (users), required for authMiddleware
• options optional, a JSON object that provides the options (see Options)

authMiddleware(requiredPermissions, tokenCache, allowApiKey = false)

• requiredPermissions - optional a single string representing a permission the user has to fulfill or a list of permissions that all have to be fulfilled.
• tokenCache a JSON object holding the authentication tokens. This is the same object that is passed into the registerEndpoints function.
• allowApiKey a boolean flag indicating whether the current endpoint can be accessed using an API key instead of a regular auth header token. The API key needs to be provided as Authorization header with value Token $KEY (replacing $KEY with the actual key generated by the system).

Options

The registerEndpoint function has a parameter to pass options. All options are optional. The following options are supported:

• apiPrefix (default: /api/user) - a prefix for all endpoints provided, this will generate:
  • POST /api/user/login - to log in (using username, password as JSON payload)
  • GET /api/user - general login check, has to provide Authorization header
  • GET|POST|DELETE /api/user/users[/:userId|/permissions] - a set of endpoints for user management
• tokenExpiration (default: 1209600 = 14 days) - the lifetime of a login session before the token gets invalidated in seconds
• userAdminPermission (default: admin) - the label for the admin privilege that allows to manage users
• defaultPermissions (default: [] - none) - a list of user permissions newly created users will receive
• noUserManagement (default false) - a flag indicating whether to register user management endpoints (get all users, update permissions, delete user and create user)
• apiKeys (default false) - a flag indicating whether API keys are available in the system for creating and revoking keys as well as recognising API keys during login.
• allowOwnProfileEdit (default false) - a flag that when set to true allows any logged in user to update their own profile information (user.profile).
• pageSize (default 25) - the maximum number of users to return with the /users endpoint.