Session

Session objects are returned by the Session command. These objects provide the developer with an interface allowing to manage the current user session and execute actions such as store contextual data, share information between session processes, launch session-related preemptive processes, or (web only) manage privileges.

Session types​

The following types of sessions are supported by this class:

• Web user sessions: Web user sessions are available when scalable sessions are enabled in your project. They are used for Web and REST connections, and can be assigned privileges.
• Remote client user sessions: In client/server applications, remote users have their own sessions managed on the server.
• Stored procedures session: All stored procedures executed on the server share the same virtual user session.
• Standalone session: Local session object returned in single-user application (useful in development and test phases of client/server applications).

Summary​

To learn more​

Scalable sessions for advanced web applications (blog post)
Permissions: Inspect Session Privileges for Easy Debugging (blog post)

.clearPrivileges()​

.clearPrivileges() : Boolean

Description​

The .clearPrivileges() function removes all the privileges associated to the session (excluding promoted privileges) and returns True if the execution was successful.

Unless in "forceLogin" mode, the session automatically becomes a Guest session. In "forceLogin" mode, .clearPrivileges() does not transform the session to a Guest session, it only clears the session's privileges.

Example​

//Invalidate a web user session
var $isGuest : Boolean
var $isOK : Boolean

$isOK:=Session.clearPrivileges()
$isGuest:=Session.isGuest() //$isGuest is True

.createOTP()​

.createOTP ( { lifespan : Integer } ) : Text

Description​

The .createOTP() function creates a new OTP (One Time Passcode) for the session and returns its token UUID. This token is unique to the session in which it was generated.

For more information about the OTP tokens, please refer to this section.

By default, if the lifespan parameter is omitted, the token is created with the same lifespan as the .idleTimeOut of the session. You can set a custom timeout by passing a value in seconds in lifespan (the minimum value is 10 seconds, lifespan is reset to 10 if a smaller value is passed). If an expired token is used to restore a web user session, it is ignored.

The returned token can then be used in exchanges with third-party applications or websites to securely identify the session. For example, the session OTP token can be used with a payment application.

Example​

var $token : Text
$token := Session.createOTP( 60 ) //the token is valid for 1 mn

.demote()​

.demote( promoteId : Integer )

Description​

The .demote() function removes the promoted privilege whose id you passed in promoteId from the web process, if it was previously added by the .promote() function.

If no privilege with promoteId was promoted using .promote() in the web process, the function does nothing.

If several privileges have been added to the web process, the demote() function must be called for each one with the appropriate promoteId. Privileges are stacked in the order they have been added to the process, it is recommended to unstack privileges in a LIFO (Last In, First Out) order.

Example​

exposed Function search($search : Text) : Collection

	var $employees : Collection
	var $promoteId1; $promoteId2 : Integer

	$promoteId1:=Session.promote("admin")
	$promoteId2:=Session.promote("superAdmin")

	$search:="@"+$search+"@"

	$employees:=This.query("type = :1 and lastname = :2"; "Intern"; $search).toCollection()

	Session.demote($promoteId2)
	Session.demote($promoteId1)

	return $employees

See also​

.promote()

.expirationDate​

.expirationDate : Text

Description​

The .expirationDate property contains the expiration date and time of the session cookie. The value is expressed as text in the ISO 8601 format: YYYY-MM-DDTHH:MM:SS.mmmZ.

This property is read-only. It is automatically recomputed if the .idleTimeout property value is modified.

Example​

var $expiration : Text
$expiration:=Session.expirationDate //eg "2021-11-05T17:10:42Z"

.getPrivileges()​

.getPrivileges() : Collection

Description​

The .getPrivileges() function returns a collection of all the privilege names associated to the session.

With remote client, stored procedure and standalone sessions, this function returns a collection only containing "WebAdmin".

Example​

The following roles.json has been defined:

{
"privileges":[
{
"privilege":"simple",
"includes":[

]
},
{
"privilege":"medium",
"includes":[
"simple"
]
}
],
"roles":[
{
"role":"Medium",
"privileges":[
"medium"
]
}
],
"permissions":{
"allowed":[

]
}
}

The session role is assigned in an authentify() datastore function:

 //Datastore Class

exposed Function authentify($role : Text) : Text
	Session.clearPrivileges()
	Session.setPrivileges({roles: $role})

Assuming the authentify() function is called with the "Medium" role:

var $privileges : Collection
$privileges := Session.getPrivileges()
//$privileges: ["simple","medium"]

See also​

.setPrivileges()
Permissions – Inspect the privileges in the session for an easy debugging (blog post)

.hasPrivilege()​

.hasPrivilege( privilege : Text ) : Boolean

Description​

The .hasPrivilege() function returns True if the privilege is associated to the session, and False otherwise.

With remote client, stored procedure and standalone sessions, this function always returns True, whatever the privilege.

Example​

You want to check if the "WebAdmin" privilege is associated to the web user session:

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

End if

.id​

.id : Text

Description​

The .id property contains the unique identifier (UUID) of the user session. With 4D Server, this unique string is automatically assigned by the server for each session and allows you to identify its processes.

.idleTimeout​

.idleTimeout : Integer

Description​

The .idleTimeout property contains the inactivity session timeout (in minutes), after which the session is automatically closed by 4D.

If this property is not set, the default value is 60 (1h).

