A global singleton what contains information about the logged in user. Server reassign properties of this object each time endpoint handler are executed

Implements EventEmitter and will emit login event each time user logged in or loginFailed event with 2 parameters(isLocked, userName) when user UB authentication failed

      const UB = require('@unitybase/ub')
const Session = UB.Session

# new Session ()


# callerIP : string static

IP address of a user. May differ from IP address current user login from. May be empty if request come from localhost.

# id : string static

Current session identifier

# pendingUserName : string static

User name for authentication in pending state

# tenantID : number static

ID of the tenant (for multitenancy applications). 0 if multitenancy is not enabled (see ubConfig.security.tenants)

# uData : Object static

Custom properties, defined in Session.on('login') handlers for logged-in user. We strongly recommend to not modify value of uData outside the Session.on('login') handler - such modification is not persisted between calls.

Properties documented below are added by @unitybase/uba model, but other model can define his own properties.

Name Type Description
userID number

Logged in user ID. The same as Session.userID. Added by ub model

login string

Logged in user name. Added by ub model

roles string

Logged in user roles names separated by comma. In most case better to use uData.roleIDs array. Added by ub model

roleIDs Array.<number>

Array or role IDs for logged in user. Added by ub model

groupIDs Array.<number>

Array or group IDs for logged in user. Added by ub model

employeeShortFIO string

Short name of the employee. Added by ub model from uba_user.firstName. org model override it

employeeFullFIO string

Full name of the employee. Added by ub model from uba_user.fullName. org model override it

employeeID number

Employee ID

staffUnitFullName string
staffUnitName string
staffUnitID number

permanent staffUnitID. Added by org model

employeeOnStaffID number

permanent employeeOnStaffID. Added by org model

parentID number

permanent staffUnitID parent. Added by org model

parentUnityEntity string

permanent staffUnitID parent entity type. Added by org model

orgUnitIDs string

all orgUnit's IDs as CSV string. Added by org model

permanentOrgUnitIDs string

all user orgUnit ID's permanent employeeOnStaffIDs in CSV. Added by org model

tempStaffUnitIDs string

array temporary staffUnitIDs in CSV. Added by org model

tempEmployeeOnStaffIDs string

array of temporary employeeOnStaffIDs in CSV. Added by org model

assistantStaffUnitIDs string

array of assistant staffUnitIDs in CSV. Added by org model

assistantEmployeeOnStaffIDs string

array of assistant employeeOnStaffIDs in CSV. Added by org model

allStaffUnitIDs string

array of all (permanent + temporary + assistant) staffUnitIDs in CSV. Added by org model

allEmployeeOnStaffIDs string

array of all (permanent + temporary + assistant) employeeOnStaffIds in CSV. Added by org model

tempPositions string

stringified array ob temporary position objects: {staffUnitID, employeeOnStaffID}. Added by org model

assistantPositions string

stringified array ob assistant position objects: {staffUnitID, employeeOnStaffID}. Added by org model

allPositions string

stringified array of permanent + temporary + assistant position objects: {staffUnitID, employeeOnStaffID}. Added by org model

# userID : number static

Logged-in user identifier (from uba_user.ID)

# userLang : string static

Logged-in user language. ==="" if no authentication running

# userRoleNames : string deprecated static

Logged-in user role names in CSV format. ==="" if no authentication running

Use `Session.uData.roles`

# userRoles : number deprecated static

Logged-in user role IDs in CSV format. ==="" if no authentication running

Use `Session.uData.roleIDs` - an array of roles IDs

# zone : string static

Security zone for current session. In UB SE empty string


# _buildPasswordHash (uNamestring, uPwdPlainstring) → string static

Build password hash based on user login and plain password Called by server during authorization handshake.

In case application need to use it's own hash algorithm in can override this function inside model initialization. Maximum result length is 64 char. Result is case sensitive.


password hash to be stored/compared with uba_used.uPasswordHashHexa


# runAsAdmin (funcfunction) → * static

