nginstack

Class: Security

@nginstack/engine/lib/security/Security~ Security

new Security()

Classe base de interação com o sistema no contexto da segurança.

Este é um objeto poderoso, portanto, deve-se prestar muita atenção ao seu uso Este objeto tem o poder de criar e apagar grupos e usuários, alterar senha e grupos de usuários, entre outros. O desenvolvedor é o único responsável pelos efeitos indesejados que possam decorrer da má utilização desse objeto.

Methods

<static> getInstance()

Obtém uma instância compartilhada desta classe.

Returns:
Type
Security

authenticateUser(userId, password)

Autentica as credenciais de um usuário e retorna a chave dele se as credenciais forem válidas.

Este método retorna -1 se as credenciais informadas forem inválidas ou se o e-mail informado estiver associado a mais de um usuário. Um erro é lançado se as credenciais estiverem corretas, mas se a conta não puder ser utilizada por estar bloqueada ou desativada.

Parameters:
Name Type Description
userId string

Nome ou e-mail do usuário.
password string

Senha do usuário.
Returns:

Chave do usuário autenticado ou -1 se as credenciais forem inválidas.

Type
number

authorizeToken(authToken, userId, password)

Autoriza um token previamente criado a ser utilizado pelo sistema.

Parameters:
Name Type Description
authToken module:@nginstack/engine/lib/security/AuthToken~AuthToken

Token de autorização.
userId string

Nome ou e-mail do usuário que irá autorizar o token e que será respectivamente vinculado à ele.
password string

Senha do usuário passado para autorização.
See:
Returns:

"ID" único do token que será utilizado para restaurar ou validar uma sessão.

Type
string

changePassword(userKey, oldPassword, newPassword)

Altera a senha de um usuário.

Importante: este método gerará um erro caso esteja sendo utilizada uma política de autenticação que envolva um autorizador externo, como a SSPI (Active Directory). Nesse caso, a modificação deve ser realizada pela interface do autorizador externo. Utilize o método #getAuthPolicyClass para determinar a política de autenticação do usuário.

Parameters:
Name Type Description
userKey number

Chave do usuário.
oldPassword string

Senha antiga.
newPassword string

Nova Senha.

createAuthToken(userId, password, expiration, data, localAuthentication)

Cria um token de autenticação legado, permitindo a autenticação automática numa sessão.

Parameters:
Name Type Description
userId string

Nome ou e-mail do usuário dono do token.
password string

Senha de usuário.
expiration Date

Data de validade do token(somente é considerado o dia).
data string

String opaca, armazenada no token.
localAuthentication boolean

Se True, o token será autenticado localmente, sem consultar o banco de dados.
Deprecated:
See:
Returns:

O token criado(somente os caracteres A-Z,a-z,0-9, @, _, =).

Type
string

createGroup(groupName, groups)

Cria um grupo no sistema.

Parameters:
Name Type Description
groupName string

Nome do grupo a ser criado.
groups Array

Grupos dos quais o grupo participará.
See:
Returns:

Chave do grupo criado.

Type
number

createUser(userName, password, groups)

Cria um usuário no sistema.

Parameters:
Name Type Description
userName string

Nome do usuário a ser criado.
password string

Senha do usuário de acesso ao sistema.
groups Array.<number>

Grupos dos quais o usuário participará.
See:
Returns:

Chave do usuário criado.

Type
number

deleteGroup(groupKey)

Exclui um grupo do sistema.

Parameters:
Name Type Description
groupKey number

Chave do grupo.
See:

deleteUser(userKey)

Exclui um usuário do sistema.

Parameters:
Name Type Description
userKey number

Chave do usuário.
See:

findUser(userId)

Pesquisa um usuário no sistema a partir do seu nome ou e-mail.

Este método retornará null se não localizar um usuário ou se houver mais de um usuário com o e-mail informado.

Parameters:
Name Type Description
userId string

Nome ou e-mail do usuário.
Returns:

Chave do usuário ou null caso não encontre um usuário válido.

Type
number

getAuthPolicy(userKey)

Obtém a política de autenticação aplicada ao usuário informado.

