ghost-express-auth
v1.2.5
Published
nodejs client to handle authorization for express apps
Downloads
16
Readme
Ghost Express Auth Module
Installation
npm install ghost-express-auth --save
Overview
This module is built on top of express and can be imported as a means to handle user authentication in your application. Pass in a configuration file and your DB, and the module defines routes to handle login, registration, password reset and role management.
There are also various exposed middleware objects that can be used for managing user access and permissions.
Router
const GhostExpressAuth = require('ghost-express-auth');
const GhostAuth = new GhostExpressAuth(config, Db);
const AuthRouter = GhostAuth.AuthRouter;
app.use('/auth', AuthRouter);
The following methods are available:
| Endpoint | Description | | ---- | --------------- | | GET /authorized | Get authorization | | GET /request-password-reset/:email | Request an email with a link to reset password | | GET /verify-reset-token/:token | Verify that a reset token exists and has not been used | | POST /login | Login | | POST /register/:role | Register | | POST /reset-password | Reset a password |
Example Request
$http({method: 'GET', url: "/auth/authorized"})
.then(response => ...)
.catch(response => ...)
Example Response
{
"profile": {
"id": 1,
"name": "Justin Tucker"
},
"authorization": {
"role": "user"
},
"status": "ACTIVE"
}
Example Request
const requestPasswordReset = (email) => {
return $http({method: 'GET', url: '/auth/request-password-reset/' + email})
.then(response => ...)
.catch(response => ...)
}
Response
200
success, email sent
4**
email address is not in system
5**
server error
Example Request
const verifyResetToken = (tokenId) => {
return $http({method: 'GET', url: '/auth/verify-reset-token/' + tokenId})
.then(response => ...)
.catch(response => ...)
}
Response
200
token is valid and unused
4**
token is expired (over 24 hours old) or already used
5**
server error
Example Request
const login = (email, password) => {
$http({method: 'POST', url: "/auth/login", data: {email: email, password: password} })
.then(response => ...)
.catch(response => ...)
}
Example Response
Note: tkn is returned as an encoded JWT string
{
"tkn": {
"user": 1,
"expires": "1/1/2017",
"role": "admin"
},
"role": "admin"
}
Example Request
const register = (email, password, role) => {
$http({method: 'POST', url: "/auth/register/" + role, data: {email: email, password: password} })
.then(response => ...)
.catch(response => ...)
}
Example Response
Note: tkn is returned as an encoded JWT string
{
"tkn": {
"user": 1,
"expires": "1/1/2017",
"role": "admin"
},
"role": "admin"
}
Example Request
Note: the server will validate that the provided reset token ID is linked to the provided email address.
/**
* @param {Object} data
* @param {String} data.email
* @param {String} data.password
* @param {String} data.token
* @returns {Promise}
*/
const resetPassword = (data) => {
$http({method: 'POST', url: "/auth/reset-password", data: data })
.then(response => ...)
.catch(response => ...)
}
Response
200
token is valid and unused
4**
token is expired (over 24 hours old), already used, or not linked to provided email address
5**
server error
Config
authSecret
: Secret key used for Bearer authorization tokensemail
: Configure email settingsenabled
: [BOOLEAN] if enabled, module will attempt to use email functionality,baseUrl
: the base url of your website, to be used in generating urls sent as substitutions in emails,processor
: ['mailchimp'|'sendgrid'] *currently only supporting mailchimpmailchimp
:defaults
: email defaultsfromEmail
fromName
replyTo
templates
: the various available templates for emails. each has 2 propertiestemplateName
andsubject
passwordResetNotification
: sent to user upon successful password resetpasswordResetRequest
: sent to user upon requesting a password reset,welcome
: sent to user upon registering
roles
: Configure user role settings{roleObject}
An object whose key is the name of the user role (e.g. 'user', 'admin', 'guest').notifyAdminsOnRegistration
: Notifying all users with 'admin' role when a user with this role registers. The following variables will be available in the template: userName, userEmail, registeredAt, userRoleenabled
[BOOLEAN] whether or not to implement notification logictemplateName
[String] the template of the email to send adminssubject
[String]
Example config file
{
"authSecret": "super$ecure",
"email": {
"enabled": true,
"baseUrl": "http://192.168.99.100:4000",
"processor": "mailchimp",
"mailchimp": {
"defaults": {
"fromEmail": "[email protected]",
"fromName": "The Email Guy",
"replyTo": "[email protected]"
},
"secretKey": "[your mailchimp secret key]",
"mandrill": "[your mandrill key]"
},
"templates": {
"passwordResetNotification": {
"templateName": "password_reset_notification",
"subject": "Password Reset Notification"
},
"passwordResetRequest" : {
"templateName": "password_reset_request",
"subject": "Password Reset Request"
},
"welcome": {
"templateName": "welcome_user",
"subject": "Welcome to Ghost Creative!"
}
}
},
"roles": {
"user": {
"level": 1,
"notifyAdminsOnRegistration": {
"enabled": true,
"templateName": "new_user_notification",
"subject": "Ghost Creative Has a New Patient!"
},
"secret": "IMALITTLETEAPOT",
"welcomeEmail": {
"templateName": "welcome_user",
"subject": "Welcome to Ghost Creative!"
}
},
"admin": {
"level": 2,
"notifyAdminsOnRegistration": {
"enabled": true,
"templateName": "new_admin_notification",
"subject": "New Ghost Creative Admin Registration"
},
"secret": "admins",
"welcomeEmail": {
"templateName": "welcome_admin",
"subject": "Welcome to Ghost Creative!"
}
}
}
}