Class Reference
IRIS for UNIX 2019.2
InterSystems: The power behind what matters   
Documentation  Search
  [%SYS] >  [Security] >  [Users]
Private  Storage   

persistent class Security.Users extends %Persistent, %XML.Adaptor, %SYSTEM.Help

Define the security User database, and methods which manipulate them.
The system includes a set of pre-defined System users.

User names have the following properties:
1) User names are not case sensitive.
2) Maximum length of a user name is 128 characters.
3) User name cannot contain "*" A user cannot have duplicate roles defined
At least one user must hold the %All role
All the roles granted to a user must exist in the roles database.

Note: The speed at which a single process can create several users at a time is limited by the PBKDF2 encryption method which hashes the password.

The table for this class should be manipulated only through object access, the published API's or through the System Management Portal. It should not be updated through direct SQL access.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
43 59 3 1 1


Summary

Properties
AccountNeverExpires Attributes AutheEnabled ChangePassword
Comment CreateDateTime CreateUsername EmailAddress
Enabled ExpirationDate Flags FullName
HOTPKey HOTPKeyDisplay HOTPKeyGenerate InvalidLoginAttempts
InvalidLoginDateTime InvalidLoginDevice InvalidLoginService InvalidLoginStatus
LastModifiedDateTime LastModifiedInfo LastModifiedUsername LoginDateTime
LoginDevice LoginService Name NameSpace
Password PasswordChangedDateTime PasswordExternal PasswordNeverExpires
PhoneNumber PhoneProvider Roles Routine
Salt SuperUser

Methods
%AddToSaveSet %AddToSyncSet %BMEBuilt %CheckConstraints
%CheckConstraintsForExtent %ClassIsLatestVersion %ClassName %ComposeOid
%ConstructClone %Delete %DeleteExtent %DeleteId
%DispatchClassMethod %DispatchGetModified %DispatchGetProperty %DispatchMethod
%DispatchSetModified %DispatchSetMultidimProperty %DispatchSetProperty %Exists
%ExistsId %Extends %GUID %GUIDSet
%GetLock %GetParameter %GetSwizzleObject %Id
%InsertBatch %IsA %IsModified %IsNull
%KillExtent %KillExtentData %LoadFromMemory %LockExtent
%LockId %New %NormalizeObject %ObjectIsNull
%ObjectModified %Oid %OnBeforeAddToSync %OnDetermineClass
%Open %OpenId %OriginalNamespace %PackageName
%PhysicalAddress %PurgeIndices %Reload %RemoveFromSaveSet
%ResolveConcurrencyConflict %RollBack %Save %SaveDirect
%SaveIndices %SerializeObject %SetModified %SortBegin
%SortEnd %SyncObjectIn %SyncTransport %UnlockExtent
%UnlockId %ValidateIndices %ValidateObject AddRoles
Copy Create Delete Exists
ExpireUserPasswords Export Get GetResourceSet
GetRoleSet Help Import Modify
UnExpireUserPasswords XMLDTD XMLExport XMLExportToStream
XMLExportToString XMLNew XMLSchema XMLSchemaNamespace
XMLSchemaType


Properties

