nxus-users v4.1.1
nxus-users
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{}
)
5 years ago
5 years ago
6 years ago
7 years ago
7 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago