nxus-users

Build Status">

User management module for Nxus apps. Users provides a complete framework for managing users, authenticating routes and sessions.

Install

> npm install nxus-users --save

Quickstart

Once Users is installed in your app, you are ready to go. It includes the following components:

• user/team models
• login/logout routes
• authentication/session middleware

Models

Uses defines a set of common models you can use to build your application, using the @nxus/storage module (which uses Waterline to provide common ORM functionality).

User

Accessing the user model:

storage.getModel('users-user').then((User) => {
  ...
});

Fields

• email: string
• password: string
• nameFirst: string
• nameLast: string
• position: string
• enabled: boolean
• admin: boolean
• lastLogin: datetime
• metadata: JSON
• team: relation to Team model

Convenience Methods

• name(): first + last name
• isAdmin(): boolean if user is an Admin
• validPassword(pass): returns true if the password is valid

Templates

Users defines a set of common templates you can use in your app

login

A login form preconfigured to work with the login/logout routes. Markup supports basic Bootstrap 3 CSS.

templater.render('users-login').then((content) => {
  ...
}

Routes

The Users module defines some convience routes for handling basic user functionality.

/login

Params Expects to recieve a POSTed form with the values username, password and redirect. redirect should be a url to redirect the user to on success. On login failure, the user will be redirected back to /login.

/logout

Params Expects to recieve a GET request with the param redirect, which is a url where the user will be redirected on successful logout.

API

---

Users

Extends HasModels

The Users Module provides a complete user authentication and authorization system.

UsersPermissions

Extends HasModels

Permissions system

This module provides a role & permission list approach to managing user access in Nxus. Routes (or other guarded functionality) is associated with a Permission name, and permissions are assigned to Roles. A User may have multiple roles, and a permission may belong to multiple roles.

Permissions and roles can also be scoped to specific model objects, allowing users access to just those objects they own or have been given a role in managing.

Usage

`import {permissions} from 'nxus-users'

Registering permissions and roles

`permissions.register('permission-name', ['Default Role'])

Guarding routes and handlers

`permissions.guard('/my/route', 'permission-name')

`permissions.guardHandler(::this._myRoute, 'permission-name').then((handler) => { router.route('/my/route', handler) })

Checking for user permissions in handlers/templates

req.user.permissions.allows('permission-name')req.user.permissions.allows('permission-name', object)

Object-level permissions

Object role assignments need a collection object that subclasses ObjectRoleModel and overrides the object attribute:

import {ObjectRoleModel} from 'nxus-users'
export default ObjectRoleModel.extend{{
identity: 'my-object-roles',
attributes: { object: { model: 'my-object'}}
}}

The permissions should be registered with an extra argument naming this model collection:

`permissions.register('my-object-permission', ['Object Editor'], 'my-object-roles')

Alternatively, this may be a function that accepts (objectId, user) and returns the roles assigned - This can implement traversing the object model to reach a parent with the permissions, or entirely override how and where role assignments are stored.

Guards should be set with the extra argument naming the URL param to use as objectId to lookup.

`permissions.guard('/edit/:id', 'my-object-permission', 'id')

Parameters

• opts (optional, default {})