• property AccountNeverExpires as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Account Expiration behavior.
0 - Account expires normally.
1 - Account will never expire.
• property Attributes as list of %Binary(MAXLEN="");
Attributes to apply to user when they log in.
• property AutheEnabled as %Integer [ InitialExpression = 0 ];
Two factor Authentication options which are enabled for this user.
Options are:
$$$AutheTwoFactorSMS - SMS Text authentication
$$$AutheTwoFactorPW - Time-based One-time Password
• property ChangePassword as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Change password on next login.
0 - Password change not required.
1 - Password change required before next login.
• property Comment as %String(MAXLEN=2048);
Comment.
• property CreateDateTime as %String [ InitialExpression = $zts ];
Account creation date and time.
$H format in utc.
• property CreateUsername as %String(MAXLEN=160) [ InitialExpression = $username ];
$username of user who created the account.
• property EmailAddress as %String(MAXLEN=512);
Email address of the user.
• property Enabled as Security.Datatype.BooleanYN [ InitialExpression = 1 ];
Allow user to log in.
0 - Disable login.
1 - Enable login.
• property ExpirationDate as %Date;
Last date an account can be used.
$H date value of when an account becomes disabled.
• property Flags as %Integer [ InitialExpression = 1 ];
Flags associated with user.
Bit 0 - User created via normal security mechanisms (InterSystems IRIS Password User).
Bit 1 - User created via LDAP.
Bit 2 - User created via Delegated Authentication.
• property FullName as %String(MAXLEN=2048);
Full name of the user.
• property HOTPKey as %Binary(MAXLEN=20,MINLEN=20) [ InitialExpression = $System.Encryption.GenCryptRand(20) ];
Time-based One-time Password key.
This property is automatically generated when the user is created using the $System.Encryption.GenCryptRand() method.
• property HOTPKeyDisplay as %Boolean [ InitialExpression = 0 ];
Display the Time-based One-time Password QR code or key on next login for the user to scan with their authentication device.
• property HOTPKeyGenerate as %Boolean [ InitialExpression = 0,Transient ];
0 - Do not generate a new Time-based One-time Password key when user is saved.
1 - Generate a new Time-based One-time Password key when user is saved.
• property InvalidLoginAttempts as %Integer(MINVAL=0,XMLPROJECTION="NONE") [ InitialExpression = 0 ];
Number of invalid login attempts since last successful one.
• property InvalidLoginDateTime as %String(XMLPROJECTION="NONE") [ InitialExpression = 0 ];
Last invalid login date and time
• property InvalidLoginDevice as %String(MAXLEN=256,XMLPROJECTION="NONE");
Last invalid login device
• property InvalidLoginService as %String(MAXLEN=64,XMLPROJECTION="NONE");
Last invalid login Service
• property InvalidLoginStatus as %Status(XMLPROJECTION="NONE") [ InitialExpression = $$$OK ];
Last login error
• property LastModifiedDateTime as %String [ InitialExpression = $zts ];
Account modified date and time.
$H format in utc.
• property LastModifiedInfo as %String(MAXLEN=1024);
Information describing last modification of the user.
• property LastModifiedUsername as %String(MAXLEN=128) [ InitialExpression = $username ];
$username of the person who last modified it.
• property LoginDateTime as %String(XMLPROJECTION="NONE") [ InitialExpression = 0 ];
Last Successful login date and time.
$H format in utc.
• property LoginDevice as %String(MAXLEN=256,XMLPROJECTION="NONE");
Last Successful login device
• property LoginService as %String(MAXLEN=64,XMLPROJECTION="NONE");
Last Successful login Service.
• property Name as %String(MAXLEN=160) [ Required ];
User Name.
Includes domain if multiple domains are enabled in the format username@domain.
• property NameSpace as %String(MAXLEN=64);
NameSpace to run in only if a terminal session.
• property Password as Security.Datatype.Password(MAXLEN=20);
PBKDF2 hashed password for InterSystems IRIS Authentication.
This is used with a salt function obtained from $System.Encryption.GenCryptRand. This property is set by the class when the PasswordExternal property is modified. Do not set this property directly.
To modify the password for a user using objects, get an instance of the object and modify the PasswordExternal property:
i '..Exists(Username,.User,.Status) q Status
s User.PasswordExternal=Password
s Status=User.%Save()
• property PasswordChangedDateTime as %String [ InitialExpression = $zts ];
Last password change date and time.
$H format in utc.
• property PasswordExternal as %String(MAXLEN=128,XMLPROJECTION="NONE") [ InitialExpression = $c(0),Transient ];
Clear text password.
This property is not stored in permanent storage. It is initially set to the value of $c(0). When it is modified, the Password property is updated to the PBKDF2 salted hashed value.
• property PasswordNeverExpires as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Password expires behavior.
0 - Password expires normally.
1 - Password never expires.
• property PhoneNumber as %String(MAXLEN=256);
Phone number for two-factor authentication
• property PhoneProvider as %String(MAXLEN=256);
Mobile phone service provider for two-factor authentication
• property Roles as list of %String(MAXLEN=64);
Roles assigned to the user.
• property Routine as %String(MAXLEN=64);
Routine to run only if terminal session, ""=Programmer mode.
• property Salt as %Binary(MAXLEN=8);
Salt value for Hashed password from $System.Encryption.GenCryptRand.
• property SuperUser as Security.Datatype.BooleanYN(XMLPROJECTION="NONE") [ InitialExpression = 0,ReadOnly ];
User holds the %All role.

