Security.Users
persistent class Security.Users extends %Library.Persistent, %XML.Adaptor, %SYSTEM.Help
SQL Table Name: Security.Users
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 160 characters.
3) User name cannot contain "*"
All defined users have the following properties:
1) A user cannot have duplicate roles defined
2) At least one user must hold the %All role
3) 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.
Property Inventory
- 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
- PasswordHash
- PasswordHashAlgorithm
- PasswordHashWorkFactor
- PasswordNeverExpires
- PhoneNumber
- PhoneProvider
- Roles
- RolesAreAdmin
- Routine
- Salt
- SuperUser
Method Inventory
- AddRoles()
- Copy()
- Create()
- Delete()
- Exists()
- ExpireUserPasswords()
- Export()
- Get()
- GetResourceSet()
- GetRoleSet()
- Import()
- Modify()
- RemoveRoles()
- UnExpireUserPasswords()
Properties
property AccountNeverExpires as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Account Expiration behavior.
0 - Account expires normally.
1 - Account will never expire.
0 - Account expires normally.
1 - Account will never expire.
Property methods: AccountNeverExpiresDisplayToLogical(), AccountNeverExpiresGet(), AccountNeverExpiresGetStored(), AccountNeverExpiresIsValid(), AccountNeverExpiresLogicalToDisplay(), AccountNeverExpiresLogicalToOdbc(), AccountNeverExpiresLogicalToXSD(), AccountNeverExpiresNormalize(), AccountNeverExpiresOdbcToLogical(), AccountNeverExpiresSet(), AccountNeverExpiresXSDToLogical()
property Attributes as list of %Binary);
Attributes to apply to user when they log in.
Property methods: AttributesBuildValueArray(), AttributesCollectionToDisplay(), AttributesCollectionToOdbc(), AttributesDisplayToCollection(), AttributesGet(), AttributesGetObject(), AttributesGetObjectId(), AttributesGetStored(), AttributesGetSwizzled(), AttributesIsValid(), AttributesLogicalToXSD(), AttributesOdbcToCollection(), AttributesSet(), AttributesSetObject(), AttributesSetObjectId(), AttributesXSDToLogical()
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
Options are:
$$$AutheTwoFactorSMS - SMS Text authentication
$$$AutheTwoFactorPW - Time-based One-time Password
Property methods: AutheEnabledDisplayToLogical(), AutheEnabledGet(), AutheEnabledGetStored(), AutheEnabledIsValid(), AutheEnabledLogicalToDisplay(), AutheEnabledNormalize(), AutheEnabledSet(), AutheEnabledXSDToLogical()
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.
0 - Password change not required.
1 - Password change required before next login.
Property methods: ChangePasswordDisplayToLogical(), ChangePasswordGet(), ChangePasswordGetStored(), ChangePasswordIsValid(), ChangePasswordLogicalToDisplay(), ChangePasswordLogicalToOdbc(), ChangePasswordLogicalToXSD(), ChangePasswordNormalize(), ChangePasswordOdbcToLogical(), ChangePasswordSet(), ChangePasswordXSDToLogical()
property Comment as %String (MAXLEN = 2048);
Comment.
Property methods: CommentDisplayToLogical(), CommentGet(), CommentGetStored(), CommentIsValid(), CommentLogicalToDisplay(), CommentLogicalToOdbc(), CommentNormalize(), CommentSet()
property CreateDateTime as %String [ InitialExpression = $zts ];
Account creation date and time.
$H format in utc.
$H format in utc.
Property methods: CreateDateTimeDisplayToLogical(), CreateDateTimeGet(), CreateDateTimeGetStored(), CreateDateTimeIsValid(), CreateDateTimeLogicalToDisplay(), CreateDateTimeLogicalToOdbc(), CreateDateTimeNormalize(), CreateDateTimeSet()
property CreateUsername as %Library.Username [ InitialExpression = $username ];
$username of user who created the account.
Property methods: CreateUsernameDisplayToLogical(), CreateUsernameGet(), CreateUsernameGetStored(), CreateUsernameIsValid(), CreateUsernameLogicalToDisplay(), CreateUsernameLogicalToOdbc(), CreateUsernameNormalize(), CreateUsernameSet()
property EmailAddress as %String (MAXLEN = 512);
Email address of the user.
Property methods: EmailAddressDisplayToLogical(), EmailAddressGet(), EmailAddressGetStored(), EmailAddressIsValid(), EmailAddressLogicalToDisplay(), EmailAddressLogicalToOdbc(), EmailAddressNormalize(), EmailAddressSet()
property Enabled as Security.Datatype.BooleanYN [ InitialExpression = 1 ];
Allow user to log in.
0 - Disable login.
1 - Enable login.
0 - Disable login.
1 - Enable login.
Property methods: EnabledDisplayToLogical(), EnabledGet(), EnabledGetStored(), EnabledIsValid(), EnabledLogicalToDisplay(), EnabledLogicalToOdbc(), EnabledLogicalToXSD(), EnabledNormalize(), EnabledOdbcToLogical(), EnabledSet(), EnabledXSDToLogical()
property ExpirationDate as %Date;
Last date an account can be used.
$H date value of when an account becomes disabled.
$H date value of when an account becomes disabled.
Property methods: ExpirationDateDisplayToLogical(), ExpirationDateGet(), ExpirationDateGetStored(), ExpirationDateIsValid(), ExpirationDateLogicalToDisplay(), ExpirationDateLogicalToOdbc(), ExpirationDateLogicalToXSD(), ExpirationDateNormalize(), ExpirationDateOdbcToLogical(), ExpirationDateSet()
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.
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 methods: FlagsDisplayToLogical(), FlagsGet(), FlagsGetStored(), FlagsIsValid(), FlagsLogicalToDisplay(), FlagsNormalize(), FlagsSet(), FlagsXSDToLogical()
property FullName as %String (MAXLEN = 2048);
Full name of the user.
Property methods: FullNameDisplayToLogical(), FullNameGet(), FullNameGetStored(), FullNameIsValid(), FullNameLogicalToDisplay(), FullNameLogicalToOdbc(), FullNameNormalize(), FullNameSet()
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.
This property is automatically generated when the user is created using the $System.Encryption.GenCryptRand() method.
Property methods: HOTPKeyGet(), HOTPKeyGetStored(), HOTPKeyIsValid(), HOTPKeyLogicalToXSD(), HOTPKeySet(), HOTPKeyXSDToLogical()
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 methods: HOTPKeyDisplayDisplayToLogical(), HOTPKeyDisplayGet(), HOTPKeyDisplayGetStored(), HOTPKeyDisplayIsValid(), HOTPKeyDisplayLogicalToDisplay(), HOTPKeyDisplayLogicalToXSD(), HOTPKeyDisplayNormalize(), HOTPKeyDisplaySet(), HOTPKeyDisplayXSDToLogical()
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.
1 - Generate a new Time-based One-time Password key when user is saved.
Property methods: HOTPKeyGenerateDisplayToLogical(), HOTPKeyGenerateGet(), HOTPKeyGenerateIsValid(), HOTPKeyGenerateLogicalToDisplay(), HOTPKeyGenerateLogicalToXSD(), HOTPKeyGenerateNormalize(), HOTPKeyGenerateSet(), HOTPKeyGenerateXSDToLogical()
property InvalidLoginAttempts as %Integer (MINVAL = 0, XMLPROJECTION = "NONE") [ InitialExpression = 0 ];
Number of invalid login attempts since last successful one.
Property methods: InvalidLoginAttemptsDisplayToLogical(), InvalidLoginAttemptsGet(), InvalidLoginAttemptsGetStored(), InvalidLoginAttemptsIsValid(), InvalidLoginAttemptsLogicalToDisplay(), InvalidLoginAttemptsNormalize(), InvalidLoginAttemptsSet(), InvalidLoginAttemptsXSDToLogical()
property InvalidLoginDateTime as %String (XMLPROJECTION = "NONE") [ InitialExpression = 0 ];
Last invalid login date and time
Property methods: InvalidLoginDateTimeDisplayToLogical(), InvalidLoginDateTimeGet(), InvalidLoginDateTimeGetStored(), InvalidLoginDateTimeIsValid(), InvalidLoginDateTimeLogicalToDisplay(), InvalidLoginDateTimeLogicalToOdbc(), InvalidLoginDateTimeNormalize(), InvalidLoginDateTimeSet()
property InvalidLoginDevice as %String (MAXLEN = 256, XMLPROJECTION = "NONE");
Last invalid login device
Property methods: InvalidLoginDeviceDisplayToLogical(), InvalidLoginDeviceGet(), InvalidLoginDeviceGetStored(), InvalidLoginDeviceIsValid(), InvalidLoginDeviceLogicalToDisplay(), InvalidLoginDeviceLogicalToOdbc(), InvalidLoginDeviceNormalize(), InvalidLoginDeviceSet()
property InvalidLoginService as %String (MAXLEN = 64, XMLPROJECTION = "NONE");
Last invalid login Service
Property methods: InvalidLoginServiceDisplayToLogical(), InvalidLoginServiceGet(), InvalidLoginServiceGetStored(), InvalidLoginServiceIsValid(), InvalidLoginServiceLogicalToDisplay(), InvalidLoginServiceLogicalToOdbc(), InvalidLoginServiceNormalize(), InvalidLoginServiceSet()
property InvalidLoginStatus as %Status (XMLPROJECTION = "NONE") [ InitialExpression = $$$OK ];
Last login error
Property methods: InvalidLoginStatusGet(), InvalidLoginStatusGetStored(), InvalidLoginStatusIsValid(), InvalidLoginStatusLogicalToOdbc(), InvalidLoginStatusLogicalToXSD(), InvalidLoginStatusSet(), InvalidLoginStatusXSDToLogical()
property LastModifiedDateTime as %String [ InitialExpression = $zts ];
Account modified date and time.
$H format in utc.
$H format in utc.
Property methods: LastModifiedDateTimeDisplayToLogical(), LastModifiedDateTimeGet(), LastModifiedDateTimeGetStored(), LastModifiedDateTimeIsValid(), LastModifiedDateTimeLogicalToDisplay(), LastModifiedDateTimeLogicalToOdbc(), LastModifiedDateTimeNormalize(), LastModifiedDateTimeSet()
property LastModifiedInfo as %String (MAXLEN = 1024);
Information describing last modification of the user.
Property methods: LastModifiedInfoDisplayToLogical(), LastModifiedInfoGet(), LastModifiedInfoGetStored(), LastModifiedInfoIsValid(), LastModifiedInfoLogicalToDisplay(), LastModifiedInfoLogicalToOdbc(), LastModifiedInfoNormalize(), LastModifiedInfoSet()
property LastModifiedUsername as %Library.Username [ InitialExpression = $username ];
$username of the person who last modified it.
Property methods: LastModifiedUsernameDisplayToLogical(), LastModifiedUsernameGet(), LastModifiedUsernameGetStored(), LastModifiedUsernameIsValid(), LastModifiedUsernameLogicalToDisplay(), LastModifiedUsernameLogicalToOdbc(), LastModifiedUsernameNormalize(), LastModifiedUsernameSet()
property LoginDateTime as %String (XMLPROJECTION = "NONE") [ InitialExpression = 0 ];
Last Successful login date and time.
$H format in utc.
$H format in utc.
Property methods: LoginDateTimeDisplayToLogical(), LoginDateTimeGet(), LoginDateTimeGetStored(), LoginDateTimeIsValid(), LoginDateTimeLogicalToDisplay(), LoginDateTimeLogicalToOdbc(), LoginDateTimeNormalize(), LoginDateTimeSet()
property LoginDevice as %String (MAXLEN = 256, XMLPROJECTION = "NONE");
Last Successful login device
Property methods: LoginDeviceDisplayToLogical(), LoginDeviceGet(), LoginDeviceGetStored(), LoginDeviceIsValid(), LoginDeviceLogicalToDisplay(), LoginDeviceLogicalToOdbc(), LoginDeviceNormalize(), LoginDeviceSet()
property LoginService as %String (MAXLEN = 64, XMLPROJECTION = "NONE");
Last Successful login Service.
Property methods: LoginServiceDisplayToLogical(), LoginServiceGet(), LoginServiceGetStored(), LoginServiceIsValid(), LoginServiceLogicalToDisplay(), LoginServiceLogicalToOdbc(), LoginServiceNormalize(), LoginServiceSet()
property Name as %Library.Username [ Required ];
User Name.
Includes domain if multiple domains are enabled in the format username@domain.
Includes domain if multiple domains are enabled in the format username@domain.
Property methods: NameDisplayToLogical(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()
property NameSpace as %String (MAXLEN = 64);
NameSpace to run in only if a terminal session.
Property methods: NameSpaceDisplayToLogical(), NameSpaceGet(), NameSpaceGetStored(), NameSpaceIsValid(), NameSpaceLogicalToDisplay(), NameSpaceLogicalToOdbc(), NameSpaceNormalize(), NameSpaceSet()
property Password as Security.Datatype.Password (MAXLEN = 64);
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()
When using the Modify() class method to change a user's password, you can either set Properties("Password")=NewPassword, or Properties("ExternalPassword")=NewPassword.
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()
When using the Modify() class method to change a user's password, you can either set Properties("Password")=NewPassword, or Properties("ExternalPassword")=NewPassword.
Property methods: PasswordGet(), PasswordGetStored(), PasswordIsValid(), PasswordLogicalToDisplay(), PasswordLogicalToOdbc(), PasswordLogicalToXSD(), PasswordXSDToLogical()
property PasswordChangedDateTime as %String [ InitialExpression = $zts ];
Last password change date and time.
$H format in utc.
$H format in utc.
Property methods: PasswordChangedDateTimeDisplayToLogical(), PasswordChangedDateTimeGet(), PasswordChangedDateTimeGetStored(), PasswordChangedDateTimeIsValid(), PasswordChangedDateTimeLogicalToDisplay(), PasswordChangedDateTimeLogicalToOdbc(), PasswordChangedDateTimeNormalize(), PasswordChangedDateTimeSet()
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.
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 methods: PasswordExternalDisplayToLogical(), PasswordExternalGet(), PasswordExternalIsValid(), PasswordExternalLogicalToDisplay(), PasswordExternalLogicalToOdbc(), PasswordExternalNormalize()
property PasswordHash as %String (MAXLEN = 10000) [ Transient ];
Used to securely set user password using a cryptographic hash. This is used
by declarative user creation via CPF. For full definition, see property PasswordHash
in class Config.Startup.
Property methods: PasswordHashDisplayToLogical(), PasswordHashGet(), PasswordHashIsValid(), PasswordHashLogicalToDisplay(), PasswordHashLogicalToOdbc(), PasswordHashNormalize(), PasswordHashSet()
property PasswordHashAlgorithm as Security.Datatype.PBKDF2Alg [ Required ];
Algorithm used to calculate user's current PBKDF2 password hash.
Irrelevant for users without passwords.
Property methods: PasswordHashAlgorithmDisplayToLogical(), PasswordHashAlgorithmGet(), PasswordHashAlgorithmGetStored(), PasswordHashAlgorithmIsValid(), PasswordHashAlgorithmLogicalToBitLength(), PasswordHashAlgorithmLogicalToDisplay(), PasswordHashAlgorithmLogicalToOdbc(), PasswordHashAlgorithmNormalize(), PasswordHashAlgorithmSet()
property PasswordHashWorkFactor as %Integer (MINVAL = 1024) [ Required ];
Work Factor used to calculate user's current PBKDF2 password hash.
Irrelevant for users without passwords.
Property methods: PasswordHashWorkFactorDisplayToLogical(), PasswordHashWorkFactorGet(), PasswordHashWorkFactorGetStored(), PasswordHashWorkFactorIsValid(), PasswordHashWorkFactorLogicalToDisplay(), PasswordHashWorkFactorNormalize(), PasswordHashWorkFactorSet(), PasswordHashWorkFactorXSDToLogical()
property PasswordNeverExpires as Security.Datatype.BooleanYN [ InitialExpression = 0 ];
Password expires behavior.
0 - Password expires normally.
1 - Password never expires.
0 - Password expires normally.
1 - Password never expires.
Property methods: PasswordNeverExpiresDisplayToLogical(), PasswordNeverExpiresGet(), PasswordNeverExpiresGetStored(), PasswordNeverExpiresIsValid(), PasswordNeverExpiresLogicalToDisplay(), PasswordNeverExpiresLogicalToOdbc(), PasswordNeverExpiresLogicalToXSD(), PasswordNeverExpiresNormalize(), PasswordNeverExpiresOdbcToLogical(), PasswordNeverExpiresSet(), PasswordNeverExpiresXSDToLogical()
property PhoneNumber as %String (MAXLEN = 256);
Phone number for two-factor authentication
Property methods: PhoneNumberDisplayToLogical(), PhoneNumberGet(), PhoneNumberGetStored(), PhoneNumberIsValid(), PhoneNumberLogicalToDisplay(), PhoneNumberLogicalToOdbc(), PhoneNumberNormalize(), PhoneNumberSet()
property PhoneProvider as %String (MAXLEN = 256);
Mobile phone service provider for two-factor authentication
Property methods: PhoneProviderDisplayToLogical(), PhoneProviderGet(), PhoneProviderGetStored(), PhoneProviderIsValid(), PhoneProviderLogicalToDisplay(), PhoneProviderLogicalToOdbc(), PhoneProviderNormalize(), PhoneProviderSet()
property Roles as list of %String (MAXLEN = 64);
Roles assigned to the user.
Property methods: RolesBuildValueArray(), RolesCollectionToDisplay(), RolesCollectionToOdbc(), RolesDisplayToCollection(), RolesDisplayToLogical(), RolesGet(), RolesGetObject(), RolesGetObjectId(), RolesGetStored(), RolesGetSwizzled(), RolesIsValid(), RolesLogicalToDisplay(), RolesLogicalToOdbc(), RolesNormalize(), RolesOdbcToCollection(), RolesSet(), RolesSetObject(), RolesSetObjectId()
property RolesAreAdmin as %Boolean [ InitialExpression = 0 , Transient ];
When adding a role to the user during Create, allows the user to be able
to GRANT the role to another user. Only applicable in SQL.
0 - Don't allow grant (default)
1 - Allow grant
0 - Don't allow grant (default)
1 - Allow grant
Property methods: RolesAreAdminDisplayToLogical(), RolesAreAdminGet(), RolesAreAdminIsValid(), RolesAreAdminLogicalToDisplay(), RolesAreAdminLogicalToXSD(), RolesAreAdminNormalize(), RolesAreAdminSet(), RolesAreAdminXSDToLogical()
property Routine as %String (MAXLEN = 64);
Routine to run only if terminal session, ""=Programmer mode.
Property methods: RoutineDisplayToLogical(), RoutineGet(), RoutineGetStored(), RoutineIsValid(), RoutineLogicalToDisplay(), RoutineLogicalToOdbc(), RoutineNormalize(), RoutineSet()
property Salt as %Binary (MAXLEN = 64);
Salt value for Hashed password from $System.Encryption.GenCryptRand.
Property methods: SaltGet(), SaltGetStored(), SaltIsValid(), SaltLogicalToXSD(), SaltSet(), SaltXSDToLogical()
property SuperUser as Security.Datatype.BooleanYN (XMLPROJECTION = "NONE") [ InitialExpression = 0 , ReadOnly ];
User holds the %All role.
Property methods: SuperUserDisplayToLogical(), SuperUserGet(), SuperUserGetStored(), SuperUserIsValid(), SuperUserLogicalToDisplay(), SuperUserLogicalToOdbc(), SuperUserLogicalToXSD(), SuperUserNormalize(), SuperUserOdbcToLogical(), SuperUserXSDToLogical()
Methods
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.
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.
If you add the user to the %All role, the SuperUser property is set to 1.
classmethod Copy(Name As %String, NewName As %String, NewFullName As %String = "", SQLSysPrivs As %Boolean = 1, SQLObjPrivs As %Boolean = 1, NewPassword As %String = "") 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 privileges.
NewPassword - Password for the newly reated 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 privileges.
NewPassword - Password for the newly reated user.
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, PasswordHashAlgorithm As %String, PasswordHashWorkFactor As %Integer) 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 Properties 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
RolesAreAdmin - 0/1 Roles are created with GRANT privilege
Password - InterSystems IRIS Authentication password for the user in clear text.
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
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 Properties 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
RolesAreAdmin - 0/1 Roles are created with GRANT privilege
Password - InterSystems IRIS Authentication password for the user in clear text.
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
Delete a User.
This method will delete a User from the security database.
Parameters:
Username - Username to delete
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
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
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.
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
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
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("PasswordHashAlgorithm") - SHA algorithm used in PBKDF2 password hash
properties("PasswordHashWorkFactor") - Number of iterations used in PBKDF2 password hash
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.
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("PasswordHashAlgorithm") - SHA algorithm used in PBKDF2 password hash
properties("PasswordHashWorkFactor") - Number of iterations used in PBKDF2 password hash
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
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
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
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
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
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.
To change a user's password, you can either set Properties("Password")=NewPassword, or Properties("ExternalPassword")=NewPassword.
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.
To change a user's password, you can either set Properties("Password")=NewPassword, or Properties("ExternalPassword")=NewPassword.
If a specific property is not passed in the properties array, the value is not modified, except that if you add the user to the %All role, the SuperUser property is set to 1 and if you remove the user from the %All role, the SuperUser property is set to 0.
If a value is unchanged, it is not set to prevent the property modified state from being set.
Remove role(s) from the User's definition.
Parameters:
Username - Name of the user to remove roles from
Roles - Comma delimited list of roles.
Parameters:
Username - Name of the user to remove roles from
Roles - Comma delimited list of roles.
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.
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, PasswordHashAlgorithm As %String, PasswordHashWorkFactor 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
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
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
Indexes
index (NameLowerCaseIndex on NameLowerCase) [IdKey, Type = key];
Index methods: NameLowerCaseIndexCheck(), NameLowerCaseIndexDelete(), NameLowerCaseIndexExists(), NameLowerCaseIndexOpen(), NameLowerCaseIndexSQLCheckUnique(), NameLowerCaseIndexSQLExists(), NameLowerCaseIndexSQLFindPKeyByConstraint(), NameLowerCaseIndexSQLFindRowIDByConstraint()
Triggers
trigger BDTrigger (BEFORE event DELETE);
Before Delete trigger, call %OnDelete method and if error, don't allow the DELETE
trigger NoSQL (BEFORE event INSERT/UPDATE/DELETE);
Inherited Members
Inherited Methods
- %%CLASSNAMELogicalToStorage()
- %%CLASSNAMEStorageToLogical()
- %AddToSaveSet()
- %AddToSyncSet()
- %BMEBuilt()
- %BuildIndicesAsync()
- %BuildIndicesAsyncResponse()
- %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()
- %OnDeleteFinally()
- %OnDetermineClass()
- %OnOpenFinally()
- %OnSaveFinally()
- %Open()
- %OpenId()
- %OriginalNamespace()
- %PackageName()
- %PhysicalAddress()
- %PurgeIndices()
- %Reload()
- %RemoveFromSaveSet()
- %ResolveConcurrencyConflict()
- %RollBack()
- %Save()
- %SaveDirect()
- %SaveIndices()
- %SerializeObject()
- %SetModified()
- %SortBegin()
- %SortEnd()
- %SyncObjectIn()
- %SyncTransport()
- %UnlockExtent()
- %UnlockId()
- %ValidateIndices()
- %ValidateObject()
- %ValidateTable()
- Help()
- XMLDTD()
- XMLExport()
- XMLExportToStream()
- XMLExportToString()
- XMLNew()
- XMLSchema()
- XMLSchemaNamespace()
- XMLSchemaType()
Storage
Storage Model: Storage (Security.Users)
^|$$$SecurityMapUsers|SYS("Security","UsersD")(ID) |
= | %%CLASSNAME
ChangePassword
Comment
Enabled
EventFlags
ExpirationDate
FullName
InvalidLoginAttempts
InvalidLoginDateTime
InvalidLoginDevice
InvalidLoginService
InvalidLoginStatus
LegacyPassword
LoginDateTime
LoginDevice
LoginService
Name
NameSpace
Password
PasswordChangedDateTime
Roles
Routine
SuperUser
Salt
Flags
Attributes
PhoneNumber
PhoneProvider
AccountNeverExpires
PasswordNeverExpires
EMSGroupEnabled
AutheEnabled
CreateDateTime
CreateUsername
LastModifiedDateTime
LastModifiedInfo
LastModifiedUsername
HOTPKey
HOTPKeyDisplay
EmailAddress
TOTPLastValidPasswords
PasswordHashAlgorithm
PasswordHashWorkFactor
Version
|