API Documentation

Classes

Permission

Represents a security permission in the system. Mapped internally to a Servoy security group which must be defined.

Role

Security role which can have user members and can be granted permissions.

Session

Security application session created by a User which starts when the user logs in and ends when the user logs out.

Tenant

Tenant account which is used to segregate all data. Users and Roles belong to a Tenant.

User

Application user account associated with a Tenant. Security Permissions are granted to users through their Role membership.

Functions

changeExternalDBTransactionSupportFlag(mustSupportExternalTransactions)

Use this method to change the behavior of the svySecurity module with respect to DB transactions.

If the flag is set to false (default) then when saving or deleting security-related records if an external DB transaction is detected the operation will fail. If the flag is set to true then when saving or deleting security-related records the module will start/commit a DB transaction only if an external DB transaction is not detected. On exceptions any DB transaction will be rolled back regardless if it is started internally or externally (exceptions will be propagated to the external transaction so callers will be able to react on them accordingly)

cloneTenant(tenantToClone, name, [makeSlave]) ⇒ Tenant

Creates and returns a new tenant with the specified name as a clone of the given tenant. The names of tenants must be unique in the system. The cloned tenant has the same roles and role permissions as the original. When makeSlave is true, the newly created clone will be a slave of the tenant to clone, inheriting all role / permission changes made to the master. WARNING: Cannot call this function when logged in as an user.

consumeAccessToken(token) ⇒ User

Consumes a secure-access token and returns the user associated with the token if a valid match was found. Tokens may be used only once to identify a user. Subsequent calls to consume the same token will fail. Secure-access tokens are created with generateAccessToken

createTenant(name) ⇒ Tenant

Creates and returns a new tenant with the specified name. The names of tenants must be unique in the system.

deleteTenant(tenant) ⇒ Boolean

Immediately and permanently deletes the specified tenant and all records associated with it, including all users and roles. Tenant will not be deleted if it has users with active sessions. If the deleted tenant is a Master tenant and is a slave of another master tenant, this operation will replace the master tenant of it's direct slaves with the master of the tenant that is deleted; If the delated tenant is a Master tenant and has no Master tenant, this operation will remove the master from all it's direct slaves.

getActiveSessions() ⇒ [ 'Array' ].<Session>

Gets all active sessions for the application.

getPermission(name) ⇒ Permission

Gets a permission by its unique permission name.

getPermissions() ⇒ [ 'Array' ].<Permission>

Gets all permissions available in this application.

getRole(roleName, [tenantName]) ⇒ Role

Gets a role by the specified role name and tenant name. If tenant name is not specified will use the tenant of the user currently logged in the application, if available.

getSession() ⇒ Session

Gets the current user session or null if no session initialized (no user is currently logged in).

getSessionCount() ⇒ Number

Gets the number of all unique sessions which have ever been initialized in the application. This includes both active sessions (for users currently logged in the application) and inactive sessions (sessions from the past which have already been closed).

getTenant([name]) ⇒ Tenant

Gets a tenant by its unique tenant name. If tenant name is not specified then will return the tenant of the currently logged in user. If tenant name is not specified and no user is currently logged in then will return null.

getTenants() ⇒ [ 'Array' ].<Tenant>

Gets all tenants in the system.

getUser([userName], [tenantName]) ⇒ User

Gets a user by the specified username and tenant name. If username is not specified will return the user currently logged in the application, if available.

getUsers() ⇒ [ 'Array' ].<User>

Gets all users in the system.

getVersion() ⇒ String

Gets the version of this module

login(user, [userUid], [permissionsToApply]) ⇒ Boolean

Logs in the specified user and initializes a new Session for it. The login request will not be successful if the user account or the parent tenant account is locked and the lock has not expired yet. The login request will not be successful also if no permissions have been granted to the specified user. This method internally calls the standard Servoy security.login().

logout()

Logs the current user out of the application and closes the associated Session. This method internally calls security.logout() to end the Servoy client session.

syncPermissions([forcePermissionRemoval])

Utility to sync permission records to the internal, design-time Servoy Security Groups. This should be called on solution import or on startup This action will create new permission records.

NOTE: This action will not delete permissions which have been removed from internal security. Design-time groups should never be renamed. They will be seen only as an ADD and will lose their tie to roles.

Permission

Represents a security permission in the system. Mapped internally to a Servoy security group which must be defined.

• Permission

  • .addRole(role) ⇒ Permission
  • .getDisplayName() ⇒ String
  • .getName() ⇒ String
  • .getRoles() ⇒ [ 'Array' ].<Role>
  • .getUsers() ⇒ [ 'Array' ].<User>
  • .hasRole(role) ⇒ Boolean
  • .removeRole(role) ⇒ Permission
  • .setDisplayName([displayName]) ⇒ Permission
  • new Permission(record)