Methods

• classmethod AddRoles(Username As %String, ByRef Roles As %String, Admin As %Boolean = 0) as %Status
Add role(s) to the User's definition.
Parameters:
Username - Name of the user to add roles to
Roles - Comma delimited list of roles
Admin - SQL ADMIN OPTION, TRUE if this user can GRANT the Role to another user/role. Only applicable in SQL.
• classmethod Copy(Name As %String, NewName As %String, NewFullName As %String = "", SQLSysPrivs As %Boolean = 1, SQLObjPrivs As %Boolean = 1) as %Status
Copy a User.
Copy an existing User in the Security database to a new one.
Parameters:
Name - Name of the User to be copied.
NewName - Name of the user to be created.
NewFullName - Full name of the new user.
SQLSysPrivs - Copy SQL system privileges.
SQLObjPrivs - Copy SQL object provileges.
• classmethod Create(Username As %String, UserRoles As %String, Password As %String, FullName As %String, NameSpace As %String, Routine As %String, ExpirationDate As %String, ChangePassword As %Boolean, Enabled As %Boolean, Comment As %String, Flags As %String = 1, PhoneNumber As %String, PhoneProvider As %String, ByRef Attributes As %String, AccountNeverExpires As %Boolean, PasswordNeverExpires As %Boolean) as %Status
Create a User.
Create a User in the Security database.
There are 2 ways to call this method and pass the parameters:

s x=##Class(Security.Users).Create(User,Roles,Password,FullName,...)
or
s x=##Class(Security.Users).Create(User,.Properties)

Where Properties are contained in an array subscripted by property name, passed by reference. See the Get() method for a description of the Properies array. Valid properties for the Create() method are described below, other values are ignored.
Parameters:
Name - Name of the user to create
UserRoles - List format of roles to assign to the user
Roles are in the format:
"Role1,Role2" For example:
s Roles="%Developer,%Operator"
s Roles="" would create a user with no roles
Password - InterSystems IRIS Authentication password for the user in clear text.
Create() will set it into PasswordExternal which will set Password to the hashed value.
FullName - Full name of the user
NameSpace - Namespace of the user for terminal access
Routine - Routine the user runs for terminal access. Routine="" means programmer mode.
ExpirationDate - ODBC date format of when the user account expires, or ""=no expiration
ChangePassword - 0/1, User cannot log in until the password is changed
Enabled - 0/1, account is disabled/enabled
Comment - Comment
Flags - Internal use only, pass 1 for this
Bit 0 - User created normally for InterSystems IRIS Authentication
Bit 1 - User created by LDAP authentication
Bit 2 - User created by User Defined authentication
PhoneNumber - Phone number for two-factor authentication PhoneProvider - Mobile phone service provider for two-factor authentication EmailAddress - Email address of the user.
HOTPKey - HOTP key used for Display Time-Based One-time Password
HOTPKeyDisplay - 0/1 - Display QR Code and key on next login
Attributes (byref) - Array of attributes to be associated with the user
Attribute(Name)=Value
AccountNeverExpires - 0/1, Account will never expire
PasswordNeverExpires - 0/1, Password will never expire
• classmethod Delete(Username As %String) as %Status
Delete a User.
This method will delete a User from the security database.
Parameters:
Username - Username to delete
• classmethod Exists(Username As %String, ByRef User As %ObjectHandle, ByRef Status As %Status, Flag As %Integer = 0) as %Boolean
User exists.
This method checks for the existence of a user in the security database.
Parameters:
Username - Name of the user to check existence of
Flag - Internal use only, must be 0 or not passed
Requires the %Admin_Secure:USE privilege to change the $USERNAME value.
Return values:
If Value of the method = 0 (User does not exist, or some error occured)
User = Null
Status = User "x" does not exist, or other error message

