Session

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(userID, isLocked) when user UB authentication failed

Members

callerIP: stringstatic #

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

id: numberstatic #

Current session identifier. === 0 if session not started, ===1 in case authentication not used, >1 in case user authorized

uData: Objectstatic #

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 roles. Added by ub model

groupIDs Array<number>

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

employeeShortFIO string

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

employeeFullFIO string

Full name of 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: numberstatic #

Logged-in user identifier (from uba_user.ID). Undefined if Session.id is 0 or 1 (no authentication running)

userLang: stringstatic #

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

userRoleNames: stringdeprecatedstatic #

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

Use Session.uData.roles

userRoles: numberdeprecatedstatic #

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

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

Methods

runAsAdmin(func: function)→*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

Arguments info:

  • 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.

Arguments info:

  • userID:

    ID of user

  • func:

    Function to be called in user's session.

setUser(userID: Number, secretopt: String)→Stringstatic#

Create new session for userID

Return:

JSON string like answer on auth request

Arguments info:

  • userID: Number

    ID of user

  • secret: String

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

Events

login static #

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 undefine something.

Example below add someCustomProperty to Session.uData:

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

See real life example inside @unitybase/org/org.js.

loginFailed static #

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

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

2 parameters are passes to this event userID(Number) and isUserLocked(Boolean)

 Session.on('loginFailed', function(userID, isLocked){
     if (isLocked)
         console.log('User with id ', userID, 'entered wrong password and locked');
     else
         console.log('User with id ', userID, 'entered wrong password');
 })

newUserRegistration static #

Legacy event CERT authentication schema only

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

Called before start event "registration" and before starting check the user. You can create new user inside this event.

Parameter is look like

 {
     "authType": 'CERT',
     "serialSign": '<serialSign>',
     "name": '<user name>',
     "additional": '',
     "issuer": '<issuer>',
     "serial": '<serial>',
     "certification_b64": '<certification_b64>'
 }

registration static #

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,
     userID,
        userOtpData
 }

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 static #

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)
  • entity method access deny by ELS (see rules in uba_els)

Single parameter is passes to this event reason: string

 Session.on('securityViolation', function(reason){
     console.log('Security violation for user with ID', Session.userID, 'from', Session.callerIP, 'reason', reason);
 })