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:
-
- Este método foi substituído por module:@nginstack/engine/lib/security/AuthToken.
- See:
-
- Session#loginByAuthToken
- module:@nginstack/engine/lib/security/AuthToken
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:
-
- module:@nginstack/engine/lib/security/AuthToken
- module:@nginstack/engine/lib/security/Security~Security#authorizeToken Security.authorizeToken
- module:@nginstack/engine/lib/session/Session~Session#authorizeToken
Returns:
Token recuperado.
-
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.
-
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.
-
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:
-
- module:@nginstack/engine/lib/security/AuthToken~AuthToken
- Session#updateAuthToken
-
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