If Value of the method = 1 (User exists)
User = Object handle to user
ActualUserName = exact-case of user's name (used by SQL) Status = User "x" already exists
• classmethod ExpireUserPasswords(Names As %String, ByRef Count As %Integer) as %Status
Set selected users accounts as having to change their password on next login.
This does not affect LDAP or Delegated authentication accounts. It also does not affect users who have the PasswordNeverExpires flag set.
Parameters:
Names - Comma separated list of user names, "*" = All
Count - Return value of number of users expired.
This method requires %Admin_Secure:USE permission to run.
• classmethod Export(FileName As %String = "UsersExport.xml", ByRef NumExported As %Integer = 0, Usernames As %String = "*", Roles As %String = "*", SQLPrivileges As %Boolean = 0, ByRef NumSQLPrivilegesExported As %Integer) as %Status
This method exports User records to a file in xml format.
Parameters:
Filename - Output file name
NumExported (byref) - Returns number of records exported.
Usernames - Comma separated list of Usernames to export, "*" = All
Roles - Comma separated list of Roles, "*" = All. Export Users containing only these roles
SQLPrivileges - 1/0 flag. If 1, export all SQL Privileges from all namespace on this system that have been directly granted to this Role
NumSQLPrivilegesExported *byref) - Returns number of SQL Privileges and SQL Admin Privilege Set records exported
• classmethod Get(Username As %String, ByRef Properties As %String) as %Status
Get a User's properties.
Gets a User's properties from the security database.
Parameters:
Username - Name of the user to get
Return values:
Properties - Array of properties
Properties("AccountNeverExpires") - 0=Expires normally, 1=Never expires
Properties("Attributes",Name) = $lb(Value1,Value2) - Attributes and values to associate with process
Properties("ChangePassword") - 0=Don't change, 1=Change before next login Properties("Comment") - Comment
Properties("EmailAddress") - Email Address
Properties("Enabled") - 0=Disabled, 1=Enabled
Properties("ExpirationDate") - Expiration date of account, ODBC date format
Properties("Flags") - Flags of the user
Properties("FullName") - Full name of the user
Properties("InvalidLoginAttempts") - Number of invalid login attempts since last success
Properties("InvalidLoginDateTime") - $h value of last invalid login attempt
Properties("InvalidLoginDevice") - Last device for invalid login attempt
Properties("InvalidLoginStatus") - Last error status for an invalid login attempt
Properties("InvalidLoginService") - Last service used for an invalid login attempt
Properties("LegacyPassword") - Legacy password for Cache Direct
Properties("LoginDateTime") - $h value for last valid login attempt
Properties("LoginDevice") - Last valid login device
Properties("LoginService") - Last valid login service
Properties("NameSpace") - Default Namespace for terminal login
Properties("Password") - InterSystems IRIS Authentication password hashed value
properties("PasswordNeverExpires") - 0=Expires normally, 1=Never expires
Properties("PhoneNumber") - Phone number for two-factor authentication
Properties("PhoneProvider") - Mobile phone service provider for two-factor authentication
Properties("Roles")- Comma-separated List format of roles
Roles are in the format:
"Role1,Role2"
For example:
s Properties("Roles")="%Developer,%Operator"
Properties("Routine") - Routine the user runs for terminal access. Routine="" means programmer mode.
Properties("Salt") - Salt used to generate password.
Properties("SuperUser") - 0=No, 1=Yes.
• classmethod GetResourceSet(Username As %String = "", Roles As %String = "", ByRef Resources As %String) as %Status
Get a User's or Roles set of resources.
Gets a User's set of resource/permission pairs he would be granted if logged in.
Parameters:
Username - Name of the user to get
Roles - Comma delimited list of roles to return resources for
Resources - Comma delimited list of resource:permission pairs
• classmethod GetRoleSet(Username As %String, ByRef Roles As %String) as %Status
Get a User's set of roles.
Gets a User's set of roles he would be granted if logged in.
Parameters:
Username - Name of the user to get
Return value:
Roles - Comma delimited list of roles a user would be granted if logged in
• classmethod Import(FileName As %String = "UsersExport.xml", ByRef NumImported As %Integer, Flags As %Integer = 0, ByRef NumSQLPrivsImported As %Integer) as %Status
Import User records from an xml file.
Parameters:
FileName - Filename to import User records from
NumImported (byref) - Returns number of records imported
Flags - Control import
Bit 0 - Do not import records, just return count
Note: On failure, no records will be imported
• classmethod Modify(Username As %String, ByRef Properties As %String) as %Status
Modify a User's properties.
Modifies a User's properties from the security database.
Parameters:
Username - Name of the user to modify
Properties - Array of properties to modify.
See the Get() method for a description of the Properties parameter.
If a specific property is not passed in the properties array, the value is not modified.
If a value is unchanged it is not set to prevent the property modified state from being set.
Note that if a new password is passed in, then the hashed value of the password will be returned in the properties array.
• classmethod UnExpireUserPasswords(Names As %String, ByRef Count As %Integer) as %Status
Set selected users accounts to not have their password change on next login.
This does not affect LDAP or Delegated authentication accounts. Parameters:
Names - Comma separated list of user names, "*" = All
Count - Return value of number of users updated.
This method requires %Admin_Secure:USE permission to run.