Call function as build-in admin user. runAs* functions allow maximum of 2 level depth of recursion.

Built-in "always alive"(newer expired) admin session is always created when the application starts, so this is very cheap method - it will not trigger Session.login event every time context is switched (Session.setUser and Session.runAsUser does) Can be used in scheduled tasks, not-authorized methods, etc. to obtain a admin Session context

  • func: function

    Function to be called in admin context

# runAsUser (userID, func) → * static

Call function as a specified user. runAs* functions allow maximum of 2 level depth of recursion.

New session will be created. Will fire login event.

  • userID:

    ID of user

  • func:

    Function to be called in user's session.

# setUser (userIDNumber, secretoptString, persistoptBoolean) → String static

Create new session for userID


JSON string like answer on auth request

  • userID: Number

    ID of user

  • secret: String

    secret word. If defined then session secretWord is JSON.parse(returns).result+secret

  • persist = true: Boolean

    Create persisted session (memorise session in session manager, so in can be used in future requests)


# login  --> (reqTHTTPRequest)

Fires just after user successfully logged-in but before auth response is written to client. Model developer can subscribe to this event and add some model specific data to Session.uData.

Since all uData content is passed to client and accessible on client via $App.connection.userData(someCustomProperty) do not add there a security sensitive data.

Standard models like @unitybase/uba and @unitybase/org are subscribed to this event and add most useful information to the uData - Session.uData documentation. Never override uData using Session.uData = {...}, in this case you delete uData properties, defined in other application models. Instead define or remove properties using Session.uData.myProperty = ... or use delete Session.uData.myProperty if you need to un-define something.

Example below add someCustomProperty to Session.uData. See also a real life example in @unitybase/org/org.js

      // @ param {THTTPRequest} req
Session.on('login', function (req) {
  const uData = Session.uData
  uData.someCustomProperty = 'Hello!'

# loginFailed  --> (shouldLockboolean, userNamestring)

Fires in case auth endpoint is called with authentication schema UB and userName is founded in database, but password is incorrect.

If wrong password is entered more than UBA.passwordPolicy.maxInvalidAttempts(from ubs_settings) times user will be locked

      Session.on('loginFailed', function(shouldLock, userName){
 if (shouldLock)
   console.log('User ', userName, 'entered wrong password and locked')
   console.log('User ', userName, 'entered wrong password')

# registration  --> ()

Fires in case new user registered in system and authentication schema support "registration" feature.

Currently only CERT and UB schemas support this feature.

For CERT schema user registered means auth endpoint is called with registration=1 parameter.

For UB schema user registered means 'publicRegistration' endpoint has been called and user confirmed registration by email otp.

Inside event handler server-side Session object is in INCONSISTENT state and you must not use it!! Only parameter (stringified object), passed to event is valid user-relative information.

For CERT schema parameter is look like

     "authType": 'CERT',
     "id_cert": '<id_cert>',
     "user_name": '<user_name>',
     "additional": '',
     "certification_b64": '<certification_b64>'

For UB schema parameter is look like

     "authType": 'UB',
     "publicRegistration": true,

Each AUTH schema can pass his own object as a event parameter, but all schema add authType. Below is a sample code for CERT schema:

 Session.on('registration', function(registrationParams){


# securityViolation  --> (reasonstring)

Fires in case of any security violation:

  • user is blocked or not exists (in uba_user)
  • user provide wrong credential (password, domain, encripted secret key, certificate etc)
  • for 2-factor auth schemas - too many sessions in pending state (max is 128)
  • access to endpoint "%" deny for user (endpoint name not present in uba_role.allowedAppMethods for eny user roles)
  • password for user is expired (see ubs_settings UBA.passwordPolicy.maxDurationDays key)
  • access to entity method is denied by ELS (see rules in uba_els)

      const Session = require('@unitybase/ub').Session
Session.on('securityViolation', function(reason){
   console.log('Security violation for user with ID', Session.userID, 'from', Session.callerIP, 'reason', reason);