Session
Os objetos de sessão são retornados pelo comando Session
. Esses objetos fornecem ao desenvolvedor uma interface que permite gerenciar a sessão atual do usuário e executar ações como armazenar dados contextuais, compartilhar informações entre processos de sessão, iniciar processos preemptivos relacionados à sessão ou (somente na Web) gerenciar privilégios.
Blog posts about this feature:
Tipos de sessão
Os seguintes tipos de sessões são suportados por essa classe:
- Sessões de usuário web: sessões de usuário web estão disponíveis quando sessões escaláveis estão habilitadas em seu projeto. Eles são usados para conexões Web e REST e podem receber privilégios.
- Sessões de usuário cliente remoto: em aplicações cliente/servidor, os usuários remotos têm suas próprias sessões gerenciadas no servidor.
- Sessão de procedimentos armazenados: Todos os procedimentos armazenados executados no servidor compartilham a mesma sessão de usuário virtual.
- Standalone session: Objeto de sessão local retornado em aplicativo de usuário único (útil nas fases de desenvolvimento e teste de aplicativos cliente/servidor).
A disponibilidade de propriedades e funções no objeto Session
depende do tipo de sessão.
Resumo
.clearPrivileges() : Boolean removes all the privileges associated to the session (excluding promoted privileges) and returns True if the execution was successful |
.createOTP ( { lifespan : Integer } ) : Text cria um novo OTP (uma senha única) para a sessão e retorna seu UUID |
.demote( promoteId : Integer ) removes the promoted privilege whose id you passed in promoteId from the web process, if it was previously added by the .promote() function |
.expirationDate : Text a data e a hora de expiração do cookie de sessão |
.getPrivileges() : Collection retorna uma coleção de todos os nomes de privilégios associados à sessão |
.hasPrivilege( privilege : Text ) : Boolean retorna True se o privilege estiver associado à sessão e False caso contrário |
.id : Text o identificador único (UUID) da sessão do usuário |
.idleTimeout : Integer o tempo limite da sessão de inatividade (em minutos), após o qual a sessão é automaticamente encerrada pelo 4D |
.info : Object descreve o cliente remoto ou a sessão do procedimento armazenado no servidor, ou a sessão autônoma |
.isGuest() : Boolean retorna True se a sessão for uma sessão Guest (ou seja, não tem privilégios) |
.promote( privilege : Text ) : Integer 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 |
.restore ( token : Text ) : Boolean substitui a sessão do usuário da web pela sua sessão original correspondente ao token UUID |
.setPrivileges( privilege : Text ) : Boolean .setPrivileges( privileges : Collection ) .setPrivileges( settings : Object ) : Boolean associa os privilégios e/ou papéis definidos no parâmetro para a sessão e retorna True se a execução foi bem sucedida |
.storage : Object um objeto compartilhado que pode ser usado para armazenar informações disponíveis para todos os processos da sessão |
.userName : Text o nome de usuário associado à sessão |
To learn more
Scalable sessions for advanced web applications (blog post)
Permissions: Inspect Session Privileges for Easy Debugging (blog post)
.clearPrivileges()
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.clearPrivileges() : Boolean
Parâmetro | Tipo | Descrição | |
---|---|---|---|
Resultados | Parâmetros | <- | True se a execução for bem-sucedida |
Descrição
Esta função não faz nada e sempre retorna Verdadeiro com cliente remoto, procedimento armazenado e sessões autônomas.
The .clearPrivileges()
function removes all the privileges associated to the session (excluding promoted privileges) and returns True if the execution was successful.
A menos que esteja no modo "forceLogin", a sessão se torna automaticamente uma sessão de convidado. No modo "forceLogin", .clearPrivileges()
não transforma a sessão em uma sessão Guest, apenas limpa os privilégios da sessão.
This function does not remove promoted privileges from the web process, whether they are added through the roles.json file or the promote()
function.
Exemplo
//Invalidar uma sessão de usuário da web
var $isGuest : Boolean
var $isOK : Boolean
$isOK:=Session.clearPrivileges()
$isGuest:=Session.isGuest() //$isGuest é True
.createOTP()
História
Release | Mudanças |
---|---|
20 R9 | Adicionado |
.createOTP ( { lifespan : Integer } ) : Text
Parâmetro | Tipo | Descrição | |
---|---|---|---|
lifespan | Integer | -> | Duração do token de sessão em segundos |
Resultados | Text | <- | UUID da sessão |
Descrição
Essa função só está disponível com sessões de usuário Web. Ele retorna uma string vazia em outros contextos.
A função .createOTP()
cria um novo OTP (uma senha única) para a sessão e retorna seu UUID. Esse token é exclusivo da sessão em que foi gerado.
Para mais informações sobre os tokens OTP, consulte esta seção.
Por padrão, se o parâmetro lifespan for omitido, o token será criado com o mesmo tempo de vida que o .idleTimeOut
da sessão. Você pode definir um tempo limite personalizado passando um valor em segundos em lifespan (o valor mínimo é 10 segundos, lifespan é redefinido para 10 se um valor menor for passado). Se um token expirado for usado para restaurar uma sessão de usuário Web, ele será ignorado.
O token retornado pode então ser usado em trocas com aplicativos ou sites de terceiros para identificar a sessão com segurança. Por exemplo, o token de sessão OTP pode ser usado com um aplicativo de pagamento.
Exemplo
var $token : Text
$token := Session.createOTP( 60 ) //o token é válido por 1 mn
.demote()
História
Release | Mudanças |
---|---|
20 R10 | Adicionado |
.demote( promoteId : Integer )
Parâmetro | Tipo | Descrição | |
---|---|---|---|
promoteId | Integer | -> | Id returned by the promote() function |
Descrição
This function does nothing in remote client, stored procedure, and standalone sessions.
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.
Exemplo
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
Veja também
.expirationDate
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.expirationDate : Text
Descrição
Essa propriedade só está disponível com sessões de usuário da Web.
A propriedade .expirationDate
contém a data e a hora de expiração do cookie de sessão. O valor é expresso como texto no formato ISO 8601: YYYY-MM-DDTHH:MM:SS.mmmZ
.
Essa propriedade é somente leitura. Ele será automaticamente recalculado se o valor da propriedade .idleTimeout
for modificado.
Exemplo
var $expiration : Text
$expiration:=Session.expirationDate //por exemplo "2021-11-05T17:10:42Z"
.getPrivileges()
História
Release | Mudanças |
---|---|
20 R6 | Adicionado |
.getPrivileges() : Collection
Parâmetro | Tipo | Descrição | |
---|---|---|---|
Resultados | Collection | <- | Coleção de nomes de privilégios (strings) |
Descrição
A função .getPrivileges()
retorna uma coleção de todos os nomes de privilégios associados à sessão.
This function returns privileges assigned to a Session using the setPrivileges()
function only. Promoted privileges are NOT returned by the function, whether they are added through the roles.json file or the promote()
function.
Com cliente remoto, procedimento armazenado e sessões autônomas, essa função retorna uma coleção que contém apenas "WebAdmin".
Exemplo
O seguinte arquivo roles.json
foi definido:
{
"privileges":[
{
"privilege":"simple",
"includes":[
]
},
{
"privilege":"medium",
"includes":[
"simple"
]
}
],
"roles":[
{
"role":"Medium",
"privileges":[
"medium"
]
}
],
"permissions":{
"allowed":[
]
}
}
O papel de sessão é atribuído em uma função de datastore authentify()
:
//Datastore Class
exposed Function authentify($role : Text) : Text
Session.clearPrivileges()
Session.setPrivileges({roles: $role})
Assumindo que a função authentify()
seja chamada com o papel "Medium":
var $privileges : Collection
$privileges := Session.getPrivileges()
//$privileges: ["simple","medium"]
Veja também
.setPrivileges()
Permissions – Inspect the privileges in the session for an easy debugging (blog post)
.hasPrivilege()
História
Release | Mudanças |
---|---|
21 | Returns True for promoted privileges |
18 R6 | Adicionado |
.hasPrivilege( privilege : Text ) : Boolean
Parâmetro | Tipo | Descrição | |
---|---|---|---|
privilege | Text | -> | Nome do privilegio a verificar |
Resultados | Parâmetros | <- | True se a sessão tiver privilege, False caso contrário |
Descrição
A função .hasPrivilege()
retorna True se o privilege estiver associado à sessão e False caso contrário.
This function returns True for the privilege if called from a function that was promoted for this privilege (either through the roles.json file or the promote()
function).
Com cliente remoto, procedimento armazenado e sessões autônomas, essa função sempre retorna True, independentemente do privilégio.
Exemplo
Você deseja verificar se o privilégio "WebAdmin" está associado à sessão do usuário da Web:
If (Session.hasPrivilege("WebAdmin"))
//Acesso é concedido, não faça nada
Else
//Exibe uma página de autenticação
End if
Veja também
.id
História
Release | Mudanças |
---|---|
20 R5 | Adicionado |
.id : Text
Descrição
A propriedade .id
contém o identificador único (UUID) da sessão do usuário. Com o 4D Server, essa string exclusiva é atribuída automaticamente pelo servidor para cada sessão e permite que você identifique seus processos.
.idleTimeout
História
Release | Mudanças |
---|
|v18 R6|Adicionado|
.idleTimeout : Integer
Descrição
Essa propriedade só está disponível com sessões de usuário da Web.
A propriedade .idleTimeout
contém o tempo limite da sessão de inatividade (em minutos), após o qual a sessão é automaticamente encerrada pelo 4D.
Se não se definir esta propriedade, o valor padrão é 60 (1h).
Quando essa propriedade é definida, a propriedade .expirationDate
é atualizada de acordo.
O valor não pode ser inferior a 60: se definir um valor inferior, o tempo de espera se eleva até 60.
Essa propriedade é leitura escrita.
Exemplo
If (Session.isGuest())
// Uma sessão de convidado será fechada após 60 minutos de inatividade
Session.idleTimeout:=60
Else
// Outras sessões serão fechadas após 120 minutos de inatividade
Session.idleTimeout:=120
End if
.info
História
Release | Mudanças |
---|---|
20 R5 | Adicionado |
.info : Object
Descrição
Essa propriedade só está disponível com cliente remoto, procedimento armazenado e sessões autônomas.
A propriedade .info
descreve o cliente remoto ou a sessão do procedimento armazenado no servidor, ou a sessão autônoma.
- O objeto
.info
é o mesmo objeto retornado na propriedade "session" pelo comandoProcess activity
para sessões de procedimento armazenado e cliente remoto. - O objeto
.info
é o mesmo objeto retornado pelo comandoSession info
para uma sessão autônoma.
O objeto .info
contém as seguintes propriedades:
Propriedade | Tipo | Descrição |
---|---|---|
type | Text | Tipo de sessão: "remote", "storedProcedure", "standalone" |
userName | Text | Nome de usuário 4D (o mesmo valor que .userName ) |
machineName | Text | Sessões remotas: nome da máquina remota. Sessão de procedimentos armazenados: nome da máquina do servidor. Sessão autônoma: nome da máquina |
systemUserName | Text | Sessões remotas: nome da sessão do sistema aberta na máquina remota. |
IPAddress | Text | Endereço IP da máquina remota |
hostType | Text | Tipo de host: "windows" ou "mac" |
creationDateTime | Date ISO 8601 | Data e hora de criação da sessão. Sessão autônoma: data e hora da inicialização do aplicativo |
state | Text | Estado da sessão: "ativa", "adiada", "em espera" |
ID | Text | UUID da sessão (mesmo valor que .id ) |
persistentID | Text | Sessões remotas: ID persistente da sessão |
Desde . nfo
é uma propriedade computada, é recomendável chamá-lo uma vez e então armazená-lo em uma variável local se você quiser fazer algum processamento em suas propriedades.
.isGuest()
História
Release | Mudanças |
---|---|
18 R6 | Adicionado |
.isGuest() : Boolean
Parâmetro | Tipo | Descrição | |
---|---|---|---|
Resultados | Parâmetros | <- | True se a sessão for uma sessão Guest, False caso contrário |
Descrição
Essa função sempre retorna False com cliente remoto, procedimento armazenado e sessões autônomas.
A função .isGuest()
retorna True se a sessão for uma sessão Guest (ou seja, não tem privilégios).
Exemplo
No método base On Web Connection
:
If (Session.isGuest())
//Fazer algo para o usuário convidado
End if
.promote()
História
Release | Mudanças |
---|---|
20 R10 | Adicionado |
.promote( privilege : Text ) : Integer
Parâmetro | Tipo | Descrição | |
---|---|---|---|
privilege | Text | -> | Nome do privilégio |
Resultados | Integer | <- | id to use when calling the demote() function |
Descrição
This function does nothing in remote client, stored procedure, and standalone sessions.
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 theroles.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.
Exemplo
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
Veja também
.restore()
História
Release | Mudanças |
---|---|
20 R9 | Adicionado |
.restore ( token : Text ) : Boolean
Parâmetro | Tipo | Descrição | |
---|---|---|---|
token | Text | -> | UUID do token de sessão |
Resultados | Parâmetros | <- | True se a sessão atual tiver sido substituída com êxito pela sessão no token |
Descrição
Essa função só está disponível com sessões de usuário Web. Ele retorna False em outros contextos.
A função .restore()
substitui a sessão do usuário da web pela sua sessão original correspondente ao token UUID. O armazenamento e os privilégios da sessão são restaurados.
Se a sessão original do usuário tiver sido restaurada corretamente, a função retornará true
.
A função retorna false
se:
- o token de sessão já foi usado,
- o token de sessão expirou,
- o token de sessão não existe,
- a própria sessão original expirou.
Nesse caso, a sessão atual do usuário da Web não é alterada (nenhuma sessão é restaurada).
Exemplo
Em um singleton chamado por um manipulador de solicitação HTTP personalizado:
shared singleton Class constructor()
Function callback($request : 4D.IncomingMessage) : 4D.OutgoingMessage
Session.restore($request.urlQuery.state)
Veja também
.setPrivileges()
História
Release | Mudanças |
---|---|
19 R8 | Suporte da propriedade "roles" das Settings |
18 R6 | Adicionado |
.setPrivileges( privilege : Text ) : Boolean
.setPrivileges( privileges : Collection )
.setPrivileges( settings : Object ) : Boolean
Parâmetro | Tipo | Descrição | |
---|---|---|---|
privilege | Text | -> | Nome do privilégio |
privileges | Collection | -> | Collection de nomes de privilégios |
settings | Object | -> | Objetos com as propriedades "privilégios" (string ou collection) |
Resultados | Parâmetros | <- | True se a execução for bem-sucedida |
Descrição
Essa função não faz nada e sempre retorna False com cliente remoto, procedimento armazenado e sessões autônomas.
A função .setPrivileges()
associa os privilégios e/ou papéis definidos no parâmetro para a sessão e retorna True se a execução foi bem sucedida .
-
No parâmetro privilege, passe uma cadeia de caracteres contendo um nome de privilégio (ou vários nomes de privilégio separados por vírgula).
-
No parâmetro privileges, passe uma coleção de cadeias de caracteres contendo nomes de privilégios.
-
No parâmetro settings, passe um objeto que contenha as seguintes propriedades:
Propriedade | Tipo | Descrição |
---|---|---|
privileges | Text ou Collection | |
roles | Text ou Collection | |
userName | Text | Nome de usuário associado à sessão (opcional) |
Os privilégios e as funções são definidos no arquivo roles.json
do projeto. Para obter mais informações, consulte a seção Privilégios.
Se a propriedade privileges
ou roles
tiverem um nome que não seja declarado no arquivo roles.json
, ele será ignorado.
Como padrão quando não houver um privilégio associado à sessão, a sessão é uma Sessão de convidados.
A propriedade userName
está disponível no nível do objeto de sessão (somente leitura).
Exemplo
Em um método de autenticação personalizado, deve estabecer o privilégio "WebAdmin" ao usuário:
var $userOK : Boolean
... //Autenticar o usuário
If ($userOK) //O usuário foi aprovado
var $info : Object
$info:=New object()
$info.privileges:=New collection("WebAdmin")
Session.setPrivileges($info)
End if
Veja também
.storage
História
Release | Mudanças |
---|---|
20 R5 | Suporte a sessões de procedimento armazenado e cliente remoto |
18 R6 | Adicionado |
.storage : Object
Descrição
A propriedade .storage
contém um objeto compartilhado que pode ser usado para armazenar informações disponíveis para todos os processos da sessão.
Quando um objeto Session
é criado, a propriedade .storage
está vazia. Como se trata de um objeto compartilhado, essa propriedade estará disponível no objeto Storage
do servidor.
Como o objeto
Storage
do servidor, a propriedade.storage
é sempre "single": adicionar um objeto compartilhado ou uma coleção compartilhada a.storage
não cria um grupo compartilhado.
Essa propriedade é apenas de leitura, mas retorna um objeto de leitura e gravação.
Você pode obter a propriedade .storage
de uma sessão usando o comando Session storage
.
Exemplo de sessão na web
Você deseja armazenar o IP do cliente na propriedade .storage
. Você pode escrever no método de banco de dados 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
Exemplo de sessão remota
Você deseja compartilhar dados entre processos na mesma sessão:
Use (Session.storage)
Session.storage.settings:=New shared object("property"; $value; "property2"; $value2)
End use
.userName
História
Release | Mudanças |
---|---|
20 R5 | Suporte a sessões de procedimento armazenado e cliente remoto |
18 R6 | Adicionado |
.userName : Text
Descrição
A propriedade .userName
contém o nome de usuário associado à sessão. Pode usá-la para identificar o usuário dentro de seu código.
- Com sessões da Web, essa propriedade é uma cadeia de caracteres vazia por padrão. Ele pode ser definido usando a propriedade
privileges
da funçãosetPrivileges()
. - Com sessões de procedimento remotas e armazenadas, esta propriedade retorna o mesmo nome de usuário que o comando
Current user
. - Com sessões autônomas, essa propriedade contém "designer" ou o nome definido com o comando
SET USER ALIAS
.
Essa propriedade é somente leitura.