---

permission.addRole(role) ⇒ Permission

Grants this permission to the specified role. The permission will be granted to all users that are members of the specified role. If the tenant of this permission is a master tenant, the role will also be added to the same permission for all the slaves of this permission tenant. You cannot grant permission to role of a master tenant when logged in as an user. You cannot grant permission to role of a slave tenant at anytime.

Returns: Permission - This permission for call-chaining support. Throws an exception when permission cannot be granted.

Param	Type	Description
role	Role	The role object to which the permission should be granted.

permission.getDisplayName() ⇒ String

Gets the display name of this permission. The display name can be set using setDisplayName.

Returns: String - The display name of the permission. Can be null.

permission.getName() ⇒ String

Gets the name of this permission. The permission name is unique in the system and matches a Servoy security group name.

Returns: String - The name of the permission.

permission.getRoles() ⇒ [ 'Array' ].<Role>

Gets all the roles to which this permission is granted.

Returns: [ 'Array' ].<Role> - An array with all roles to which this permission is granted or an empty array if the permission has not been granted to any role.

permission.getUsers() ⇒ [ 'Array' ].<User>

Gets all users whom this permission is granted to via the users' role membership.

Returns: [ 'Array' ].<User> - An array with all users whom this permission is granted to or an empty array if no user has this permission.

permission.hasRole(role) ⇒ Boolean

Checks if this permission is granted to the specified role.

Returns: Boolean - True if this permission is granted to the specified role.

Param	Type	Description
role	Role | String	The role object or the name of the role to check.

permission.removeRole(role) ⇒ Permission

Removes this permission from the specified role. The permission will no longer be granted to all users that are members of the specified role. If the tenant of this permission is a master tenant, the role will also be removed from the same permission for all the slaves of this permission tenant. You cannot remove permission from role of a master tenant when logged in as an user. You cannot remove permission from role of a slave tenant at anytime.

Returns: Permission - This permission for call-chaining support. Throws an exception when permission cannot be removed.

Param	Type	Description
role	Role | String	The role object or the name of the role to remove.

permission.setDisplayName([displayName]) ⇒ Permission

Sets the display name of this permission.

Returns: Permission - This permission for call-chaining support.

Param	Type	Description
[displayName]	String	The display name to use.

new Permission(record)

Permission objects cannot be created through the API. They are created automatically when the scope is loaded. Use getPermission or getPermissions to get permission objects. Creating permission objects with the new operator is reserved for internal use only.

Param	Type
record	[ 'JSRecord' ].<permissions>

---

Role

Security role which can have user members and can be granted permissions.

• Role

  • .addPermission(permission) ⇒ Role
  • .addUser(user) ⇒ Role
  • .getDisplayName() ⇒ String
  • .getName() ⇒ String
  • .getPermissions() ⇒ [ 'Array' ].<Permission>
  • .getTenant() ⇒ Tenant
  • .getUsers() ⇒ [ 'Array' ].<User>
  • .hasPermission(permission) ⇒ Boolean
  • .hasUser(user) ⇒ Boolean
  • .removePermission(permission) ⇒ Role
  • .removeUser(user) ⇒ Role
  • .setDisplayName(displayName) ⇒ Role
  • new Role(record)

role.addPermission(permission) ⇒ Role

Grants the specified permission to this role. Any users that are members of this role will be granted the permission. If the tenant of this role is a master tenant, the permission will also be added to the same role in all slaves of this role tenant. You cannot grant permission to role of a master tenant when logged in as an user. You cannot grant permission to role of a slave tenant at anytime.

Returns: Role - This role for call-chaining support.

Param	Type	Description
permission	Permission | String	The permission object or name of permission to add.\ Throws an exception when permission cannot be grant.

role.addUser(user) ⇒ Role

Adds the specified user as member of this role. All permissions granted to this role will be granted to the user.

Returns: Role - This role for call-chaining support.

Param	Type	Description
user	User | String	The user object or username of user to add. The user must be associated with the tenant of this role.

role.getDisplayName() ⇒ String

Gets the display name of this role.

Returns: String - The display name of this role. Can be null.

role.getName() ⇒ String

Gets the name of this role. The role name is unique to the associated tenant.

Returns: String - The role name.

role.getPermissions() ⇒ [ 'Array' ].<Permission>

Gets all the permissions granted to this role.

Returns: [ 'Array' ].<Permission> - An array with all permissions granted to this role or an empty array if no permissions are granted.

role.getTenant() ⇒ Tenant

Gets the tenant which this role belongs to.

Returns: Tenant - The tenant which this role belongs to.

role.getUsers() ⇒ [ 'Array' ].<User>

