Define the security User database, and methods which manipulate them. More...

Inheritance diagram for Users:

[legend]

Collaboration diagram for Users:

[legend]

Static Public Member Functions
_.Library.Status	AddRoles (_.Library.String Username, _.Library.String Roles, _.Library.Boolean Admin)
	Add role(s) to the User's definition. More...

_.Library.Status	Copy (_.Library.String Name, _.Library.String NewName, _.Library.String NewFullName, _.Library.Boolean SQLSysPrivs, _.Library.Boolean SQLObjPrivs, _.Library.String NewPassword)
	Copy a User. More...

_.Library.Status	Create (_.Library.String Username, _.Library.String UserRoles, _.Library.String Password, _.Library.String FullName, _.Library.String NameSpace, _.Library.String Routine, _.Library.String ExpirationDate, _.Library.Boolean ChangePassword, _.Library.Boolean Enabled, _.Library.String Comment, _.Library.String Flags, _.Library.String PhoneNumber, _.Library.String PhoneProvider, _.Library.String Attributes, _.Library.Boolean AccountNeverExpires, _.Library.Boolean PasswordNeverExpires, _.Library.String PasswordHashAlgorithm, _.Library.Integer PasswordHashWorkFactor)
	Create a User. More...

_.Library.Status	Delete (_.Library.String Username)
	Delete a User. More...

_.Library.Boolean	Exists (_.Library.String Username, _.Library.ObjectHandle User, _.Library.Status Status, _.Library.Integer Flag)
	User exists. More...

_.Library.Status	ExpireUserPasswords (_.Library.String Names, _.Library.Integer Count)
	Set selected users accounts as having to change their. More...

_.Library.Status	Export (_.Library.String FileName, _.Library.Integer NumExported, _.Library.String Usernames, _.Library.String Roles, _.Library.Boolean SQLPrivileges, _.Library.Integer NumSQLPrivilegesExported)
	This method exports User records to a file in xml format. More...

_.Library.Status	Get (_.Library.String Username, _.Library.String Properties)
	Get a User's properties. More...

_.Library.Status	GetResourceSet (_.Library.String Username, _.Library.String Roles, _.Library.String Resources)
	Get a User's or Roles set of resources. More...

_.Library.Status	GetRoleSet (_.Library.String Username, _.Library.String Roles)
	Get a User's set of roles. More...

_.Library.Status	Import (_.Library.String FileName, _.Library.Integer NumImported, _.Library.Integer Flags, _.Library.Integer NumSQLPrivsImported)
	Import User records from an xml file. More...

_.Library.Status	Modify (_.Library.String Username, _.Library.String Properties)
	Modify a User's properties. More...

_.Library.Status	RemoveRoles (_.Library.String Username, _.Library.String Roles)
	Remove role(s) from the User's definition. More...

_.Library.Status	UnExpireUserPasswords (_.Library.String Names, _.Library.Integer Count)
	Set selected users accounts to not have their password change on next login. More...

Public Attributes
	AccountNeverExpires
	Account Expiration behavior. More...

	Attributes
	Attributes to apply to user when they log in. More...

	AutheEnabled
	Two factor Authentication options which are enabled for this user. More...

	ChangePassword
	Change password on next login. More...

	Comment
	Comment. More...

	CreateDateTime
	Account creation date and time. More...

	CreateUsername
	$username of user who created the account. More...

	EmailAddress
	Email address of the user. More...

	Enabled
	Allow user to log in. More...

	ExpirationDate
	Last date an account can be used. More...

	Flags
	Flags associated with user. More...

	FullName
	Full name of the user. More...

	HOTPKey
	Time-based One-time Password key. More...

	HOTPKeyDisplay
	Display the Time-based One-time Password QR code or key on next login for the. More...

	HOTPKeyGenerate
	0 - Do not generate a new Time-based One-time Password key when user is saved. More...

	InvalidLoginAttempts
	Number of invalid login attempts since last successful one. More...

	InvalidLoginDateTime
	Last invalid login date and time. More...

	InvalidLoginDevice
	Last invalid login device. More...

	InvalidLoginService
	Last invalid login Service. More...

	InvalidLoginStatus
	Last login error. More...

	LastModifiedDateTime
	Account modified date and time. More...

	LastModifiedInfo
	Information describing last modification of the user. More...

	LastModifiedUsername
	$username of the person who last modified it. More...

	LoginDateTime
	Last Successful login date and time. More...

	LoginDevice
	Last Successful login device. More...

	LoginService
	Last Successful login Service. More...

	Name
	User Name. More...

	NameSpace
	NameSpace to run in only if a terminal session. More...

	Password
	PBKDF2 hashed password for InterSystems IRIS Authentication. More...

	PasswordChangedDateTime
	Last password change date and time. More...

	PasswordExternal
	Clear text password. More...

	PasswordHash
	Used to securely set user password using a cryptographic hash. More...

	PasswordHashAlgorithm
	Algorithm used to calculate user's current PBKDF2 password hash. More...

	PasswordHashWorkFactor
	Work Factor used to calculate user's current PBKDF2 password hash. More...

	PasswordNeverExpires
	Password expires behavior. More...

	PhoneNumber
	Phone number for two-factor authentication. More...

	PhoneProvider
	Mobile phone service provider for two-factor authentication. More...

	Roles
	Roles assigned to the user. More...

	RolesAreAdmin
	When adding a role to the user during Create, allows the user to be able. More...

	Routine
	Routine to run only if terminal session, ""=Programmer mode. More...

	Salt
	Salt value for Hashed password from $System.Encryption.GenCryptRand. More...

	SuperUser
	User holds the All role. More...