A política de autenticação é uma configuração da política de segurança associada diretamente ao usuário ou a um dos seus grupos e papéis. Será retornada a chave da política de autenticação padrão do sistema caso não haja nenhuma política de segurança associada ao usuário ou aos seus grupos e papéis.

Parameters:
Name Type Description
userKey DBKey | number

Chave do usuário do qual deseja-se obter a política de autenticação associada.
Returns:

Chave da política de autenticação.

Type
number

getAuthPolicyClass(userKey)

Obtém a classe da política de autenticação configurada para o usuário.

Atualmente, há três classes possíveis:

  • Políticas de autenticação padrão (-1898141725): onde o Engine é responsável por autenticar as credenciais do usuário.
  • Políticas de autenticação externa (-1898139694): onde o Engine delega a autenticação das credenciais do usuário a um provedor de identidade externo.
  • Política de autenticação SSPI (-1898141724): onde o Engine delega a autenticação das credenciais do usuário ao Windows via API SSPI. Atualmente, é suportado apenas o protocolo Microsoft NTLM.
Parameters:
Name Type Description
userKey DBKey | number

Chave do usuário.
Returns:

Chave da classe da política de autenticação do usuário.

Type
DBKey

getMimeTypesWithPermissionControl()

Obtém as chaves dos tipos de arquivos que tem controle de permissões.

Returns:
Type
Array.<number>

getPermission(classKeyOrVfsKey, permissionFieldName, userKey [, getMode] [, extraFilter])

Método utilizado para obter as permissões de um usuário em uma determinada classe ou script da Virtual File System

Parameters:
Name Type Argument Description
classKeyOrVfsKey number

Chave ou nome da classe da qual deseja-se saber se o usuário tem permissão.
permissionFieldName string

Nome do campo da tabela iPermission que define a permissão a ser obtida.
userKey number

Chave do usuário do qual se deseja descobrir a permissão.
getMode string <optional>

Determina como a permissão deve ser obtida. Os valores possíveis são:
"withoutInheritance": Obtém a permissão para a classe informada sem levar em conta as permissões definidas nas classes mães. Este parâmetro não é adequado para utilização com campos do tipo "string" que podem ser multivalorados, recomendamos o uso do parâmetro "distinct".
"first": Obtém a primeira permissão definida para a classe ou uma de suas mães, levando em conta a ordem da classe informada. A ordem considerada no sentido da classe atual até a classe root.
Neste modo não há herança se a chave informada for um script da iVFS como, por exemplo, um processo.
"max": Obtém o maior valor informado para a classe ou para uma de suas mães.
Neste modo não há herança se a chave informada for um script da iVFS como, por exemplo, um processo.
"min": Obtém o menor valor informado para a classe ou para uma de suas mães.
Neste modo não há herança se a chave informada for um script da iVFS como, por exemplo, um processo.
"distinct": Obtém todos os valores distintos informados para a classe ou para uma de suas mães. Se a permissão informada para uma classe possuir os separadores ";" ou ",", a mesma será dividida e cada elemento será considerado um valor distinto. Neste modo não há herança se a chave informada for um script da iVFS como, por exemplo, um processo.
"concat": Obtém todos os valores informados para a classe ou para uma de suas mães concatenados. Se a permissão informada para uma classe possuir os separadores ";" ou ",", a mesma será dividida e cada elemento será considerado um valor distinto. Neste modo não há herança se a chave informada for um script da iVFS como, por exemplo, um processo.

Se getMode não for informado, ele será considerado como 'withoutInheritance'.
extraFilter string | Array <optional>

Filtro extra que trás a possibilidade de filtrar a permissão por um outro campo da tabela de permissões(iPermission).
Examples
// Testa se o usuário corrente tem acesso à classe Entidades (-2007900000)
  if ( security.getPermission(-2007900000, 'iView') ){
      ...
  }

  // Obtém a lista de campos alteráveis para um determinado usuário. Retornará
  // null se ele possui acesso a todos os campos
  var chgFldNames = security.getPermission(-1896048403,
                                           'iChangeableFieldNames',
                                           userKey,
                                           'distinct');