Gets all the users who are members of this role.

Returns: [ 'Array' ].<User> - An array with all users who are members of this role or an empty array if the role has no members.

role.hasPermission(permission) ⇒ Boolean

Checks if the specified permission is granted to this role.

Returns: Boolean - True if the specified permission is granted to this role.

Param	Type	Description
permission	Permission | String	The permission object or name of permission to check.

role.hasUser(user) ⇒ Boolean

Checks if the specified user is a member of this role.

Returns: Boolean - True if the specified user is a member of this role.

Param	Type	Description
user	User | String	The user object or username of user to check. The user must be associated with the tenant of this role.

role.removePermission(permission) ⇒ Role

Removes the specified permission from this role. The permission will no longer be granted to all users that are members of this role. If the tenant of this role is a master tenant, the permission will also be removed from the same role in all slaves of this role tenant. You cannot remove permission from role of a master tenant when logged in as an user. You cannot remove permission from role of a slave tenant at anytime.

Returns: Role - This role for call-chaining support. Throws an exception when permission cannot be removed.

Param	Type	Description
permission	Permission | String	The permission object or name of permission to remove.

role.removeUser(user) ⇒ Role

Removes the specified user from the members of this role. All permissions granted to this role will no longer be granted to the user.

Returns: Role - This role for call-chaining support.

Param	Type	Description
user	User | String	The user object or username of user to remove.

role.setDisplayName(displayName) ⇒ Role

Sets the display name of this role. If the tenant of this role is a master tenant, the displayName will be set to the same role in all slaves of this role tenant. You cannot set the display name to role of a master tenant when logged in as an user. You cannot set the display name to role of a slave tenant at anytime.

Returns: Role - This role for call-chaining support. throws an exception if the displayName cannot be changed

Param	Type	Description
displayName	String	The display name to use.

new Role(record)

Use createRole to create role objects. Creating role objects with the new operator is reserved for internal use only.

Param	Type
record	[ 'JSRecord' ].<roles>

---

Session

Security application session created by a User which starts when the user logs in and ends when the user logs out.

• Session

  • .getDuration() ⇒ Number
  • .getEnd() ⇒ Date
  • .getID() ⇒ String
  • .getIPAddress() ⇒ String
  • .getServoyClientID() ⇒ String
  • .getSolutionName() ⇒ String
  • .getStart() ⇒ Date
  • .getTenant() ⇒ Tenant
  • .getTenantName() ⇒ String
  • .getUser() ⇒ User
  • .getUserAgentString() ⇒ String
  • .getUserName() ⇒ String
  • .isAbandoned() ⇒ Boolean
  • .isActive() ⇒ Boolean
  • .isTerminated() ⇒ Boolean
  • new Session(record)

session.getDuration() ⇒ Number

Gets the session duration in milliseconds (as updated in the database)

Returns: Number - The Servoy Client ID associated with the session.

Note: The session duration is updated on each "client ping" which by default is once per minute

session.getEnd() ⇒ Date

Gets the end datetime of this session. Can be null if the session is still active or if the session has not been properly closed. The session end date/time is set by logout.

Returns: Date - The end date/time of this session.

session.getID() ⇒ String

Gets the internal unique ID of this session. This matches the Servoy Client ID as seen in the Servoy App Server admin page.

Returns: String - The internal unique ID of this session.

session.getIPAddress() ⇒ String

Gets the client IP address of the session.

Returns: String - The client IP address of the session.

session.getServoyClientID() ⇒ String

Gets the Servoy Client ID associated with the session (as shown on the Servoy app server admin page).

Returns: String - The Servoy Client ID associated with the session.

Note: Multiple user sessions can have the same Servoy Client ID if the client is not closed between different logins (for NG/Web clients this requires complete closing of the browser and not just a tab).

session.getSolutionName() ⇒ String

Gets the name of the Servoy solution that was accessed by this session

session.getStart() ⇒ Date

Gets the start date/time of this session. The session start date/time is set by login.

Returns: Date - The start date/time of this session.

session.getTenant() ⇒ Tenant

Gets the tenant associated with this session. Returns null if the tenant has been deleted. In such cases use getTenantName as it will be preserved even if the tenant account is deleted.

session.getTenantName() ⇒ String

Gets the name of the tenant associated with this session. It will be available even if the associated tenant account is deleted.

Returns: String - The name of the tenant associated with this session.

session.getUser() ⇒ User

Gets the user who created this session. Returns null if the user account has been deleted. In such cases use getUserName as it will be preserved even if the user account is deleted.

Returns: User - The user who created this session or null if the user account has been deleted.

session.getUserAgentString() ⇒ String

Gets the client user agent string of the session. The user agent string will be null if the session was not browser-based.

