@isoftdata/isoft-authentication

ISoft Authentication :closed_lock_with_key:

A cross-platform solution to authenticating requests and session management using a normal ISoft style database schema.

Install

npm i @isoftdata/isoft-authentication

Version Notes

12.x

• Breaking Change: All functions now take DatabaseConnectionInterfaces as arguments instead of raw mysql connections. This is to facilitate both MySQL1 or MySQL2 systems. In General, callers will want to do something like:

import { MySQL2ConnectionWrapper } from '@isoftdata/utility-db'

const connectionWrapper = new MySQL2ConnectionWrapper(ctx.rawConnection)

const result = await createSession(connectionWrapper, userName, password, siteId, 'plant',)

• Breaking Change: Supporting both mysql and mysql2/mysql2/promise through @isoftdata/utility-db's new MySQL*ConnectionWrappers. Instead of passing a raw pool or connection into the various functions, do something like:

const myWrapper = new MySQL2ConnectionWrapper(aBasicMySQL2Connection)
const myOtherWrapper = new MySQL2PoolConnectionWrapper(aConnectionFromAPool)
const myPoolWrapper = new MySQL2PoolWrapper(pool)

The wrapper classes are generics and can handle either arguments constructed from mysql2 or mysql2/promise. Similar wrappers exist for mysql, just replace 2 with 1. This provides a generic interface to the module.

11.x

• Breaking Change: Exported prop backupEMailField -> backupEmailField on the exported functions getUser, getAPIUser, and checkUserPassword

10.x

• Breaking Change: Switched to ESM

9.x

• Added MySQL 8 support, which means mysql's PASSWORD function has been removed. This means that any account currently secured with the mysql PASSWORD() function will not be able to log in anymore.

Usage

import {createSession, checkSession, closeSession} from '@isoftdata/isoft-authentication'
import {connection} from './myDatabaseConnection'

let token

// Start a session
const { authenticated, status, session } = await createSession(connection, 'user', 'secret', 1)
if (authenticated) {
    console.log('Welcome!')
    token = session.token
}
else console.log(`Sorry, ${status}!`)

// Check the session
const { authenticated, status } = await checkSession(connection, token)
if (authenticated) { console.log('OK!') } // do some stuff
else console.log(`Sorry, ${status}`)

// Close the session
await closeSession(connection, token)

API Reference

createSession

This is the method you'll want to call when a user logs in. It handles checking their password and returning a session or an error response.

Argument	Description
connection	a MySql Connection, Pool, or PoolConnection
userName	string - name of the account
password	string - password for the account
siteId	number - which site to log into at the company
site	string, optional - defaults to "store", name of the site type

Returns a Promise that resolves to an AuthenticationResponse object

checkSession

This method checks the session status and optionally calls p_session_keep_alive() to refresh it.

Argument	Description
connection	a MySql Connection, Pool, or PoolConnection
token	string - the token string
options	object optional - with the following optional properties: site(string, defaults to store), getSession(boolean, defaults to false), keepAlive(boolean, defaults to true).

Returns a Promise that resolves to an AuthenticationResponse object.

closeSession

This method calls the p_session_end() stored procedure for you.

Argument	Description
connection	a MySql Connection, Pool, or PoolConnection
token	string - the token string

Returns a Promise that resolves, or rejects if p_session_end() throws a MySql error.

initiatePasswordRecovery

This method starts the process for the user resetting their password. It sends an email to the recovery email address with a resetToken(see changedPassword). Normally you would call changePassword after the user provides the resetToken provided in the email.

• Takes a single object argument with the following properties:

Property	Description
connection	a MySql Connection, Pool, or Pool Connection
userName	string - name of the account
fromEmail	string - optional - defaults to "[e-mail]"
productTitle	string - optional - defaults to "ITrack". Used in email from and body

Returns a Promise that resolves to an object which has a userName and recoveryEmail property. The recoveryEmail address will be obfuscated so that it can be shown on the client without fully exposing the user's email address.

changePassword

• Takes a single object argument with the following properties:

Property	Description
connection	a MySql Connection, Pool, or Pool Connection
userName	string - name of the account
resetToken	string - token given to the user when initiatePasswordRecovery was called
currentPassword	string - the user's current password
newPassword	string - the new password to set for the user
enforcePasswordRules	boolean - optional (defaults true) - check the password rules in setting if this is set to true
forcePasswordChange	boolean - optional (defaults false) - force a password change without resetToken OR currentPassword OR user needing to be in Pending status

Either resetToken OR currentPassword is required when forcePasswordChange is false

checkUserPassword

• Takes a single object argument with the following properties:

Property	Description
connection	a MySql Connection, Pool, or Pool Connection
userName	string - name of the account
password	string - the password to check
userInfo	object - optional - an object that contains information about the user
checkPendingStatus	boolean - optional(defaults true) - If false the pending status will be ignored and the password will just be checked.

What is Required?

Schema

Some schema is currently required on a new database for this module to work correctly:

Tables:

• useraccount with the columns:
  • useraccountid
  • name
  • [backup email field] the name of this field is an argument to checkSession
  • recoveryemail
  • firstname
  • lastname
  • passwordencoding
  • passwordkey
  • passwordsalt
  • status
  • locknotes
  • resettoken
  • resetexpiration
• [site] where site is one of ('plant', 'store', 'region')
• useraccess with the columns:
  • useraccessid
  • useraccountid
  • username
  • currentuseraccountid
  • accesstype
  • accessstatus
  • sessionstatus
  • sessiontoken
  • lastaccess
  • date
  • accesssource
  • ${site}id where site is one of ('plant', 'store', 'region')

Functions and stored procedures:

• Function f_useraccount_has_site_access(nUserID INT, nSiteID INT) RETURNS BOOL
• Functions f_BIN_TO_UUID and f_UUID_TO_BIN
• Function f_get_setting
• Stored procedure p_session_start
• Stored procedure p_session_keep_alive
• Stored procedure p_session_end

MySQL Options

If multipleStatements is not enabled on the MySQL connection, checkSession will error if keepAlive = true, which it is by default.