// Para verificar se o usuário "37860639 -  Teste" tem acesso a classe "43614400 - Contatos" e
 // se o campo "estabeleci" no cadastro de permissões tem o valor
 // "3002932 - Estabelecimento Demonstração"
 security.getPermission(43614400, "iView", 37860639, "withoutInheritance",
     [['Estabeleci', 3002932]]);

getUserAccountType(userKey)

Obtém o tipo de conta de um usuário.

Parameters:
Name Type Description
userKey number | DBKey

Chave do usuário.
See:
Returns:

Chave de um registro da classe Tipos de Conta de Usuário (-1898139529).

Type
DBKey

getUserAndGroupsKeys(userKey)

Retorna um array contendo as chaves dos grupos aos quais o usuário pertence, onde primeiro item será sempre a chave do próprio usuário.

Esta lista define a ordem de prioridade dos grupos, onde os grupos de um grupo são inseridos logo após este na lista completa. Exemplo: se X participa dos grupos A, B, C, D e E, e o grupo B participa dos grupos D e C, a ordem será: X, A, B, D, C, C, D, E, Todos; que é simplificada para X, A, B, D, C, E e Todos.

Observe que com este conceito, o grupo "Todos" não necessariamente é o último grupo, visto que ele pode ser incluído explicitamente em um grupo.

Eventuais chaves de grupos inválidas, que não existam no cache local, serão ignoradas e não serão inseridas no array retornado, sendo esses casos registrados apenas no log. O motivo desse comportamento é evitar que um eventual erro de integridade impeça o login do usuário no sistema.

Parameters:
Name Type Description
userKey number

Chave do usuário.
Returns:

Array com as chaves dos grupos.

Type
Array

getUserScopes(userKey)

Obtém os escopos de autorização associados diretamente ao usuário ou indiretamente aos seus grupos e papéis.

Parameters:
Name Type Description
userKey DBKey | number

Chave do usuário do qual serão obtidos os escopos de autorização atribuídos.
Returns:

Escopos de autorização atribuídos ao usuário.

Type
Array.<string>

getUserStatus(userKey)

Obtém o status de um usuário.

Parameters:
Name Type Description
userKey number | DBKey

Chave do usuário.
See:
Returns:

Chave de um registro da classe Estados dos Usuários (-1898143910).

Type
DBKey

hasPermissionControl(key)

Indica se a chave informada possui controle de permissão ou não.

Parameters:
Name Type Description
key number

Chave que se deseja saber se há controle de permissões.
Returns:

True Caso tenha controle de permissão. chave.

Type
boolean

isAdministrator(userKey)

Retorna true caso o usuário seja um Administrador do sistema.

Parameters:
Name Type Description
userKey number

Chave do usuário.
Returns:

True se é um Administrador.

Type
boolean

isDeveloper(userKey)

Retorna true caso o usuário seja um Developer.

Parameters:
Name Type Description
userKey number

Chave do usuário.
Returns:

True se é um Developer.

Type
boolean

restoreAuthToken(accessToken)

Recupera um token autorizado anteriormente através dos métodos Security.authorizeToken ou Session.authorizeToken.

Parameters:
Name Type Description
accessToken string

Identificador do token que será restaurado.
See:
Returns:

Token recuperado.

Type
module:@nginstack/engine/lib/security/AuthToken~AuthToken

revokeAuthToken(accessToken)

Revoga a autorização de um token, tornando-o inutilizável.

Parameters:
Name Type Description
accessToken string

Token que será revogado e não poderá ser mais utilizado.
See:

revokeAuthTokenByKey(key, userId, password)

Revoga a autorização de um token, tornando-o inutilizável.

Parameters:
Name Type Description
key number

Chave do registro do AuthToken.
userId string

Nome ou e-amil do usuário que autorizou o token.
password string

Senha referente ao nome de usuário.
See:

setPassword(userKey, password)

Altera a senha do usuário informado.

O usuário autenticado na sessão deverá ter o escopo de autorização "security.changeUserPassword" caso esteja modificando a senha de um outro usuário.

Parameters:
Name Type Description
userKey Object

Chave do usuário que terá a senha alterada.
password Object

Nova senha.

setUserAccountType(userKey, accountType)

Altera o tipo da conta do usuário.