Queries

• query Detail(Names As %String, Roles As %String, LastLoginOlderThan As %Integer, Flag As %Integer = 0)
Selects Name As %String, FullName As %String, Comment As %String, Enabled As %String, ExpirationDate As %String, Roles As %String, GrantedRoles As %String, Namespace As %String, Routine As %String, LastPasswordChangeTime As %String, LastLoginTime As %String, LastLoginService As %String, LastLoginDevice As %String, LastInvalidLoginTime As %String, LastLoginError As %String, InvalidLoginAttempts As %String, LastInvalidLoginService As %String, LastInvalidLoginDevice As %String, Type As %String, EmailAddress As %String, PhoneNumber As %String, PhoneProvider As %String, AccountNeverExpires As %String, PasswordNeverExpires As %String, AutheEnabled As %String, CreateDateTime As %String, CreateUsername As %String, LastModifiedDateTime As %String, LastModifiedUsername As %String, LastModifiedInfo As %String, Flags As %Integer
List all user records, brief display.
Names - Comma separated list of user names, "*" = All
Roles - Comma separated list of Role names, "*"=ALL
LastLoginOlderThan - Select users who haven't logged in in more than x days, "*"=ALL Flag - 0 - Use "Startswith" as the selection on the name.
Flag - 1 - Use "Contains" as the selection on the name.
Note: This query may change in future versions
• query List(Names As %String, Roles As %String, LastLoginOlderThan As %Integer, Flag As %Integer = 0)
Selects Name As %String, Enabled As %String, Roles As %String, LastLoginTime As %String, Flags As %Integer
List all user records, brief display.
Names - Comma separated list of user names, "*" = All
Roles - Comma separated list of Role names, "*"=ALL
LastLoginOlderThan - Select users who haven't logged in in more than x days, "*"=ALL Flag - 0 - Use "Startswith" as the selection on the name.
Flag - 1 - Use "Contains" as the selection on the name.
Note: This query may change in future versions

Indices

•index (NameLowerCaseIndex on NameLowerCase) [IdKey];

Triggers

•trigger BDTrigger (BEFORE event DELETE)
Before Delete trigger, call %OnDelete method and if error, don't allow the DELETE


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.