Version : 21 BETA

Session

Les objets session sont retournés par la commande Session. Ces objets fournissent au développeur une interface permettant de gérer la session en cours et d'exécuter des actions telles que le stockage de données contextuelles, le partage d'informations entre les process de session, le lancement de process préemptifs liés à la session ou (contexte web uniquement) la gestion des privilèges.

Articles de blog sur le sujet

Types de sessions

Les types de sessions suivants sont pris en charge par cette classe :

Sessions utilisateur Web : Les sessions utilisateur Web sont disponibles lorsque les sessions évolutives (scalable sessions) sont activées dans votre projet. Elles sont utilisées pour les connexions Web (y compris les accès REST) et sont contrôlées par les privilèges qui leur sont attribués.
Sessions desktop, qui comprennent :
- Sessions utilisateurs distants : Dans les applications client/serveur, les utilisateurs distants ont leurs propres sessions gérées sur le serveur.
- Sessions procédures stockées : Session utilisateur virtuelle pour toutes les procédures stockées exécutées sur le serveur.
- Sessions autonomes: Session locale retournée dans une application mono-utilisateur (utile dans les phases de développement et de test des applications client/serveur).

A propos des privilèges de session

Tous les types de sessions peuvent gérer les privilèges, mais seul le code exécuté dans les sessions web utilisateurs est en fait contrôlé par les privilèges de la session.

Sommaire


.clearPrivileges() : Boolean supprime tous les privilèges associés à la session (à l'exception des privilèges promus) et renvoie True si l'exécution a réussi
.createOTP ( { lifespan : Integer } ) : Text crée un nouvel OTP (One Time Passcode) pour la session et renvoie son UUID de token
.demote( promoteId : Integer ) supprime du process web le privilège promu dont l'identifiant a été passé dans promoteId, s'il a été précédemment ajouté par la fonction `.promote()`
.expirationDate : Text la date et l'heure d'expiration du cookie de session
.getPrivileges() : Collection renvoie une collection contenant tous les noms de privilèges associés à la session
.hasPrivilege( privilege : Text ) : Boolean renvoie True si le privilege est associé à la session, et False sinon
.id : Text l'identifiant unique (UUID) de la session utilisateur
.idleTimeout : Integer le délai maximal d'inactivité de session (en minutes), au-delà duquel la session est automatiquement fermée par 4D
.info : Object décrit la session desktop ou la session web
.isGuest() : Boolean retourne True tant que `setPrivileges()` n'est pas appelé dans la session ou après qu'un Qodly logout a été exécuté dans la session
.promote( privilege : Text ) : Integer ajoute le privilège défini dans le paramètre privilege au process courant durant l'exécution de la fonction appelante et renvoie l'identifiant du privilège promu
.restore ( token : Text ) : Boolean remplace la session courante de l'utilisateur Web par sa session originale correspondant à l'UUID token
.setPrivileges( privilege : Text ) : Boolean .setPrivileges( privileges : Collection ) .setPrivileges( settings : Object ) : Boolean associe le ou les privilège(s) et/ou rôle(s) défini(s) en paramètre à la session et renvoie True si l'exécution a réussi
.storage : Object un objet partagé qui peut être utilisé pour stocker des informations disponibles pour tous les process de la session
.userName : Text le nom d'utilisateur associé à la session

.clearPrivileges()

Historique

Release	Modifications
21	Prise en charge des sessions distantes et autonomes
18 R6	Ajout

.clearPrivileges() : Boolean

Paramètres	Type		Description
Résultat	Boolean	<-	True si l'exécution est réussie

Description

La fonction .clearPrivileges() supprime tous les privilèges associés à la session (à l'exception des privilèges promus) et renvoie True si l'exécution a réussi.

note

Cette fonction ne supprime pas les privilèges promus du process web, qu'ils aient été ajoutés par le biais du fichier roles.json ou de la fonction promote().

note

Gardez à l'esprit que les privilèges ne s'appliquent qu'au code exécuté via les accès web, quel que soit le type de session sur lequel cette fonction est exécutée.

Exemple

//Invalider la session d'un utilisateur web
var $isGuest : Boolean
var $isOK : Boolean

$isOK:=Session.clearPrivileges()

.createOTP()

Historique

Release	Modifications
21	Prise en charge des sessions distantes et autonomes
20 R9	Ajout

.createOTP ( { lifespan : Integer } ) : Text

Paramètres	Type		Description
lifespan	Integer	->	Durée de vie du token de session en secondes (sessions web uniquement)
Résultat	Text	<-	UUID du token OTP

Description

La fonction .createOTP() crée un nouvel OTP (One Time Passcode) pour la session et renvoie son UUID de token. Ce token est propre à la session au cours de laquelle il a été généré.

Pour plus d'informations sur les tokens OTP, veuillez consulter cette section.

Si un token expiré est utilisé pour restaurer la session, il est ignoré.

Pour les sessions web, vous pouvez définir un délai personnalisé en passant une valeur en secondes dans lifespan. Par défaut, si le paramètre lifespan est omis, le token est créé avec la même durée de vie que le .idleTimeOut de la session.

Pour les sessions desktop, le token est créé avec une durée de vie de 10 secondes.

Le token retourné peut être utilisé lors d'échanges avec des applications tierces ou des sites Web pour identifier la session de manière sécurisée. Par exemple, le token OTP de session peut être utilisé avec une application de paiement.

Le token renvoyé peut être utilisé par le serveur 4D ou l'application mono-utilisateur 4D pour identifier les requêtes provenant du web qui partagent la session.

Exemple

var $token : Text
$token := Session.createOTP( 60 ) //le token est valable pendant 1 mn

.demote()

Historique

Release	Modifications
20 R10	Ajout

.demote( promoteId : Integer )

Paramètres	Type		Description
promoteId	Integer	->	Id retourné par la fonction `promote()`

Description

La fonction .demote() supprime du process web le privilège promu dont l'identifiant a été passé dans promoteId, s'il a été précédemment ajouté par la fonction .promote().

Si aucun privilège avec promoteId n'a été promu à l'aide de .promote() dans le process web, la fonction ne fait rien.

Si plusieurs privilèges ont été ajoutés au process web, la fonction demote() doit être appelée pour chacun d'entre eux avec le promoteId approprié. Les privilèges sont empilés dans l'ordre dans lequel ils ont été ajoutés au process, il est recommandé de dépiler les privilèges dans l'ordre LIFO (Last In, First Out).

Exemple

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

Voir également

.promote()

.expirationDate

Historique

Release	Modifications
18 R6	Ajout

.expirationDate : Text

Description

note

Cette propriété est uniquement disponible avec les sessions web.

La propriété .expirationDate contient la date et l'heure d'expiration du cookie de session. La valeur est exprimée sous forme de texte au format ISO 8601 : YYYY-MM-DDTHH:MM:SS.mmmZ.

Cette propriété est en lecture seule. Elle est automatiquement recalculée si la valeur de la propriété .idleTimeout est modifiée.

Exemple

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

.getPrivileges()

Historique

Release	Modifications
21	Prise en charge des sessions distantes et autonomes
20 R6	Ajout

.getPrivileges() : Collection

Paramètres	Type		Description
Résultat	Collection	<-	Collection de noms de privilèges (chaînes)

Description

La fonction .getPrivileges() renvoie une collection contenant tous les noms de privilèges associés à la session.

note

Cette fonction renvoie les privilèges attribués à une session en utilisant la fonction setPrivileges() uniquement. Les privilèges promus ne sont PAS renvoyés par la fonction, qu'ils aient été ajoutés via le fichier roles.json ou la fonction promote().

note

Gardez à l'esprit que les privilèges ne s'appliquent qu'au code exécuté via les accès web, quel que soit le type de session sur lequel cette fonction est exécutée.

Exemple

Les rôles suivants roles.json ont été définis :

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

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

      ]
   }
}

Le rôle de la session est attribué dans une fonction de datastore authentify() :

  //Datastore Class

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

En supposant que la fonction authentify() soit appelée avec le rôle "Medium" :

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

Voir également

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

.hasPrivilege()

Historique

Release	Modifications
21	Retourne True pour les privilèges promus, Prise en charge des sessions distantes et autonomes
18 R6	Ajout

.hasPrivilege( privilege : Text ) : Boolean

Paramètres	Type		Description
privilege	Text	->	Nom du privilège à vérifier
Résultat	Boolean	<-	Vrai si la session dispose du privilege, sinon Faux

Description

La fonction .hasPrivilege() renvoie True si le privilege est associé à la session, et False sinon.

note

