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

authenticateAuthToken(authToken)

Autentica um token de autorização e retorna suas informações. Este método não realiza login no sistema, apenas valida o token.

Um erro é lançado se o token informado for inválido ou se estiver associado a um usuário inválido.

Parameters:
Name Type Description
authToken string

Token de autorização.
Returns:

Informações do token autenticado, podendo incluir as propriedades userKey, userName, tokenKey, providerKey, scope e data.

Type
AuthTokenInfo

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:

encryptSecret(key, secret)

Encripta um segredo de acesso utilizado nas APIs do Engine de comunicação com serviços de terceiros, permitindo que ele possa ser gravado em um registro da base de dados com um nível adicional de segurança.

Uma vez encriptados, os segredos protegidos por este método somente podem ser lidos pelo Engine durante a utilização de APIs nativas, como a classe ObjectStorage, não sendo possível a recuperação do segredo via código JavaScript ou qualquer outro meio.

Importante: este método permite a gravação de segredos na base de dados com um maior nível de segurança, no entanto essa segurança não deve ser considerada inviolável. Por esse motivo, as credenciais gravadas devem ser únicas para o sistema e não devem ser compartilhadas com outros serviços. Elas também devem ser renovadas periodicamente.

Parameters:
Name Type Description
key DBKey | number

Chave de um cadastro associado a esse segredo.
secret string

Segredo de acesso.
Returns:

Segredo de acesso encriptado.

Type
string

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