umpack

user management pack for express framework app.

you can use this package in typescript too.

Install Guide

Install npm package

1npm install umpack-express -S -E

Set Options and Router(express app)

• accessTokenExpiresIn time span string description

1var umpack = require('umpack-express')({
2    mongodbConnectionString: 'mongodb://172.17.7.92:27017/umpack',
3    accessTokenSecret: 'myrandomstring',
4    passwordHashSecret: 'mypasswordsecret',
5    accessTokenExpiresIn: '1m',
6    cookieAccessTokenName: 'accessToken',
7    passwordResetData: {
8      smtpData: {
9        host: 'smtp host',
10        port: 'smtp port. optional',
11        user: 'username for logging into smtp',
12        password: 'password for logging into smtp',
13        timeout: 5000, // number of milliseconds to wait. default 5000
14        ssl: false //boolean or object with fields: key, ca, cert. default false
15      },
16      senderEmail: 'sender@email.com',
17      resetKeyExpiresIn: '2h', //password reset key expiration
18      passwordMessageFunction: function (key /*password reset key*/) {
19        return 'message to send. use key. for example: http://example.com?key=' + key;
20      },
21      passwordWrongEmailInstruction: function (clientIp) {
22        return 'someone with ip: ' + clientIp + ' requested password reset on the site example.com'; //message to send to input email, when user with input email does not exist
23      }
24    },
25    passwordResetPhoneData: {
26      resetKeyExpiresIn: '2h',
27      sendResetKey: function (phone, resetKey) {
28        // send sms to the phone.
29        // return promise or nothing.
30      }
31    },
32    deviceControl: false, // default false. if it is true, user's devices access is controlled
33    userNameCaseSensitive: false, // if it is true, userName is case sensitive, if false - it is not.
34    logger: loggerObject, // loggerObject should have methods: error, warn, info, debug and trace. it should have logging level restriction itself.
35    // by default logger field is logger object that logs only warnings and errors.
36    activateOnSignup: false, // if true, when user signs up account doesn't need to activate
37    userDefaultRole: 'user' //not works if activateOnSignup is false. on signup user has this role
38});
39//.....
40app.use('/um', umpack.router);
41//.....

umpack API Methods

This methods should be called without authorization header

Login

1POST : {baseurl}/login
2request - data/body : {
3  userName: 'user',
4  email: 'user@test.com', // userName or email is required
5  password: 'userpassword',
6  deviceToken: 'device token' //required if device control is enabled
7}
8response - 'user access token'

Signup

1POST : {baseurl}/signup
2request - data/body : {

3    userName: 'user', //required

4    password: 'userpassword', //required

5    firstName: 'first name',

6    lastName: 'last name',

7    email: 'user@test.com',

8    phone: '123456',

9    address: 'usa/de',

10    additionalInfo: 'user additional info',
11    }
12response - { success: true, message: 'Thanks for signUp' }

Next methods requires authorization header (access token).

1headers:{'authorization': 'user access token'}

Password Reset

1POST : {baseurl}/resetpass
2request - data/body : {
3    userName: 'admin',
4    oldPassword: 'admin',
5    newPassword: '123456789'
6}
7response - { success: true, message: 'Password Reset Done' }

Get all users

1GET : {baseurl}/users
2response - {
3                id: '34jhb5jh45b6',
4                userName: 'user name',
5                isActivated: 'true/false',
6                roles: ['admin','provider','root','etc.']
7            }

Get all roles

1GET : {baseurl}/roles
2response - [{name:'admin', description: ''},{name:'user', description: ''},{name:'provider', description: ''},{name:'root', description: ''},{name:'organizationUser', description: ''}]

Update user status (Activate / Deactivate)

1POST : {baseurl}/updateUserStatus
2request - data/body : {
3        id: 'user id',
4        isActivated: true/false,
5    }
6response - {
7                id: 'user id',
8                isActivated: 'true/false',
9                userName: 'user name',
10                roles: ['admin','provider','root','sys','etc.']
11            }

Update user roles (assigne or remove role from user)

1POST : {baseurl}/updateUserRoles
2request - data/body : {
3        userId: 'user id',
4        roleName: 'admin',
5        enable: 'true/false'
6    }
7response - {
8                id: 'user id',
9                isActivated: 'true/false',
10                userName: 'user name',
11                roles: ['admin','provider','root','sys','etc.']
12            }

Get User Object