Cette fonction renvoie True pour le privilège si elle est appelée depuis une fonction qui a été promue pour ce privilège (soit via le fichier roles.json, soit via la fonction promote()).

note

Gardez à l'esprit que les privilèges ne s'appliquent qu'au code exécuté via les accès web, quel que soit le type de session sur lequel cette fonction est exécutée.

Exemple

Vous voulez vérifier si le privilège "CreateInvoices" est associé à la session de l'utilisateur web :

If (Session.hasPrivilege("CreateInvoices"))
	//Accès à la fonctionnalité de création de facture
Else
	//Pas d'accès à la fonctionnalité 

End if

Voir également

Restreindre les données en fonction des privilèges ou des informations enregistrées dans la mémoire de session (article de blog)

.id

Historique

Release	Modifications
20 R5	Ajout

.id : Text

Description

La propriété .id contient l'identifiant unique (UUID) de la session utilisateur. Avec 4D Server, cette chaîne unique est automatiquement assignée par le serveur à chaque session et vous permet d'identifier ses process.

tip

Vous pouvez utiliser cette propriété pour obtenir l'objet .storage d'une session grâce à la commande Session storage .

.idleTimeout

Historique

Release	Modifications
18 R6	Ajout

.idleTimeout : Integer

Description

note

Cette propriété est uniquement disponible avec les sessions web.

La propriété .idleTimeout contient le délai maximal d'inactivité de session (en minutes), au-delà duquel la session est automatiquement fermée par 4D.

Si cette propriété n'est pas définie, sa valeur par défaut est 60 (1h).

Lorsque cette propriété est définie, la propriété .expirationDate est mise à jour en conséquence.

La valeur ne peut pas être < 60 ; si une valeur inférieure est définie, le timeout est élevé à 60.

Cette propriété est en lecture-écriture.

Exemple

If (Session.isGuest())
		// La session Guest se ferme après 60 minutes d'inactivité
	Session.idleTimeout:=60
Else
		// Les autres sessions se ferment après 120 minutes d'inactivité
	Session.idleTimeout:=120
End if

.info

Historique

Release	Modifications
20 R5	Ajout

.info : Object

Description

La propriété .info décrit la session desktop ou la session web.

Sessions distantes et Sessions de procédure stockée : L'objet .info est le même que celui renvoyé dans la propriété "session" par la commande Process activity.
Sessions autonomes : L'objet .info est le même que celui retourné par la commande Session info.

L'objet .info contient les propriétés suivantes:

Propriété	Type	Description
type	Text	Type de session : "remote", "storedProcedure", "standalone", "rest", "web"
userName	Text	Nom d'utilisateur 4D (même valeur que `.userName`)
machineName	Text	Sessions distantes : nom de la machine distante. Session procédures stockées : nom de la machine serveur. Session autonome : nom de la machine
systemUserName	Text	Sessions distantes : nom de la session système ouverte sur la machine distante.
IPAddress	Text	Adresse IP de la machine distante
hostType	Text	Type d'hôte : "windows" ou "mac"
creationDateTime	Date ISO 8601	Date et heure de création de la session. Session autonome : date et heure de démarrage de l'application
state	Text	État de la session : "active", "postponed", "sleeping"
ID	Text	UUID de session (même valeur que `.id`)
persistentID	Text	Sessions distantes : ID persistant de la session

note

.info étant une propriété calculée, il est recommandé de l'appeler une fois et de la stocker dans une variable locale si vous souhaitez effectuer un traitement sur ses propriétés.

.isGuest()

Historique

Release	Modifications
18 R6	Ajout

.isGuest() : Boolean

Paramètres	Type		Description
Résultat	Boolean	<-	True si la session est une session Guest, False sinon (sessions web uniquement)

Description

note

Cette fonction renvoie toujours False pour les sessions desktop.

La fonction .isGuest() retourne True tant que setPrivileges() n'est pas appelé dans la session ou après qu'un Qodly logout a été exécuté dans la session.

Compatibilité

Dans une session REST lorsque le mode Force login n'est pas activé, .isGuest() renvoie True si la session n'a pas de privilèges.

Exemple

Dans la méthode base On Web Connection :

If (Session.isGuest())
 //Faire quelque chose pour l'utilisateur invité
End if

.promote()

Historique

Release	Modifications
20 R10	Ajout

