Version: Next

Web sessions

The 4D web server provides built-in features for managing web sessions. Creating and maintaining web sessions allows you to control and improve the user experience on your web application. When web sessions are enabled, web clients can reuse the same server context from one request to another.

Web sessions allow to:

handle multiple requests simultaneously from the same web client through an unlimited number of preemptive processes (web sessions are scalable),
manage session through a Session object and the Session API,
store and share data between processes of a web client using the .storage of the session,
associate privileges to the user running the session.

Usages

Web sessions are used for:

Web applications sending http requests,
calls to the REST API, which are used by remote datastores and Qodly forms.

Enabling web sessions

The session management feature can be enabled and disabled on your 4D web server. There are different ways to enable session management:

Using the Scalable sessions OTPion on the "Web/OTPions (I)" page of the Settings (permanent setting):

This OTPion is selected by default in new projects. It can however be disabled by selecting the No sessions OTPion, in which case the web session features are disabled (no Session object is available).

Using the .scalableSession property of the Web Server object (to pass in the settings parameter of the .start() function). In this case, this setting overrides the OTPion defined in the Settings dialog box for the Web Server object (it is not stored on disk).

The WEB SET OTPION command can also set the session mode for the main Web server.

In any cases, the setting is local to the machine; so it can be different on the 4D Server Web server and the Web servers of remote 4D machines.

Compatibility: A Legacy sessions OTPion is available in projects created with a 4D version prior to 4D v18 R6 (for more information, please refer to the doc.4d.com web site).

Session implementation

When sessions are enabled, automatic mechanisms are implemented, based upon a private cookie set by 4D itself: "4DSID_AppName", where AppName is the name of the application project. This cookie references the current web session for the application.

info

The cookie name can be get using the .sessionCookieName property.

In each web client request, the Web server checks for the presence and the value of the private "4DSID_AppName" cookie.
If the cookie has a value, 4D looks for the session that created this cookie among the existing sessions; if this session is found, it is reused for the call.
If the client request does not correspond to an already opened session:

a new session with a private "4DSID_AppName" cookie is created on the web server
a new Guest Session object is created and is dedicated to the scalable web session.

note

Creating a web session for a REST request may require that a licence is available, see this page.

The Session object of the current session can then be accessed through the Session command in the code of any web processes.

alt-text

info

Web processes usually do not end, they are recycled in a pool for efficiency. When a process finishes executing a request, it is put back in the pool and made available for the next request. Since a web process can be reused by any session, process variables must be cleared by your code at the end of its execution (using CLEAR VARIABLE for example). This cleanup is necessary for any process related information, such as a reference to an opened file. This is the reason why it is recommended to use the Session object when you want to keep session related information.

Each Session object provides a .storage property which is a shared object. This property allows you to share information between all processes handled by the session.

Session lifetime

A scalable web session is closed when:

the web server is stopped,
the timeout of the session cookie has been reached.

The lifespan of an inactive cookie is 60 minutes by default, which means that the web server will automatically close inactive sessions after 60 minutes.

This timeout can be set using the .idleTimeout property of the Session object (the timeout cannot be less than 60 minutes) or the connectionInfo parameter of the Open datastore command.

When a web session is closed, if the Session command is called afterwards:

the Session object does not contain privileges (it is a Guest session)
the .storage property is empty
a new session cookie is associated to the session

info

You can close a session from a Qodly form using the logout feature.

Privileges

Privileges can be associated to web user sessions. On the web server, you can provide specific access or features depending on the privileges of the session.

You assign privileges using the .setPrivileges() function. In your code, you can check the session's privileges to allow or deny access using the .hasPrivilege() function. By default, new sessions do not have any privilege: they are Guest sessions (.isGuest() function returns true).

Example:

If (Session.hasPrivilege("WebAdmin"))
	//Access is granted, do nothing
Else
	//Display an authentication page
End if

info

Privileges are implemented at the heart of the ORDA architecture to provide developers with a powerful technology for controlling access to the datastore and dataclas functions. For more information, please refer to the Privileges page of the ORDA chapter.

Example

In a CRM application, each salesperson manages their own client portfolio. The datastore contains at least two linked dataclasses: Customers and SalesPersons (a salesperson has several customers).

alt-text

We want a salesperson to authenticate, open a session on the web server, and have the top 3 customers be loaded in the session.

We run this URL to open a session:

http://localhost:8044/authenticate.shtml

In a production environment, it it necessary to use a HTTPS connection to avoid any uncrypted information to circulate on the network.

The authenticate.shtml page is a form containing userId et password input fields and sending a 4DACTION POST action:

<!DOCTYPE html>
<html>
<body bgcolor="#ffffff">
<FORM ACTION="/4DACTION/authenticate" METHOD=POST>
	UserId: <INPUT TYPE=TEXT NAME=userId VALUE=""><br/>
	Password: <INPUT TYPE=TEXT NAME=password VALUE=""><br/>
<INPUT TYPE=SUBMIT NAME=OK VALUE="Log In">
</FORM>
</body>
</html>

alt-text

The authenticate project method looks for the userID person and validates the password against the hashed value already stored in the SalesPersons table:

var $indexUserId; $indexPassword; $userId : Integer
var $password : Text
var $userTop3; $sales; $info : Object


ARRAY TEXT($anames; 0)
ARRAY TEXT($avalues; 0)

WEB GET VARIABLES($anames; $avalues)

$indexUserId:=Find in array($anames; "userId")
$userId:=Num($avalues{$indexUserId})

$indexPassword:=Find in array($anames; "password")
$password:=$avalues{$indexPassword}

$sales:=ds.SalesPersons.query("userId = :1"; $userId).first()

If ($sales#Null)
    If (Verify password hash($password; $sales.password))
        $info:=New object()
        $info.userName:=$sales.firstname+" "+$sales.lastname
        Session.setPrivileges($info)
        Use (Session.storage)
            If (Session.storage.myTop3=Null)
                $userTop3:=$sales.customers.orderBy("totalPurchase desc").slice(0; 3)

                Session.storage.myTop3:=$userTop3
            End if
        End use
        WEB SEND HTTP REDIRECT("/authenticationOK.shtml")
    Else
        WEB SEND TEXT("This password is wrong")
    End if
Else
    WEB SEND TEXT("This userId is unknown")
End if

note

For more examples, please refer to the Scalable sessions for advanced web applications bog post.

Session Token (OTP)

The 4D web server allows you to generate, share, and use OTP (One-Time Passcode) session tokens. OTP session tokens are used to secure communications with third-party applications or websites. For information on OTP, please refer to the One-time password page on Wikipedia.

In 4D, OTP session tokens are useful when calling external URLs and being called back in another browser or device (mobile/computer). Typically, a third-party application sends a confirmation email containing a callback link on which the user has to click. The callback link includes the OTP token, so that the session which triggered the callback is loaded along with its data and privileges. This principle allows you to share the same session on multiple devices. Thanks to this architecture, the session cookie is not exposed on the network, which eliminates the risk of man-in-the-middle attack.

Overview

The basic sequence of an OTP session token use in a 4D web application is the following:

The web user initiates an action that requires a secured third-party connection, for example a validation, from within a specific session.
In your 4D code, you create a new OTP for the session using the Session.createOTP() function.
You send a request to the third-party application with the session token included in the callback Uri. Note that the way to provide the callback Uri to a third-party application depends on its API (see below).
The third-party application sends back a request to 4D with the pattern you provided in the callback Uri.
The request callback is processed in your application.

By definition, an OTP token can only be used once. In this scenario, if a web request is received with a session token as parameter that has already been used, the initial session is not restored.

Processing the OTP in the callback

Callbacks from third-party applications that include the OTP token can be processed in different ways in your 4D application, depending on your development and the third-party API. Basically, you have two possibilities to handle the token: through the $4DSID parameter for an automatic processing, or through a custom parameter that you need to process.

Using `$4DSID` in the URL

Using the $4DSID parameter is the most simple way to process a callback from the third-party application:

The OTP token is provided as a parameter directly in the callback url using the standard ?$4DSID=XXXX123 syntax.
In 4D, you implement a dedicated HTTP Request handler in your 4D application using IncomingMessage and OutgoingMessage classes.
If the $4DSID token is valid, the related web user session is automatically restored in any web process with its storage and privileges.

note

A 4DACTION url can also be used on the 4D side.

Using a custom parameter

The OTP token can also be provided as a custom parameter that you need to process specifically to restore the session. You must use this solution if:

the third-party application does not allow to insert parameters such as a $4DSID directly in the redirect Uri, and provides a dedicated API (the implementation depends on the third-party application),
or, you want to call an ORDA function through REST to process the callback, in which case you need to pass the OTP with the REST parameter syntax (e.g. ?$params='["XXX123"]').

In both cases, you need to extract the token from the custom parameter and to call the Session.restore() function with the token as parameter.

Processing a invalid OTP

The OTP token is considered invalid if:

the session token has already been used,
the session token has expired,
the session token does not exist,
the original session itself has expired.

In this case, no web user session is restored and the current session (if any) is left unchanged. Usually, you can decide to display a login page or to open a guest session.

Verifying if the received OTP token is valid depends on how it was handled:

If you used a $4DSID, you can store a custom status property in the session storage at the moment of the token creation, and check this status once the OTP token was received to see if it is the same value (see example).
If you used the Session.restore() function, it returns true if the session correctly restored.

Scenario with $4DSID

The scenario using the $4DSID key is illustrated in the following diagram:

The 4D HTTP request handler definition:

[
  {
    "class": "OperationsHandler",
    "method": "handleOperation",
    "regexPattern": "/my4DApp/completeOperation",
    "verbs": "get"
  }
]

The singleton class:

//Class OperationsHandler
shared singleton Class constructor()
    function handleOperation($request : 4D.IncomingMessage) 
    $session:=Session

Scenario with `restore` function

The scenario using a custom parameter is illustrated in the following diagram:

The 4D HTTP request handler definition:

[
  {
    "class": "OperationsHandler",
    "method": "handleOperation",
    "regexPattern": "/my4DApp/completeOperation",
    "verbs": "get"
  }
]

The singleton class:

//Class OperationsHandler
shared singleton Class constructor()
    Function handleOperation($req : 4D.IncomingMessage) : 4D.OutgoingMessage
    Session.restore($req.urlQuery.state)

Example of email validation with $4DSID

A user account is created in a Users dataclass. A $info object is received with the email and password. An OTP corresponding to the current session is generated. An URL is then returned with this OTP given in the $4DSID parameter.

//cs.Users class

Function create($info : Object) : Text
	
var $user : cs.UsersEntity
var $status : Object
var $token : Text
	
$user:=This.new() //create a new user
$user.fromObject($info)
$status:=$user.save()
	
//Store information in the session
//including user creation status
Use (Session.storage)
	Session.storage.status:=New shared object("step"; "Waiting for validation email"; /
    "email"; $user.email; "ID"; $user.ID)
End use 
	
//Generate an OTP corresponding to the session
$token:=Session.createOTP()

// Return an URL with a $4DSID parameter
return "https://my.server.com/tools/validateEmail?$4DSID="+$token`

The user is sent this URL as a link in an email. The URL prefix /validateEmail is handled by a custom HTTP request handler:

[
  {
    "class": "RequestHandler",
    "method": "validateEmail",
    "regexPattern": "/validateEmail",
    "verbs": "get"
  }
]

The validateEmail() function of the RequestHandler singleton:

//validateEmail class

shared singleton Class constructor()

Function validateEmail() : 4D.OutgoingMessage
	
 var $result:=4D.OutgoingMessage.new()
    //The session which generated the OTP is retrieved 
    //thanks to the $4DSID parameter given in the URL
 If (Session.storage.status.step="Waiting for validation email")
	
  $user:=ds.Users.get(Session.storage.status.ID)
  $user.emailValidated() //set to true
		
  $result.setBody("Congratulations <br>"\
  +"Your email "+Session.storage.status.email+" has been validated")
		
  $result.setHeader("Content-Type"; "text/html"	
  Use (Session.storage.status)
	Session.storage.status.step:="Email validated"
  End use
 Else
  $result.setBody("Invalid token")

 End if 
	
 return $result

Since the $4DSID parameter contains a valid OTP corresponding to the original session, the Session object refers to the session that created the OTP.

A new user is created, and some information is stored in the session, especially the current step of the user account creation process (Waiting for validation email) and the user ID.

Supported contexts

Both HTTP and HTTPS schemas are supported.
Only scalable sessions can be reused with tokens.
Only sessions of the host database can be reused (sessions created in component web servers cannot be restored).
Tokens are not supported with client/server sessions or single-user sessions.

Lifespan

A session token has a lifespan, and the session itself has a lifespan. The session token lifespan can be set at the token creation. By default, the token lifespan is the same value as the .idleTimeout value.

A session is only restored by a token if both the session token lifespan and the session lifespan have not expired. In other cases (the session token has expired and/or the session itself has expired), a guest session is created when a web request with a session token is received.

note

For more information, please refer to the Connect Your Web Apps to Third-Party Systems blog post.

Usages​

Enabling web sessions​

Session implementation​

Storing and sharing session information​

Session lifetime​

Privileges​

Example​

Session Token (OTP)​

Overview​

Processing the OTP in the callback​

Using $4DSID in the URL​

Using a custom parameter​

Processing a invalid OTP​

Scenario with $4DSID​

Scenario with restore function​

Example of email validation with $4DSID​

Supported contexts​

Lifespan​

Usages

Enabling web sessions

Session implementation

Storing and sharing session information

Session lifetime

Privileges

Example

Session Token (OTP)

Overview

Processing the OTP in the callback

Using `$4DSID` in the URL

Using a custom parameter

Processing a invalid OTP

Scenario with $4DSID

Scenario with `restore` function

Example of email validation with $4DSID

Supported contexts

Lifespan