Detailed Description

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.

Member Function Documentation

◆ AddRoles()

_.Library.Status AddRoles	(	_.Library.String	Username,
		_.Library.String	Roles,
		_.Library.Boolean	Admin
	)

static

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.

If you add the user to the All role, the SuperUser property is set to 1.

◆ Copy()

_.Library.Status Copy	(	_.Library.String	Name,
		_.Library.String	NewName,
		_.Library.String	NewFullName,
		_.Library.Boolean	SQLSysPrivs,
		_.Library.Boolean	SQLObjPrivs,
		_.Library.String	NewPassword
	)

static

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.

◆ Create()

_.Library.Status Create	(	_.Library.String	Username,
		_.Library.String	UserRoles,
		_.Library.String	Password,
		_.Library.String	FullName,
		_.Library.String	NameSpace,
		_.Library.String	Routine,
		_.Library.String	ExpirationDate,
		_.Library.Boolean	ChangePassword,
		_.Library.Boolean	Enabled,
		_.Library.String	Comment,
		_.Library.String	Flags,
		_.Library.String	PhoneNumber,
		_.Library.String	PhoneProvider,
		_.Library.String	Attributes,
		_.Library.Boolean	AccountNeverExpires,
		_.Library.Boolean	PasswordNeverExpires,
		_.Library.String	PasswordHashAlgorithm,
		_.Library.Integer	PasswordHashWorkFactor
	)

static

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

◆ Delete()

_.Library.Status Delete ( _.Library.String Username )

static

Delete a User.

This method will delete a User from the security database.
Parameters:
Username - Username to delete

◆ Exists()

_.Library.Boolean Exists	(	_.Library.String	Username,
		_.Library.ObjectHandle	User,
		_.Library.Status	Status,
		_.Library.Integer	Flag
	)

static

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<br>
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

◆ ExpireUserPasswords()

_.Library.Status ExpireUserPasswords	(	_.Library.String	Names,
		_.Library.Integer	Count
	)

static

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.

◆ Export()

_.Library.Status Export	(	_.Library.String	FileName,
		_.Library.Integer	NumExported,
		_.Library.String	Usernames,
		_.Library.String	Roles,
		_.Library.Boolean	SQLPrivileges,
		_.Library.Integer	NumSQLPrivilegesExported
	)

static

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

◆ Get()

_.Library.Status Get	(	_.Library.String	Username,
		_.Library.String	Properties
	)

static

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.

◆ GetResourceSet()

_.Library.Status GetResourceSet	(	_.Library.String	Username,
		_.Library.String	Roles,
		_.Library.String	Resources
	)

static

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

◆ GetRoleSet()

_.Library.Status GetRoleSet	(	_.Library.String	Username,
		_.Library.String	Roles
	)

static

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

◆ Import()

_.Library.Status Import	(	_.Library.String	FileName,
		_.Library.Integer	NumImported,
		_.Library.Integer	Flags,
		_.Library.Integer	NumSQLPrivsImported
	)

static

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

◆ Modify()

_.Library.Status Modify	(	_.Library.String	Username,
		_.Library.String	Properties
	)

static

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.

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.

◆ RemoveRoles()

_.Library.Status RemoveRoles	(	_.Library.String	Username,
		_.Library.String	Roles
	)

static

Remove role(s) from the User's definition.

Parameters:
Username - Name of the user to remove roles from
Roles - Comma delimited list of roles.

