Skip to content

Sessions in Node++

Jump to bottom
Jurek Muszyński edited this page Jun 13, 2022 · 6 revisions

Overview

Node++ provides a session mechanism.

A session can be in one of the two states: anonymous or logged in. Anonymous session is identified with as cookie, whereas logged in with ls cookie.

There are two factors affecting whether the first HTTP request from a client starts a session or not:

  1. Default resource authorization level for the entire application, set with NPP_REQUIRED_AUTH_LEVEL. If not set, it's AUTH_LEVEL_NONE, which means that – unless set with npp_require_auth() – there are no sessions.

  2. Authorization level set for a particular resource with npp_require_auth(). It has a priority over NPP_REQUIRED_AUTH_LEVEL.

How to enable sessions

To enable sessions globally for the entire application, add to npp_app.h:

#define NPP_REQUIRED_AUTH_LEVEL AUTH_LEVEL_ANONYMOUS

Now every new request will create an anonymous session. This is the most popular option.

Resource authorization

To change required level just for one resource, add to npp_app_init():

npp_require_auth(NULL, "dashboard", AUTH_LEVEL_LOGGEDIN);

Now "dashboard" will require authenticated session. See npp_require_auth() for more examples.

Authorization levels

Authorization level is one of the resource's and the session's property. They can have one of the following values:

macro value notes
AUTH_LEVEL_NONE 0 No session is required.
AUTH_LEVEL_ANONYMOUS 1 Anonymous user session is required. If there's no valid as cookie, anonymous session is started.
AUTH_LEVEL_LOGGEDIN 2 Authenticated session is required. If request does not have valid ls cookie, it's redirected to URI defined in npp_app.h NPP_LOGIN_URI.
AUTH_LEVEL_USER
AUTH_LEVEL_CUSTOMER
AUTH_LEVEL_STAFF
AUTH_LEVEL_MODERATOR
AUTH_LEVEL_ADMIN
AUTH_LEVEL_ROOT		 10
20
30
40
50
100		 User has to have at least matching auth_level. Otherwise request will receive 404 (security by obscurity).
AUTH_LEVEL_NOBODY 125 Provided for whitelist-based access model, when high security is required. If NPP_REQUIRED_AUTH_LEVEL is set to AUTH_LEVEL_NOBODY, only resources explicitly set via npp_require_auth() will be accessible.

Static resources always have AUTH_LEVEL_NONE.

Session data structures

There are two data sets holding session information:

  1. Engine, defined in npp.h
/* engine session data */

typedef struct {
    /* id */
    char    sessid[NPP_SESSID_LEN+1];
    /* connection data */
    char    ip[INET_ADDRSTRLEN];
    char    uagent[NPP_MAX_VALUE_LEN+1];
    char    referer[NPP_MAX_VALUE_LEN+1];
    char    lang[NPP_LANG_LEN+1];
    char    formats;     /* date & numbers format */
    char    auth_level;
    /* users table record */
    int     user_id;
    char    login[NPP_LOGIN_LEN+1];
    char    email[NPP_EMAIL_LEN+1];
    char    name[NPP_UNAME_LEN+1];
    char    phone[NPP_PHONE_LEN+1];
    char    about[NPP_ABOUT_LEN+1];
    int     group_id;
    /* time zone info */
    short   tz_offset;
    bool    tz_set;
    /* CSRF token */
    char    csrft[NPP_CSRFT_LEN+1];
    /* internal */
    time_t  last_activity;
} eng_session_data_t;
  1. Application, defined in npp_app.h
/* app session data */
/* accessible via SESSION_DATA macro */

typedef struct {
    char dummy;     // replace with your own struct members
} app_session_data_t;

This part is meant to be extended by an app developer.

Session vs Connection

If a session has been created, every active connection keeps the pointer to it. Therefore, connection index (ci) can be used to access current session data. SESSION and SESSION_DATA macros are provided for this.

Upgrading / downgrading the session

These terms are used to indicate session state change.

  • Upgrade means switching the session state to logged in, after successful authentication. The engine then calls npp_app_user_login().

  • Downgrade means switching the session state back to anonymous. The engine then calls npp_app_user_logout().

LOGGED macro can be used to check whether current session is in logged in state.

Closing the session

Anonymous session is closed after session had been inactive for NPP_AUTH_SESSION_TIMEOUT seconds or npp_app_session_init() returned false.

Logged in sessions are not closed but downgraded to anonymous. This can happen either by calling npp_usr_logout() or after being inactive for NPP_AUTH_SESSION_TIMEOUT seconds.

ASYNC requests

User sessions are shared between the master (npp_app) process and the services (npp_svc). If the application part of the user session exceeds G_async_req_data_size, messages' sizes may need to be increased. See Data Exchange paragraph in ASYNC for details.

Clone this wiki locally