Importante: alterações do tipo da conta do usuário somente podem ser realizadas por este método. Modificações realizadas diretamente no registro da tabela tornarão inválida a assinatura de integridade do registro, impedindo a utilização da conta de usuário.

Parameters:
Name Type Description
userKey number | DBKey

Chave do usuário.
accountType DBKey

Chave de um registro da classe Tipos de Conta de Usuário (-1898139529).
See:

setUserStatus(userKey, status)

Altera o estado da conta do usuário.

Estados possíveis:

  • Ativo: -1898143909
  • Bloqueado: -1898143908
  • Desativado: -1898141728
  • Expirado: -1898143907

Este método gerará um erro caso o estado informado seja "Expirado" (-1898143907) e esteja sendo utilizada uma política de autenticação que envolva um autorizador externo, como a SSPI (Active Directory). Nesse caso, a modificação deve ser realizada pela interface do autorizador externo. Utilize o método #getAuthPolicyClass para determinar a política de autenticação do usuário.

Importante: alterações do estado da conta do usuário somente podem ser realizadas por este método. Modificações realizadas diretamente no registro da tabela tornarão inválida a assinatura de integridade do registro, impedindo a utilização da conta de usuário.

Parameters:
Name Type Description
userKey number | DBKey

Chave do usuário.
status DBKey

Chave de um registro da classe Estados dos Usuários (-1898143910).
See:

suggestPermissionApplyMode(parent)

Sugere o modo de aplicação padrão para uma permissão da classe ou arquivo informado.

Parameters:
Name Type Description
parent number

Chave da classe ou arquivo ao qual a permissão está associada.
Returns:

Chave do modo de aplicação de permissão ou null caso a chave informada não exista ou não seja uma classe.

Type
number

updateAuthToken(token, userId, password)

Atualiza um token previamente autorizado pelo método Security.authorizeToken. Após a autorização de um token, apenas as propriedades module:@nginstack/engine/lib/security/AuthToken~AuthToken#description e module:@nginstack/engine/lib/security/AuthToken~AuthToken#expires podem ser modificadas.

Parameters:
Name Type Description
token module:@nginstack/engine/lib/security/AuthToken~AuthToken

Token que terá as suas propriedades atualizadas.
userId string

Nome ou e-mail do usuário que autorizou o token.
password string

Senha do usuário vinculado ao token.
See:

userCanModifyKey(key, classKey [, userKey])

Verifica se o usuário pode alterar o registro informado. Caso seja uma chave do sistema, será verificado se o usuário está habilitado como desenvolvedor do produto do qual a chave faz parte.

Parameters:
Name Type Argument Description
key number

Chave do registro.
classKey number

Classe do registro.
userKey number <optional>

Chave do usuário que deseja saber se possui permissão para alterar um registro. Caso não seja informado será considerado o usuário logado na sessão.
Returns:

True se é possível modificar. False, caso contrário.

Type
boolean

userCanModifyRecord(ds [, userKey])

Verifica se o usuário pode alterar o registro corrente do DataSet. Caso seja um registro do sistema, será verificado se o usuário está habilitado como desenvolvedor do produto do qual o registro faz parte.

Parameters:
Name Type Argument Description
ds DataSet

Dataset que contém o registro que será verificado.
userKey number <optional>

Chave do usuário que deseja saber se possui permissão para alterar um registro. Caso não seja informado será considerado o usuário logado na sessão.
Returns:

True se é possível alterar. False, caso contrário.

Type
boolean

userHasScope(userKey, scope)

Verifica se o escopo informado foi atribuído ao usuário.

Parameters:
Name Type Description
userKey DBKey | number

Chave do usuário ao qual se deseja verificar a atribuição do escopo.
scope string | DBKey | number

Nome ou chave do escopo a ter a atribuição verificada.
Returns:

True se o escopo indicado por scope tiver sido atribuído ao usuário.

Type
boolean

userSignatureIsValid(userKey)

Verifica se a assinatura de integridade da conta de usuário é válida, garantindo que as alterações da conta de usuário foram realizadas de forma segura pela classe Security.

Parameters:
Name Type Description
userKey number | DBKey

Chave do usuário.
Returns:

True se assinatura for válida.

Type
boolean