Sessions Web
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 option on the "Web/Options (I)" page of the Settings (permanent setting):
This option is selected by default in new projects. It can however be disabled by selecting the No sessions option, 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 option defined in the Settings dialog box for the Web Server object (it is not stored on disk).
The
WEB SET OPTION
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 option 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.
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.
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.
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. C'est la raison pour laquelle il est recommandé d'utiliser l'objet Session lorsque vous souhaitez conserver les informations relatives à la session.
Storing and sharing session 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
You can close a session from a Qodly form using the logout feature.
Privilèges
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).
Voici un exemple :
If (Session.hasPrivilege("WebAdmin"))
//Access is granted, do nothing
Else
//Display an authentication page
End if
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.
Exemple
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).
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
Dans un environnement de production, il est nécessaire d'utiliser une connexion HTTPS pour éviter la circulation d'informations non chiffrées sur le réseau.
- 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>
- 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