.promote( privilege : Text ) : Integer

Paramètres	Type		Description
privilege	Text	->	Nom de privilège
Résultat	Integer	<-	id à utiliser pour l'appel de la fonction `demote()`

Description

La fonction .promote() ajoute le privilège défini dans le paramètre privilege au process courant durant l'exécution de la fonction appelante et renvoie l'identifiant du privilège promu.

L'ajout dynamique de privilèges est utile lorsque les droits d'accès dépendent du contexte d'exécution, qui ne peut pas être entièrement défini dans le fichier "roles.json". Ceci est particulièrement le cas lorsque la même fonction peut être exécutée par des utilisateurs ayant des niveaux d'accès différents. L'utilisation de .promote() permet de s'assurer que seul le process en cours bénéficie des privilèges nécessaires, sans affecter les autres.

La fonction ne fait rien et renvoie 0 si :

le privilege n'existe pas dans le fichier roles.json,
le privilege est déjà assigné au process courant (en utilisant .promote() ou à travers une action de promotion statique déclarée pour la fonction appelante dans le fichier roles.json).

Vous pouvez appeler la fonction promote() plusieurs fois dans le même process pour ajouter différents privilèges.

L'identifiant renvoyé est incrémenté chaque fois qu'un privilège est ajouté dynamiquement au process.

Pour supprimer un privilège de manière dynamique, appelez la fonction demote() avec l'identifiant du privilège.

note

Gardez à l'esprit que les privilèges ne s'appliquent qu'au code exécuté via les accès web, quel que soit le type de session sur lequel cette fonction est exécutée.

Exemple

Plusieurs utilisateurs se connectent à un seul point d'accès qui sert différentes applications. Un utilisateur de l'application n°1 n'a pas besoin du privilège "super_admin" car il ne crée pas de "VerySensitiveInfo". Un utilisateur de l'application n° 2 a besoin du privilège "super_admin".

Vous pouvez allouer dynamiquement les privilèges appropriés dans la fonction CreateInfo :

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 

Voir également

.demote()
hasPrivilege()

.restore()

Historique

Release	Modifications
20 R9	Ajout

.restore ( token : Text ) : Boolean

Paramètres	Type		Description
token	Text	->	UUID du token de session
Résultat	Boolean	<-	True si la session courante a été remplacée avec succès par la session du token

Description

La fonction .restore() remplace la session courante de l'utilisateur Web par sa session originale correspondant à l'UUID token. Le storage et les privilèges de la session sont restaurés.

Si la session originale de l'utilisateur a été correctement restaurée, la fonction renvoie true.

La fonction renvoie false si :

le token de session a déjà été utilisé,
le token de session a expiré,
le token de session n'existe pas,
la session d'origine elle-même a expiré.

Dans ce cas, la session courante de l'utilisateur web est laissée intacte (aucune session n'est restaurée).

Exemple

Dans un singleton appelé par un HTTP request handler personnalisé :

shared singleton Class constructor()

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

Voir également

.createOTP()

.setPrivileges()

Historique

Release	Modifications
21	Prise en charge des sessions distantes et autonomes
19 R8	Prise en charge de la propriété "roles" dans settings
18 R6	Ajout

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

Paramètres	Type		Description
privilege	Text	->	Nom de privilège
privileges	Collection	->	Collection de noms de privilèges
settings	Object	->	Objet contenant une propriété "privileges" (texte ou collection)
Résultat	Boolean	<-	True si l'exécution est réussie

Description

La fonction .setPrivileges() associe le ou les privilège(s) et/ou rôle(s) défini(s) en paramètre à la session et renvoie True si l'exécution a réussi.

Dans le paramètre privilege, passez une chaîne contenant un nom de privilège (ou plusieurs noms de privilèges séparés par des virgules).
Dans le paramètre privileges, passez une collection de chaînes contenant des noms de privilèges.
Dans le paramètre settings, passez un objet contenant les propriétés suivantes :

Propriété	Type	Description
privileges	Text ou Collection	Chaîne contenant un nom de privilège, ou Collection de chaînes contenant des noms de privilèges
roles	Text ou Collection	Chaîne contenant un rôle, ou Collection de chaînes contenant des rôles
userName	Text	Nom d'utilisateur à associer à la session (facultatif, uniquement pour les sessions web). Non disponible dans les sessions de clients distants (ignoré).

note