Returns: String - The client user agent string of this session. Can be null.

session.getUserName() ⇒ String

The username of the user associated with this session. It will be available even if the associated user account is deleted.

Returns: String - The username of the user who created this session.

session.isAbandoned() ⇒ Boolean

Indicates if this session was abandoned and closed due to inactivity and was not closed by logout.

Returns: Boolean - True if this session was not terminated/closed normally, but has timed out due to inactivity.

session.isActive() ⇒ Boolean

Indicates if this session is still active.

Returns: Boolean - True if the session has not been terminated and has not been inactive for longer than the session inactivity timeout period.

session.isTerminated() ⇒ Boolean

Indicates if this session was terminated/closed using logout or closed due to inactivity.

Returns: Boolean - True if the session was terminated/closed normally or by timeout from inactivity.

new Session(record)

Session objects cannot be created through the API. They are created automatically when a user is logged in. Use getSession to get the current session or getActiveSessions to get all active sessions. Creating session objects with the new operator is reserved for internal use only.

Param	Type
record	[ 'JSRecord' ].<sessions>

---

Tenant

Tenant account which is used to segregate all data. Users and Roles belong to a Tenant.

• Tenant

  • .createRole(name) ⇒ Role
  • .createSlave(name) ⇒ Tenant
  • .createUser(userName, [password]) ⇒ User
  • .deleteRole(role) ⇒ Tenant
  • .deleteUser(user) ⇒ Boolean
  • .getActiveSessions() ⇒ [ 'Array' ].<Session>
  • .getDisplayName() ⇒ String
  • .getLockExpiration() ⇒ Date
  • .getLockReason() ⇒ String
  • .getName() ⇒ String
  • .getRole(name) ⇒ Role
  • .getRoles() ⇒ [ 'Array' ].<Role>
  • .getSessionCount() ⇒ Number
  • .getSlaves() ⇒ [ 'Array' ].<Tenant>
  • .getUser(userName) ⇒ User
  • .getUsers() ⇒ [ 'Array' ].<User>
  • .isLocked() ⇒ Boolean
  • .isMasterTenant() ⇒ Boolean
  • .isSlaveTenant() ⇒ Boolean
  • .lock([reason], [duration]) ⇒ Tenant
  • .setDisplayName(displayName) ⇒ Tenant
  • .unlock() ⇒ Tenant
  • new Tenant(record)

tenant.createRole(name) ⇒ Role

Creates a role associated with this tenant using the specified role name. If this is a Master Tenant the created role will be added to all slaves of this Tenant. Cannot create role for a master tenant when logged in as an user.

Returns: Role - The role which was created. If the role name is not unique to this tenant.

Param	Type	Description
name	String	The name of the role to be created. Must be unique to this tenant.

tenant.createSlave(name) ⇒ Tenant

Creates a slave of this tenant with the given name. Modifications to roles and permissions of this tenant will be propagated to all of its slaves.

WARNING: Cannot call this function when logged in as an user.

Returns: Tenant - slave The slave that has been created

Param	Type	Description
name	String	The name of the tenant. Must be unique and no longer than 50 characters. Throws an exception if this function is called when logged in as an user.

tenant.createUser(userName, [password]) ⇒ User

Creates a user with the specified user name.

Returns: User - The user which was created. If the user name is not specified or is not unique.

Note: If password is not specified the user account will be created with a blank password. Use setPassword to set or change the user password.

Param	Type	Description
userName	String	Must be unique in system.
[password]	String	The password to use for the new user.

tenant.deleteRole(role) ⇒ Tenant

Deletes the specified role from this tenant. All associated permissions and grants to users are removed immediately. Users with active sessions will be affected, but design-time security (CRUD, UI) will not be affected until next log-in.

If this is a Master Tenant the deleted role will be deleted also for all slaves of this Tenant. Cannot delete role of a master tenant when logged in as an user.

Returns: Tenant - This tenant for call-chaining support.

Param	Type	Description
role	Role | String	The role object or name of role to be deleted. The role must be associated with this tenant. throws an exception if the role cannot be deleted.

tenant.deleteUser(user) ⇒ Boolean

Immediately and permanently deletes the specified user and all security-related records associated with it. The user will not be deleted if it has active sessions.

Returns: Boolean - True if the user is deleted, otherwise false.

Note: USE WITH CAUTION! There is no undo for this operation.

Param	Type	Description
user	User | String	The user object or the username of the user to be deleted. The specified user must be associated with this tenant.

tenant.getActiveSessions() ⇒ [ 'Array' ].<Session>

Gets the active sessions for users associated with this tenant. This includes any sessions from any device and any location for users associated with this tenant.

Returns: [ 'Array' ].<Session> - An array with all active sessions for users associated with this tenant or an empty array if the are no active sessions.