1GET : {baseurl}/users/{userId}
2response - {
3  id: '',
4  userName: 'name',
5  firstName: 'firstName',
6  lastName: 'lastName',
7  email: 'test@email.com',
8  phone: '',
9  address: '',
10  additionalInfo: '',
11  isActivated: true/false,
12  roles: ['user', 'admin'],
13  metaData: {}
14}

Get User Object By userName

1GET : {baseurl}/users/{userName}/full
2response - {
3  id: '',
4  userName: 'name',
5  firstName: 'firstName',
6  lastName: 'lastName',
7  email: 'test@email.com',
8  phone: '',
9  address: '',
10  additionalInfo: '',
11  isActivated: true/false,
12  roles: ['user', 'admin'],
13  metaData: {}
14}

Change User's userName

1PUT : {baseurl}/users/{userId}/username
2request - data/body : {
3  userName: 'userName'
4}
5response - {success : true}

Change User Info

1PUT : {baseurl}/users/{userId}/info
2request - data/body : {
3  firstName: '',
4  lastName: '',
5  email: '',
6  phone: '',
7  address: '',
8  additionalInfo: ''
9}
10response - {success : true}

Delete User

1DELETE : {baseurl}/users/{userId}
2response - {
3  success: true
4}

Lost Password Reset Request

1POST : {baseurl}/users/passwordResetRequest
2request - data/body : {
3  email: 'test@email.com'
4}
5response - {success : true}
6instructions are sent to the email

Lost Password Reset

1POST : {baseurl}/users/passwordReset
2request - data/body : {
3  resetKey: '', //password reset key sent to the email
4  newPassword: 'password'
5}
6response - {success : true}

Lost Password Reset By Phone Request

1POST : {baseurl}/users/{userName}/passwordResetRequestByPhone
2request - data/body : {} //empty object
3response - {success : true}
4password reset key is sent to the user phone

Lost Password Reset By Phone

1POST : {baseurl}/users/{userName}/passwordResetByPhone
2request - data/body : {
3  resetKey: '', //key sent to the phone
4  newPassword: 'password'
5}
6response - {success : true}

Get User's All Registered Devices

1GET : {baseurl}/users/{userName}/devices
2response - [
3  {
4    deviceToken: 'token',
5    canAccess: true/false,
6    lastUsageDate: new Date() //last usage date
7  }
8]

Get User's All Permitted Devices

1GET : {baseurl}/users/{userName}/devices/permitted
2response - [
3  {
4    deviceToken: 'token',
5    canAccess: true,
6    lastUsageDate: new Date() //last usage date
7  }
8]

Grant User's Device Access

1POST : {baseurl}/users/{userName}/devices/access
2request - data/body : {
3  deviceToken: 'device token'
4}
5response - { success: true }

Restrict User's Device From Access

1POST : {baseurl}/users/{userName}/devices/restriction
2request - data/body : {
3  deviceToken: 'token'
4}
5response - { success: true }

Get metadata

1GET : {baseurl}/metadata
2response - metadata object

Update metadata

1PUT : {baseurl}/metadata
2request - data/body : metadata object
3response - { success: true, message: 'metadata updated' }

Set metadata field

1PUT : {baseurl}/metadata/{fieldName}
2request - data/body : {
3  value: 'some value of any type'
4}
5response - { success: true, message: 'metadata key: {fieldName} updated' }

Create New Role

1POST : {baseurl}/roles
2request - data/body : {
3  name: 'admin',
4  description: 'description'
5}
6response - { success: true }

Get Role Full Object

1GET : {baseurl}/roles/{roleName}
2response - {

3  name: 'admin',

4  description: 'description',

5  actions: [{

6    id: '464sadfsdf6',

7    pattern: '/api/*',

8    name: 'action name',

9    verbGet: true,

10    verbPost: true,

11    verbPut: true,

12    verbDelete: true,

13    verbHead: true
14  }]
15}

Change Role's name and description

1PUT : {baseurl}/roles/{roleName}
2request - data/body : {
3  name: 'role name',
4  description: 'role description'
5}
6response - { success: true }

Delete Role

1DELETE : {baseurl}/roles/{roleName}
2response: { success: true }

Permit Action to Role

1POST : {baseurl}/roles/{roleName}/actions
2request - data/body : {
3  pattern: '/api/*',
4  name: 'name',
5  verbGet: true,
6  verbPost: true,
7  verbPut: true,
8  verbDelete: true,
9  verbHead: true
10}
11response - {
12  success: true,
13  actionId: 'action id'
14}