When this property is set, the .expirationDate property is updated accordingly.

The value cannot be less than 60: if a lower value is set, the timeout is raised up to 60.

This property is read write.

Example​

If (Session.isGuest())
		// A Guest session will close after 60 minutes of inactivity
	Session.idleTimeout:=60
Else
		// Other sessions will close after 120 minutes of inactivity
	Session.idleTimeout:=120
End if

.info​

.info : Object

Description​

The .info property describes the remote client or stored procedure session on the server, or the standalone session.

The .info object contains the following properties:

.isGuest()​

.isGuest() : Boolean

Description​

The .isGuest() function returns True if the session is a Guest session (i.e. it has no privileges).

Example​

In the On Web Connection database method:

If (Session.isGuest())
	//Do something for Guest user
End if

.promote()​

.promote( privilege : Text ) : Integer

Description​

The .promote() function adds the privilege defined in the privilege parameter to the current process during the execution of the calling function and returns the id of the promoted privilege.

Dynamically adding privileges is useful when access rights depend on the execution context, which cannot be fully defined in the "roles.json" file. This is particularly relevant when the same function can be executed by users with different access levels. The use of .promote() ensures that only the current process is granted the necessary privileges, without affecting others.

The function does nothing and returns 0 if:

• the privilege does not exist in the roles.json file,
• the privilege is already assigned to the current process (using .promote() or through a static promote action declared for the calling function in the roles.json file).

You can call the promote() function several times in the same process to add different privileges.

The returned id is incremented each time a privilege is dynamically added to the process.

To remove a privilege dynamically, call the demote() function with the appropriate id.

Example​

Several users connect to a single endpoint that serves different applications. A user from application #1 does not need the "super_admin" privilege because they don't create "VerySensitiveInfo". A user from application #2 needs "super_admin" privilege.

You can dynamically provide appropriate privileges in the CreateInfo function:

exposed Function createInfo($info1 : Text; $info2 : Text)

var $sensitive : cs.SensitiveInfoEntity
var $verySensitiveInfo : cs.VerySensitiveInfoEntity
var $status : Object
var $promoteId : Integer

$sensitive:=ds.SensitiveInfo.new()
$sensitive.info:=$info1
$status:=$sensitive.save()

If (Session.storage.role.name="userApp2")
	$promoteId:=Session.promote("super_admin")
	$verySensitiveInfo:=ds.VerySensitiveInfo.new()
	$verySensitiveInfo.info:=$info2
	$status:=$verySensitiveInfo.save()
	Session.demote($promoteId)
End if 

See also​

.demote()
hasPrivilege()

.restore()​

.restore ( token : Text ) : Boolean

Description​

The .restore() function replaces the current web user session with their original session corresponding to the token UUID. Session's storage and privileges are restored.

If the original user session has been correctly restored, the function returns true.

The function returns false 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, the current web user session is left untouched (no session is restored).

Example​

In a singleton called by a custom HTTP Request handler:

shared singleton Class constructor()

Function callback($request : 4D.IncomingMessage) : 4D.OutgoingMessage
 Session.restore($request.urlQuery.state) 

See also​

.createOTP()

.setPrivileges()​

.setPrivileges( privilege : Text ) : Boolean
.setPrivileges( privileges : Collection )
.setPrivileges( settings : Object ) : Boolean

Description​

The .setPrivileges() function associates the privilege(s) and/or role(s) defined in the parameter to the session and returns True if the execution was successful.

• In the privilege parameter, pass a string containing a privilege name (or several comma-separated privilege names).

• In the privileges parameter, pass a collection of strings containing privilege names.

• In the settings parameter, pass an object containing the following properties:

If the privileges or roles property contains a name that is not declared in the roles.json file, it is ignored.

By default when no privilege or role is associated to the session, the session is a Guest session.

The userName property is available at session object level (read-only).

Example​

In a custom authentication method, you set the "WebAdmin" privilege to the user:

var $userOK : Boolean

... //Authenticate the user

If ($userOK) //The user has been approved
 var $info : Object
 $info:=New object()
 $info.privileges:=New collection("WebAdmin")
 Session.setPrivileges($info)
End if

See also​

.getPrivileges()

.storage​

.storage : Object

Description​

The .storage property contains a shared object that can be used to store information available to all processes of the session.

When a Session object is created, the .storage property is empty. Since it is a shared object, this property will be available in the Storage object of the server.

Like the Storage object of the server, the .storage property is always "single": adding a shared object or a shared collection to .storage does not create a shared group.

This property is read only itself but it returns a read-write object.

Web session example​

You want to store the client IP in the .storage property. You can write in the On Web Authentication database method:

If (Session.storage.clientIP=Null) //first access
 Use (Session.storage)
 Session.storage.clientIP:=New shared object("value"; $clientIP)
 End use
End if

Remote session example​

You want to share data between processes in the same session:

Use (Session.storage)
 Session.storage.settings:=New shared object("property"; $value; "property2"; $value2)
End use

.userName​

.userName : Text

Description​

The .userName property contains the user name associated to the session. You can use it to identify the user within your code.

• With web sessions, this property is an empty string by default. It can be set using the privileges property of the setPrivileges() function.
• With remote and stored procedure sessions, this property returns the same user name as the Current user command.
• With standalone sessions, this property contains "designer" or the name set with the SET USER ALIAS command.

This property is read only.