Note: Any unterminated sessions are deemed to be active when they have not been idle for more than a set timeout period.

tenant.getDisplayName() ⇒ String

Gets the display name of this tenant. The display name can be set using setDisplayName.

Returns: String - The display name of this tenant. Can be null if a display name is not set.

tenant.getLockExpiration() ⇒ Date

Gets the expiration date/time of the lock created by lock. The lock will remain in place until it expires or it is removed using unlock.

Returns: Date - The date/time when the lock expires. Can be null. The date/time is using the Servoy application server timezone.

tenant.getLockReason() ⇒ String

Gets the reason for the account lock created by lock.

Returns: String - The lock reason. Can be null.

tenant.getName() ⇒ String

Gets the name of this tenant. Tenant names are unique in the system and are specified when the tenant is created.

Returns: String - The name of this tenant.

tenant.getRole(name) ⇒ Role

Gets a role by name unique to this tenant.

Returns: Role - The matching role, or null if a role with the specified name and associated with this tenant is not found.

Param	Type	Description
name	String	The name of the role to get.

tenant.getRoles() ⇒ [ 'Array' ].<Role>

Gets the roles associated with this tenant.

Returns: [ 'Array' ].<Role> - An array with the roles associated with this tenant or an empty array if the tenant has no roles.

tenant.getSessionCount() ⇒ Number

Gets the number of all unique sessions which have ever been initialized in the system by users associated with this tenant. This includes both active sessions (for users currently logged in the application) and inactive sessions (sessions from the past which have already been terminated).

Returns: Number - The number of all sessions (active and inactive) for users associated with this tenant.

tenant.getSlaves() ⇒ [ 'Array' ].<Tenant>

Gets all slaves of this tenant When recursive is true, all slaves of this tenant's slaves are included WARNING: Cannot call this function when logged in as an user.

Throws an exception if this function is called when logged in as an user.

Returns: [ 'Array' ].<Tenant> - slaves Array of tenants that have this tenant as their master

tenant.getUser(userName) ⇒ User

Gets the user (associated with this tenant) specified by the username.

Returns: User - The matching user or null if a user with the specified username and associated with this tenant is not found.

Param	Type	Description
userName	String	The username of the user.

tenant.getUsers() ⇒ [ 'Array' ].<User>

Gets all users for this tenant.

Returns: [ 'Array' ].<User> - An array with all users associated with this tenant or an empty array if the tenant has no users.

tenant.isLocked() ⇒ Boolean

Indicates if the tenant account is locked using lock.

Returns: Boolean - True if the tenant account is currently locked and the lock has not expired.

tenant.isMasterTenant() ⇒ Boolean

Returns true if this Tenant is a master (template) tenant WARNING: When the user is already logged, can call this function only for the tenant of the logged user; cannot call this function for other tenants when logged in as an user.

Returns: Boolean - isMasterTenant Whether this tenant is a master to other tenants

Throws an exception when logged in as an user and called for another tenant than the tenant of the logged user.

tenant.isSlaveTenant() ⇒ Boolean

Returns true if this Tenant is a slave tenant

Returns: Boolean - isMasterTenant Whether this tenant is a master to other tenants

tenant.lock([reason], [duration]) ⇒ Tenant