Les privilèges et les rôles sont définis dans le fichier roles.json du projet. Pour plus d'informations, veuillez vous reporter à la section Privileges.

Si la propriété privileges ou roles contient un nom qui n'est pas déclaré dans le fichier roles.json, il est ignoré.

Par défaut lorsqu'aucun privilège ou rôle n'est associé à la session, la session est une session Guest.

La propriété userName est accessible au niveau de l'objet session (lecture seulement).

note

Gardez à l'esprit que les privilèges ne s'appliquent qu'au code exécuté via les accès web, quel que soit le type de session sur lequel cette fonction est exécutée.

Exemple

Dans une méthode d'authentification personnalisée, vous assignez le privilège "WebAdmin" à l'utilisateur :

var $userOK : Boolean

... //Authentifier l'utilisateur

If ($userOK) //L'utilisateur a été approuvé
  var $info : Object
  $info:=New object()
  $info.privileges:=New collection("WebAdmin")
  Session.setPrivileges($info)
End if

Voir également

.getPrivileges()

.storage

Historique

Release	Modifications
20 R5	Prise en charge des sessions desktop
18 R6	Ajout

.storage : Object

Description

La propriété .storage contient un objet partagé qui peut être utilisé pour stocker des informations disponibles pour tous les process de la session.

Lorsqu'un objet Session est créé, la propriété .storage est vide. Puisqu'il s'agit d'un objet partagé, cette propriété sera disponible dans l'objet Storage du serveur.

Tout comme l'objet Storage du serveur, la propriété .storage est toujours "single" : l'ajout d'un objet partagé ou d'une collection partagée à .storage ne crée pas de groupe partagé.

Cette propriété est elle-même en lecture seulement mais elle retourne un objet en lecture-écriture.

tip

Vous pouvez obtenir la propriété .storage d'une session en utilisant la commande Session storage.

Lorsqu'une session desktop et une session web sont partagées à l'aide d'un OTP, elles partagent également le même objet .storage.

Exemple de session Web

Vous voulez stocker l'adresse IP du client dans la propriété .storage. Vous pouvez écrire dans la méthode base On Web Authentication :

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

Exemple de session distante

Vous voulez partager des données entre les process de la même session :

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

.userName

Historique

Release	Modifications
20 R5	Prise en charge des sessions desktop
18 R6	Ajout

.userName : Text

Description

La propriété .userName contient le nom d'utilisateur associé à la session. Vous pouvez vous en servir pour identifier l'utilisateur dans votre code.

Sessions web : Cette propriété est une chaîne vide par défaut. Elle peut être définie via la propriété privileges de la fonction setPrivileges().
Sessions de procédure stockée/distantes : Cette propriété retourne le même nom d'utilisateur que la commande Current user.
Sessions autonomes : Cette propriété contient "designer" ou le nom défini avec la commande SET USER ALIAS.

Cette propriété est en lecture seule pour les sessions desktop.

Types de sessions​

Sommaire​

.clearPrivileges()​

Description​

Exemple​

.createOTP()​

Description​

Exemple​

.demote()​

Description​

Exemple​

Voir également​

.expirationDate​

Description​

Exemple​

.getPrivileges()​

Description​

Exemple​

Voir également​

.hasPrivilege()​

Description​

Exemple​

Voir également​

.id​

Description​

.idleTimeout​

Description​

Exemple​

.info​

Description​

.isGuest()​

Description​

Exemple​

.promote()​

Description​

Exemple​

Voir également​

.restore()​

Description​

Exemple​

Voir également​

.setPrivileges()​

Description​

Exemple​

Voir également​

.storage​

Description​

Exemple de session Web​

Exemple de session distante​

.userName​

Description​

Types de sessions

Sommaire

.clearPrivileges()

Description

Exemple

.createOTP()

Description

Exemple

.demote()

Description

Exemple

Voir également

.expirationDate

Description

Exemple

.getPrivileges()

Description

Exemple

Voir également

.hasPrivilege()

Description

Exemple

Voir également

.id

Description

.idleTimeout

Description

Exemple

.info

Description

.isGuest()

Description

Exemple

.promote()

Description

Exemple

Voir également

.restore()

Description

Exemple

Voir également

.setPrivileges()

Description

Exemple

Voir également

.storage

Description

Exemple de session Web

Exemple de session distante

.userName

Description