◆ UnExpireUserPasswords()

_.Library.Status UnExpireUserPasswords	(	_.Library.String	Names,
		_.Library.Integer	Count
	)

static

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.

Member Data Documentation

◆ AccountNeverExpires

AccountNeverExpires

Account Expiration behavior.

0 - Account expires normally.
1 - Account will never expire.

◆ Attributes

Attributes

Attributes to apply to user when they log in.

◆ AutheEnabled

AutheEnabled

Two factor Authentication options which are enabled for this user.

Options are:
$$$AutheTwoFactorSMS - SMS Text authentication
$$$AutheTwoFactorPW - Time-based One-time Password

◆ ChangePassword

ChangePassword

Change password on next login.

0 - Password change not required.
1 - Password change required before next login.

◆ Comment

Comment

Comment.

◆ CreateDateTime

CreateDateTime

Account creation date and time.

$H format in utc.

◆ CreateUsername

CreateUsername

$username of user who created the account.

◆ EmailAddress

EmailAddress

Email address of the user.

◆ Enabled

Enabled

Allow user to log in.

0 - Disable login.
1 - Enable login.

◆ ExpirationDate

ExpirationDate

Last date an account can be used.

$H date value of when an account becomes disabled.

◆ Flags

Flags

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.

◆ FullName

FullName

Full name of the user.

◆ HOTPKey

HOTPKey

Time-based One-time Password key.

This property is automatically generated when the user is created using the $System.Encryption.GenCryptRand() method.

◆ HOTPKeyDisplay

HOTPKeyDisplay

Display the Time-based One-time Password QR code or key on next login for the.

user to scan with their authentication device.

◆ HOTPKeyGenerate

HOTPKeyGenerate

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.

◆ InvalidLoginAttempts

InvalidLoginAttempts

Number of invalid login attempts since last successful one.

◆ InvalidLoginDateTime

InvalidLoginDateTime

Last invalid login date and time.

◆ InvalidLoginDevice

InvalidLoginDevice

Last invalid login device.

◆ InvalidLoginService

InvalidLoginService

Last invalid login Service.

◆ InvalidLoginStatus

InvalidLoginStatus

Last login error.

◆ LastModifiedDateTime

LastModifiedDateTime

Account modified date and time.

$H format in utc.

◆ LastModifiedInfo

LastModifiedInfo

Information describing last modification of the user.

◆ LastModifiedUsername

LastModifiedUsername

$username of the person who last modified it.

◆ LoginDateTime

LoginDateTime

Last Successful login date and time.

$H format in utc.

◆ LoginDevice

LoginDevice

Last Successful login device.

◆ LoginService

LoginService

Last Successful login Service.

◆ Name

Name

User Name.

Includes domain if multiple domains are enabled in the format username@domain.

◆ NameSpace

NameSpace

NameSpace to run in only if a terminal session.

◆ Password

Password

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.

◆ PasswordChangedDateTime

PasswordChangedDateTime

Last password change date and time.

$H format in utc.

◆ PasswordExternal

PasswordExternal

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.

◆ PasswordHash

PasswordHash

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 <CLASS>Config.Startup</CLASS>.

◆ PasswordHashAlgorithm

PasswordHashAlgorithm

Algorithm used to calculate user's current PBKDF2 password hash.

Irrelevant for users without passwords.

◆ PasswordHashWorkFactor

PasswordHashWorkFactor

Work Factor used to calculate user's current PBKDF2 password hash.

Irrelevant for users without passwords.

◆ PasswordNeverExpires

PasswordNeverExpires

Password expires behavior.

0 - Password expires normally.
1 - Password never expires.

◆ PhoneNumber

PhoneNumber

Phone number for two-factor authentication.

◆ PhoneProvider

PhoneProvider

Mobile phone service provider for two-factor authentication.

◆ Roles

Roles

Roles assigned to the user.

◆ RolesAreAdmin

RolesAreAdmin

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

◆ Routine

Routine

Routine to run only if terminal session, ""=Programmer mode.

◆ Salt

Salt

Salt value for Hashed password from $System.Encryption.GenCryptRand.

◆ SuperUser

SuperUser

User holds the All role.

Static Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ AddRoles()

◆ Copy()

◆ Create()

◆ Delete()

◆ Exists()

◆ ExpireUserPasswords()

◆ Export()

◆ Get()

◆ GetResourceSet()

◆ GetRoleSet()

◆ Import()

◆ Modify()

◆ RemoveRoles()

◆ UnExpireUserPasswords()

Member Data Documentation

◆ 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