Locks the tenant account preventing its users from logging in. The lock will remain in place until it expires (if a duration was specified) or it is removed using {Tenant#unlock}. Users with active sessions will be unaffected until subsequent login attempts. Can be called even if the tenant is already locked. In such cases the lock reason and duration will be reset.

Returns: Tenant - This tenant for call-chaining support.

Param	Type	Description
[reason]	String	The reason for the lock.
[duration]	Number	The duration of the lock (in milliseconds). If no duration specified, the lock will remain until {Tenant#unlock} is called.

tenant.setDisplayName(displayName) ⇒ Tenant

Sets the display name of this tenant.

Returns: Tenant - This tenant for call-chaining support.

Param	Type	Description
displayName	String	The display name to use.

tenant.unlock() ⇒ Tenant

Removes the lock on the tenant account which is created by lock. Can be safely called even if the tenant is not locked.

Returns: Tenant - This tenant for call-chaining support.

new Tenant(record)

Use createTenant to create tenant objects. Creating tenant objects with the new operator is reserved for internal use only.

Param	Type	Description
record	[ 'JSRecord' ].<tenants>	The database record where the tenant account information is stored.

---

User

Application user account associated with a Tenant. Security Permissions are granted to users through their Role membership.

• User

  • .addRole(role) ⇒ User
  • .checkPassword(password) ⇒ Boolean
  • .generateAccessToken([duration]) ⇒ String
  • .getActiveSessions() ⇒ [ 'Array' ].<Session>
  • .getDisplayName() ⇒ String
  • .getEmail() ⇒ String
  • .getLockExpiration() ⇒ Date
  • .getLockReason() ⇒ String
  • .getPermissions() ⇒ [ 'Array' ].<Permission>
  • .getRoles() ⇒ [ 'Array' ].<Role>
  • .getSessionCount() ⇒ Number
  • .getTenant() ⇒ Tenant
  • .getUserName() ⇒ String
  • .hasPermission(permission) ⇒ Boolean
  • .hasRole(role) ⇒ Boolean
  • .isLocked() ⇒ Boolean
  • .lock([reason], [duration]) ⇒ User
  • .removeRole(role) ⇒ User
  • .setDisplayName(displayName) ⇒ User
  • .setEmail(email) ⇒ User
  • .setPassword(password) ⇒ User
  • .unlock() ⇒ User
  • new User(record)

user.addRole(role) ⇒ User

Adds this user as member of the specified role and grants the user all permissions which the role has.

Returns: User - This user for call-chaining support.

Param	Type	Description
role	Role | String	The role object or role name to use. The role must be associated with the tenant of this user.

user.checkPassword(password) ⇒ Boolean

Checks if the specified password matches the password of this user. User password can be set when the user is created or by using setPassword.

Returns: Boolean - True if the specified password matches the password of this user.

Param	Type	Description
password	String	The password (plain-text) to check.

user.generateAccessToken([duration]) ⇒ String

Generates a secure access token to authenticate this user within a window of validity of the specified duration. The generated access token can be used with consumeAccessToken.

Returns: String - The generated access token.

Param	Type	Description
[duration]	Number	The duration of token validity in milliseconds. Default is 30 minutes in future.

user.getActiveSessions() ⇒ [ 'Array' ].<Session>

Gets the active sessions this user. This includes any sessions from any device and any location for this user.

Returns: [ 'Array' ].<Session> - An array with all active sessions for this user or an empty array if the are no active sessions.

Note: Any unterminated sessions are deemed to be active when they have not been idle for more than a set timeout period.

user.getDisplayName() ⇒ String

Gets the display name of this user, i.e. "Jane Doe". The display name can be set using setDisplayName.

Returns: String - The display name of this user.

user.getEmail() ⇒ String

Returns: String - The email of this user.

user.getLockExpiration() ⇒ Date

Gets the expiration date/time of the lock created by lock. The lock will remain in place until it expires or it is removed using unlock.

Returns: Date - The date/time when the lock expires. Can be null. The date/time is using the Servoy application server timezone.

user.getLockReason() ⇒ String

Gets the reason for the account lock created by lock.

Returns: String - The lock reason. Can be null.

user.getPermissions() ⇒ [ 'Array' ].<Permission>

Gets all the permissions granted to this user via its roles membership. Result will exclude duplicates. Permissions cannot be granted directly to the user. Use addRole or addUser to make the user a member of specific roles and all role permissions will be granted to the user.

Returns: [ 'Array' ].<Permission> - An array with the permissions granted to this user or an empty array if the user has no permissions.

user.getRoles() ⇒ [ 'Array' ].<Role>

Gets all the roles that this user is member of.

Returns: [ 'Array' ].<Role> - An array with all roles which this user is member of or an empty array if the user is not a member of any role.

user.getSessionCount() ⇒ Number

Gets the number of all unique sessions which have ever been initialized in the system by this user. This includes both active sessions (for users currently logged in the application) and inactive sessions (sessions from the past which have already been terminated).

Returns: Number - The number of all sessions (active and inactive) for this user.

user.getTenant() ⇒ Tenant

Returns the tenant that owns this user account.

Returns: Tenant - The parent tenant associated with this user.

user.getUserName() ⇒ String

Gets the username of this user which was specified when the user was created. The username cannot be changed after the user is created and is unique to the associated tenant.

Returns: String - The username of this user.

user.hasPermission(permission) ⇒ Boolean

Checks if the this user is granted the specified permission via the user's role membership. Permissions cannot be granted directly to the user. Use addRole or addUser to make the user a member of specific roles and all role permissions will be granted to the user.

Returns: Boolean - True if the user has been granted the specified permission.

Param	Type	Description
permission	Permission | String	The permission object or permission name to check.

user.hasRole(role) ⇒ Boolean

Checks if this user is a member of the specified role.

Returns: Boolean - True if the user is a member of the specified role.

Param	Type	Description
role	Role | String	The role object or role name to check. The role must be associated with the tenant of this user.

user.isLocked() ⇒ Boolean

Indicates if the use account is locked using lock.

Returns: Boolean - True if the user account is currently locked and the lock has not expired.

user.lock([reason], [duration]) ⇒ User

Locks the user account preventing it from logging in. The lock will remain in place until it expires (if a duration was specified) or it is removed using {User#unlock}. Users with active sessions will be unaffected until subsequent login attempts. Can be called even if the user account is already locked. In such cases the lock reason and duration will be reset.

Returns: User - This user for call-chaining support.

Param	Type	Description
[reason]	String	The reason for the lock.
[duration]	Number	The duration of the lock (in milliseconds). If no duration specified, the lock will remain until {User#unlock} is called.

user.removeRole(role) ⇒ User

Removes the membership of this user from the specified role. All permissions of the role will no longer be granted to the user.

Returns: User - This user for call-chaining support.

Param	Type	Description
role	Role | String	The role object or role name to use. The role must be associated with the tenant of this user.

user.setDisplayName(displayName) ⇒ User

Sets the display name of this user.

Returns: User - This user for call-chaining support.

Param	Type	Description
displayName	String	The display name to use.

user.setEmail(email) ⇒ User

Returns: User - This user for call-chaining support.

Param	Type
email	String

user.setPassword(password) ⇒ User

Sets the users password. The specified plain-text password will not be stored. Only its hash will be stored and used for password validation. The actual plain-text password cannot be retrieved from the stored hash.

Returns: User - This user for call-chaining support.

Param	Type	Description
password	String	The plain-text password to use.

user.unlock() ⇒ User

Removes the lock on the user account which is created by lock. Can be safely called even if the user account is not locked.

Returns: User - This user for call-chaining support.

new User(record)

Param	Type
record	[ 'JSRecord' ].<users>

---

changeExternalDBTransactionSupportFlag(mustSupportExternalTransactions)

Use this method to change the behavior of the svySecurity module with respect to DB transactions.

If the flag is set to false (default) then when saving or deleting security-related records if an external DB transaction is detected the operation will fail. If the flag is set to true then when saving or deleting security-related records the module will start/commit a DB transaction only if an external DB transaction is not detected. On exceptions any DB transaction will be rolled back regardless if it is started internally or externally (exceptions will be propagated to the external transaction so callers will be able to react on them accordingly)

Note: If using external DB transactions then callers are responsible for refreshing the state of security-related objects upon transaction rollbacks which occur after successful calls to the svySecurity API.

Param	Type	Description
mustSupportExternalTransactions	Boolean	The value for the supportExternalDBTransaction flag to set.

---

cloneTenant(tenantToClone, name, [makeSlave]) ⇒ Tenant

Creates and returns a new tenant with the specified name as a clone of the given tenant. The names of tenants must be unique in the system. The cloned tenant has the same roles and role permissions as the original. When makeSlave is true, the newly created clone will be a slave of the tenant to clone, inheriting all role / permission changes made to the master. WARNING: Cannot call this function when logged in as an user.

Returns: Tenant - The cloned tenant that is created. Throws an exception if this function is called when logged in as an user.

Param	Type	Description
tenantToClone	Tenant	The tenant to clone from
name	String	The name of the tenant. Must be unique and no longer than 50 characters.
[makeSlave]	Boolean	When true, the cloned tenant will be a slave of the tenant to clone (defaults to false).

---

consumeAccessToken(token) ⇒ User

Consumes a secure-access token and returns the user associated with the token if a valid match was found. Tokens may be used only once to identify a user. Subsequent calls to consume the same token will fail. Secure-access tokens are created with generateAccessToken

Returns: User - The user associated with the specified token or null if the token is not valid or has expired.

Note: An error will be thrown if this method is called from within an active user session.

Param	Type	Description
token	String	The secure-access token to use.

---

createTenant(name) ⇒ Tenant

Creates and returns a new tenant with the specified name. The names of tenants must be unique in the system.

Returns: Tenant - The tenant that is created.

Param	Type	Description
name	String	The name of the tenant. Must be unique and no longer than 50 characters.

---

deleteTenant(tenant) ⇒ Boolean

Immediately and permanently deletes the specified tenant and all records associated with it, including all users and roles. Tenant will not be deleted if it has users with active sessions. If the deleted tenant is a Master tenant and is a slave of another master tenant, this operation will replace the master tenant of it's direct slaves with the master of the tenant that is deleted; If the delated tenant is a Master tenant and has no Master tenant, this operation will remove the master from all it's direct slaves.

Returns: Boolean - False if tenant could not be deleted, most commonly because of active user sessions associated with the tenant.

Note: USE WITH CAUTION! There is no undo for this operation.

Param	Type	Description
tenant	Tenant | String	The tenant object or the name of the tenant to delete.

---

getActiveSessions() ⇒ [ 'Array' ].<Session>

Gets all active sessions for the application.

Returns: [ 'Array' ].<Session> - An array will all active sessions or an empty array if there are no active sessions.

Note: If users close the application without logging out then their sessions will remain active for a period of time.

---

getPermission(name) ⇒ Permission

Gets a permission by its unique permission name.

Returns: Permission - The specified permission or null if a permission with the specified name is not found.

Param	Type	Description
name	String	The name of the permission.

---

getPermissions() ⇒ [ 'Array' ].<Permission>

Gets all permissions available in this application.

Returns: [ 'Array' ].<Permission> - An array with all permissions or an empty array if no permissions are defined.

---

getRole(roleName, [tenantName]) ⇒ Role

Gets a role by the specified role name and tenant name. If tenant name is not specified will use the tenant of the user currently logged in the application, if available.

Returns: Role - The specified role or null if not found.

Note: Will fail if tenant is not specified and user is not logged in and multiple roles are found with the specified role name but associated with different tenants.

Param	Type	Description
roleName	String	The name of the role to get.
[tenantName]	String	If not specified will use the tenant of the current logged in user (if user is not currently logged in

---

getSession() ⇒ Session

Gets the current user session or null if no session initialized (no user is currently logged in).

Returns: Session - The current session or null if a user is not currently logged in.

Note: Sessions represent authenticated user sessions. They are not initialized until after user login.

---

getSessionCount() ⇒ Number

Gets the number of all unique sessions which have ever been initialized in the application. This includes both active sessions (for users currently logged in the application) and inactive sessions (sessions from the past which have already been closed).

Returns: Number - The number of all sessions (active and closed).

---

getTenant([name]) ⇒ Tenant

Gets a tenant by its unique tenant name. If tenant name is not specified then will return the tenant of the currently logged in user. If tenant name is not specified and no user is currently logged in then will return null.

Returns: Tenant - The tenant or null if not found / no user is logged in.

Param	Type	Description
[name]	String	The name of the tenant to get. Or null to get the current tenant.

Example

//get the tenant of the current user
var currentUserTenant = scopes.svySecurity.getTenant();
//get a specific tenant
var tenant = scopes.svySecurity.getTenant('tenantNameToGet');

---

getTenants() ⇒ [ 'Array' ].<Tenant>

Gets all tenants in the system.

Returns: [ 'Array' ].<Tenant> - An array with all tenants or an empty array if no tenants are defined.

---

getUser([userName], [tenantName]) ⇒ User

Gets a user by the specified username and tenant name. If username is not specified will return the user currently logged in the application, if available.

Returns: User - The specified user (or current user if parameters are not specified) or null if the specified user does not exist (or if parameters are not specified and a user is not logged in currently).

Note: Will fail if tenant is not specified and user is not logged in and multiple users are found with the specified username but associated with different tenants.

Param	Type	Description
[userName]	String	The username of the user to return. Can be null to get the current user.
[tenantName]	String	The name of the tenant associated with the user. Can be null if username is also null when getting the current user.

---

getUsers() ⇒ [ 'Array' ].<User>

Gets all users in the system.

Returns: [ 'Array' ].<User> - An array with all users or an empty array if no users are defined.

---

getVersion() ⇒ String

Gets the version of this module

Returns: String - the version of the module using the format Major.Minor.Revision

---

login(user, [userUid], [permissionsToApply]) ⇒ Boolean

Logs in the specified user and initializes a new Session for it. The login request will not be successful if the user account or the parent tenant account is locked and the lock has not expired yet. The login request will not be successful also if no permissions have been granted to the specified user. This method internally calls the standard Servoy security.login().

Returns: Boolean - Returns true if the login was successful and a user Session was created, otherwise false.

Note: This method does not perform any password checks - for validation of user passwords use User.checkPassword.

Param	Type	Description
user	User	The user to log in.
[userUid]	String | UUID	The uid to log the user in with (defaults to userName)
[permissionsToApply]	[ 'Array' ].<(String|Permission)>	Optional permissions to assign to the user. Note that these permissions cannot be asked for using User.getPermissions() or User.hasPermission().

---

logout()

Logs the current user out of the application and closes the associated Session. This method internally calls security.logout() to end the Servoy client session.

---

syncPermissions([forcePermissionRemoval])

Utility to sync permission records to the internal, design-time Servoy Security Groups. This should be called on solution import or on startup This action will create new permission records.

NOTE: This action will not delete permissions which have been removed from internal security. Design-time groups should never be renamed. They will be seen only as an ADD and will lose their tie to roles.

Param	Type	Description
[forcePermissionRemoval]	Boolean	if true then permissions without a matching Servoy security group will be deleted regardless if they have been granted to any role or not; if false (default) then permissions without a matching Servoy security group will be deleted only if they have not been granted to any role

---