Edit Role's Action

1PUT : {baseurl}/roles/{roleName}/actions/{actionId}
2request - data/body : {
3  pattern: '/api/something',
4  name: 'name',
5  verbGet: true,
6  verbPost: true,
7  verbPut: true,
8  verbDelete: false,
9  verbHead: false
10}
11response - { success : true }

Remove Permitted Action From Role

1DELETE : {baseurl}/roles/{roleName}/actions/{actionId}
2response - { success: true }

Umpack Initialization.

• saves root user and admin role if they do not exist.
• if device control is enabled, it saves one permitted device of the root for administration.

1POST : {baseurl}/initialization
2request - data/body : {

3  umBaseUrl: '/um',

4  deviceToken: 'token', //not required if device control is disabled

5  password: '123' // password for root user. optional. if it isn't passed new password is generated randomly.
6}
7response - {

8  success: true,

9  password: 'password' //generated or parameter password for root user
10}

Authorization Route

it is used for validating access token

1HEAD : {baseurl}/authorization

API Response Internal Statuses

• Every response with status 400/401 has also internal status for example :

1{message:User Is Not Activated, internalStatus:601}

• All internal status

1    { code: 601, message: 'User Is Not Activated' }
2    { code: 602, message: 'User Name Or Email Already Exists' }
3    { code: 603, message: 'Wrong User Name Or Password' }
4    { code: 604, message: 'Wrong Password' }
5    { code: 605, message: 'User Does Not Exists' }
6    { code: 606, message: 'Can\'t Find JWT Token Inside The Request Header' }
7    { code: 607, message: 'Invalid JWT Token' }
8    { code: 608, message: 'Token Expired' }
9    { code: 609, message: 'Access Denied' }
10    { code: 701, message: 'Wrong Role Name' }
11    { code: 702, message: 'Role Already Exists'}
12    { code: 703, message: 'Invalid Action Pattern'}
13    { code: 704, message: 'Action Pattern Already Exists'}
14    { code: 800, message: 'password reset key is expired' }
15    { code: 801, message: 'password reset key is invalid' }
16    { code: 802, message: 'password reset by email is not supported' }
17    { code: 803, message: 'password reset by phone is not supported' }
18    { code: 804, message: 'invalid phone number' }
19    { code: 805, message: 'invalid device token' }
20    { code: 806, message: 'access is denied for your device' }
21    { code: 807, message: 'devices control is not supported' }
22    { code: 900, message: 'invalid userName' }
23    { code: 901, message: 'invalid email' }

Use Authorization Middleware

• if user is not authorized then response status is 401
• if user has no access right then response status is 403
• if device control is enabled and user's device has no access right then response status is 403 too
• if response status is 401 or 403 response body is object with error message and internalStatus { message: err.message, internalStatus: err.internalStatus }

1var umpack = require('./umpack')();
2
3router.get('/', umpack.isAuthorized, function(req, res, next) {
4
5    return res.send('your resources');
6
7});

User's Metadata Management

• if you need to add additional info, attribute, etc. you can use user's metadata to manage it.
• metadata is custom field/subdocument of user doc which can contains any kind of object.
• example :

assigne/update user metadata

1    var organizationInfo = {
2        organizationId: '2222',
3        organiationName: 'bbbbb',
4        organizationTaxCode: '777777'
5    };
6
7    umpack.updateUserMetaData('admin', organizationInfo)
8        .then(function(result) {
9            console.log(result);
10        })
11        .catch(function(err) {
12            console.log(err.message);
13        });

get user metadata by user name

1router.get('/usermetadata', function(req, res, next) {
2
3     umpack.getUserMetaDataByUserName('admin')
4         .then(function(result) {
5             return res.send(result);
6         })
7         .catch(function(err) {
8             console.log(err.message);
9             return res.send({ message: err.message });
10         });
11
12
13
14});
15

get user metadata by request

1router.get('/usermetadata', function(req, res, next) {
2
3    umpack.getUserMetaDataByRequest(req)
4        .then(function(result) {
5            return res.send(result);
6        })
7        .catch(function(err) {
8            //console.log(err.message);
9            return res.status(400).send({ message: err.message });
10        });
11
12});
13

Filter users by metadata param

1router.get('/usersbymeta', function(req, res, next) {
2
3    umpack.filterUsersByMetaData('organizationId', '2222')
4        .then(function(users) {
5
6            res.send(users);
7
8        })
9        .catch(function(err) {
10
11            return res.status(400).send({ message: err.message });
12
13        });
14
15
16
17});

Get User Full Name

1router.get('/userFullName', function(req, res, next) {
2
3    umpack.getFullName('admin')
4        .then(function(fullName) {
5
6            res.send(fullName);
7
8        })
9        .catch(function(err) {
10
11            return res.status(400).send({ message: err.message });
12
13        });
14});

Get User Roles By User Name

1router.get('/userRoles', function(req, res, next) {
2
3     umpack.getUserRolesByUserName('admin')
4         .then(function(result) {
5             res.send(result);
6         })
7         .catch(function(err) {
8
9             return res.status(400).send({ message: err.message });
10
11         });
12
13});

Get User Roles From Request

1router.get('/userRoles', function(req, res, next) {
2
3    umpack.getUserRolesFromRequest(req)
4        .then(function(result) {
5
6            res.send(result);
7
8        })
9        .catch(function(err) {
10
11            return res.status(400).send({ message: err.message });
12
13        });
14});
15

Filter users by role

1router.get('/usersbyrole', function(req, res, next) {
2
3    umpack.filterUsersByRole('user')
4        .then(function(result) {
5
6            res.send(result);
7
8        })
9        .catch(function(err) {
10
11            return res.status(400).send({ message: err.message });
12
13        });
14});
15

Get Full User Object

1router.get('/fullUserObject', function(req, res, next) {
2
3    umpack.getFullUserObject('admin')
4        .then(function(result) {
5
6            res.send(result);
7
8        })
9        .catch(function(err) {
10
11            return res.status(400).send({ message: err.message });
12
13        });
14});

Get Full User Object From Request

1router.get('/fullUserObject', function(req, res, next) {
2
3    umpack.getFullUserObjectFromRequest(req)
4        .then(function(result) {
5
6            res.send(result);
7
8        })
9        .catch(function(err) {
10
11            return res.status(400).send({ message: err.message });
12
13        });
14});

Initialize Umpack

• saves root user and admin role if they do not exist.
• if device control is enabled, it saves one permitted device of the root for administration.

1router.get('/initialization', function(req, res, next) {
2
3    //password is optional
4    umpack.init(req.body.umBaseUrl, req.body.password, req.body.deviceToken) // if deviceControl is disabled deviceToken is not required else it is required
5        .then(function(password) {
6            // randomly generated password or passed parameter password for the root user is returned
7            res.send(password);
8
9        })
10        .catch(function(err) {
11
12            return res.status(400).send({ message: err.message });
13
14        });
15});

Initialize Umpack With Full Api Access to admin Role

• saves root user and admin role if they do not exist.
• saved admin role has permission of everything.
• if device control is enabled, it saves one permitted device of the root for administration.

1router.get('/initialization', function(req, res, next) {
2
3    //password is optional
4    umpack.initWithFullAccess(req.body.password, req.body.deviceToken) // if deviceControl is disabled deviceToken is not required else it is required
5        .then(function(password) {
6            // randomly generated password or passed parameter password for the root user is returned
7            res.send(password);
8
9        })
10        .catch(function(err) {
11
12            return res.status(400).send({ message: err.message });
13
14        });
15});

Get UserName From Request

1router.get('/userRoles', isAuthorized, function(req, res, next) {
2
3    // Request Must Have authorization Header
4    umpack.getUserNameFromRequest(req)
5        .then(function(userName) {
6
7            res.send(userName);
8
9        })
10        .catch(function(err) {
11
12            return res.status(400).send({ message: err.message });
13
14        });
15});

Signup method

1router.get('/signup', function(req, res, next) {
2
3  // {
4  //     userName: 'user',
5  //     password: 'userpassword',
6  //     firstName: 'first name',
7  //     lastName: 'last name',
8  //     email: 'user@test.com',
9  //     phone: '123456',
10  //     address: 'usa/de',
11  //     additionalInfo: 'user additional info',
12  // }
13  // parameters are exactly same as in /{baseurl}/signup
14
15    umpack.signup(req.body)
16        .then(function() {
17
18            res.send({success: true});
19
20        })
21        .catch(function(err) {
22
23            return res.status(400).send({ message: err.message });
24
25        });
26});