%SYSTEM.Security

Class %SYSTEM.Security [ Abstract, System = 4 ]

Methods

AddRoles

ClassMethod AddRoles(ApplicationName As %String, Hash As %String = "") As %Status

Add the extra roles associated with the named application

Audit

ClassMethod Audit(Source As %String, Type As %String, Name As %String, EventData As %String, Description As %String) As %Status [ Abstract ]

Audit a user-level event. If auditing is enabled for user level events, generate an audit record with the user-specified information.
Source - Source of the Audit event
Type - Type of the Audit event
Name - Name of the Audit event
EventData - Data logged by the event. Maximum size of 3632952 bytes. Truncated if longer.
Description - Description of the audit event. Maximum size of 128 bytes. Truncated if longer.

AuditID

ClassMethod AuditID(AuditIndex As %Integer, EventData As %String, Description As %String) As %Boolean [ Abstract, Internal ]

Audit a system-level event.
This method functions exactly like the Audit method, but avoids the overhead of looking up the Audit Index using the Source, Type, and Name.
AuditIndex - Audit event number defined in %syAudit.
EventData - Data logged by the event. Maximum size of 3632952 bytes. Truncated if longer.
Description - Description of the audit event. Maximum size of 128 bytes. Truncated if longer.

ChangePassword

ClassMethod ChangePassword(Username As %String, NewPassword As %String, OldPassword As %String, ByRef Status As %Status) As %Boolean

Change password for a user.
Parameters:
Username - Name of the User to change
NewPassword - New password to set
OldPassword - Old Password to validate against
Return Value:
0 - Failure
1 - Password changed
On failure, an error code is returned in Status.
If the old password is not passed as a parameter, then the password will be changed to the NewPassword parameter, providing the following:

The calling process has Write permission on the resource that protects the IRISSYS database or the calling routine is stored in the system database.
If you are trying to change the password of a user who was created either through Delegated authentication or through LDAP authentication, you will need to update the ChangePassword^ZAUTHENTICATE routine on your system. See the ZAUTHENTICATE routine in the SAMPLES namespace for documentation.

Check

ClassMethod Check(ResourceName As %String, Permissions As %String) As %RawString [ Abstract ]

Determine if a specified privilege is held on a specified resource.
If called as $System.Security.Check(resource)
it returns the privileges held on that resource as a comma-separated list. For example,
$System.Security.Check("%DB_IRISTEMP") => "READ,WRITE"

If called as $System.Security.Check(resource,privilege) it returns 1 or 0 depending on whether the specified privilege is held. For example,
$System.Security.Check("%Development","USE") => 1
Note: If the process holds the %All role, then the method always returns "READ,WRITE,USE" for the 1-argument form and 1 for the 2-argument form.

CheckRolesPermission

ClassMethod CheckRolesPermission(Roles As %String, ResourceName As %String, Permissions As %String) As %RawString

Determine if a specified privilege is held on a specified resource for a set of roles.
If called as $System.Security.CheckRolesPermission(Roles,Resource)
it returns the privileges held on that resource as a comma-separated list. For example,
$System.Security.CheckRolesPermission("%Manager,%Operator","%DB_IRISSYS") => "READ,WRITE"

If called as $System.Security.CheckRolesPermission(Roles,Resource,Privilege) it returns 1 or 0 depending on whether the specified privilege is held. For example,
$System.Security.CheckRolesPermission("%Manager","%Admin_Secure","USE") => 1
The method will take the list of roles passed to this method, and for each role in the list will determine if any additional roles are granted by this role. If so, it also adds this role to the list. Once the entire set of roles is calculated, the list of resources and permissions which the list of roles contains is calculated. Finally, any PUBLIC resources are also added to the list of resources and permission. The resource name is then checked against this list to determine the return value for the method.
Note: If one of the roles being checked is %All, then the method always returns "READ,WRITE,USE" for the 2-argument form and 1 for the 3-argument form
If the Role does not exist, or an error occurs, then the method will return "" for the 2-argument form and 0 for the 3-argument form.

CheckUserPermission

ClassMethod CheckUserPermission(Username As %String, ResourceName As %String, Permissions As %String) As %RawString

Determine if a specified privilege is held on a specified resource for a specific Username.
If called as $System.Security.CheckUserPermission(Username,Resource)
it returns the privileges held on that resource as a comma-separated list. For example,
$System.Security.CheckUserPermission("Admin","%DB_IRISSYS") => "READ,WRITE"

If called as $System.Security.CheckUserPermission(Username,Resource,Privilege) it returns 1 or 0 depending on whether the specified privilege is held. For example,
$System.Security.CheckUserPermission("Operator","%Admin_Secure","USE") => 0
The method will take the Username passed to this method, and retrieve the list of roles the user is granted. For each role in this list, it will determine if any additional roles are granted by this role. If so, it also adds this role to the list. Once the entire set of roles is calculated, the list of resources and permissions which the list of roles contains is calculated. Finally, any PUBLIC resources are also added to the list of resources and permission. The resource name is then checked against this list to determine the return value for the method.
Note: If the Username holds the %All role, then the method always returns "READ,WRITE,USE" for the 2-argument form and 1 for the 3-argument form
If the User does not exist, or an error occurs, then the method returns "" for the 2-argument form and 0 for the 3-argument form

ValidatePassword

ClassMethod ValidatePassword(Password As %String, Username As %String = "User") As %Status

Validate a password against system password policy.
Password - Password to validate against the system password policy
Username - (Optional) Username to use to validate against user defined password policy

Login

ClassMethod Login(Username As %String, Password As %String) As %Boolean

Log in a user given a valid username and password.
Parameters:
Username - Name of the user to log in as
Password - Password of user to log in (optional)
Return Value:
0 - Failure
1 - Success, user logged in
If the password is not passed as a parameter (1 argument form), then the user will be logged in if the calling process has Write permission on the resource that protects the IRISSYS database or the calling routine is stored in the system database.

When the password is passed in as the second parameter (2 argument form), the method requires that the user has the %Service_Login:USE privilege.

GetGlobalPermission

ClassMethod GetGlobalPermission(Namespace As %String = "", Global As %String = "", Subscript As %String, Mount As %Boolean = 1) As %String

Return the permissions the process has for a global.
This method will follow the mapping of where the global and subscript are actually mapped to to find out the access to it.
If the database where it maps to is read-only, then the method can only return "READ" or "".
Parameters:
Namespace - Namespace where the global exists. The namespace specified may either be a real namespace, or an implied namespace in the format ^system^directory.
Global - Name of the global. If not specified or "", then the method returns the permissions for the default global database of the namespace.
Subscripts - Fully specified subscript including "()".
Mount - Default = 1 - 1=If the database is not mounted, mount it before checking. Subsequent permission checks may be faster.
0 = Do not mount the database if it is not mounted.
Return Values:
Comma delimited list of permissions the process has on the global, or "" for no access/invalid parameters.
e.g. READ,WRITE
In the case where an ECP database is not mounted, the return value may be "UNKNOWN"
Examples:
Check the access on the global ^GLOBALNAME("Subscript1")
S x=$SYSTEM.Security.GetGlobalPermission("USER","GLOBALNAME","(""Subscript1"")")
Check the access on the global ^ABC("Subscript1",2)
S x=$SYSTEM.Security.GetGlobalPermission("USER","GLOBALNAME","(""Subscript1"",2)")

GlobalPermissionCheck

ClassMethod GlobalPermissionCheck(Permissions As %String, Namespace As %String = "", Global As %String = "", Subscript As %String, Mount As %Boolean = 1) As %Boolean

Checks if the caller has the permissions requested on the specified global.
This method follows the mappings for the namespace and determines if you have the permissions requested on the specified global.
Parameters:
Permissions - comma separated list of permissions. Can be any combination of "READ","R","WRITE", or "W".
Namespace - Namespace where the global exists. The namespace specified may either be a real namespace, or an implied namespace in the format ^system^directory.
Global - Name of the global. Subscripts - Fully specified subscript including "()".
Mount - Default = 1 - 1=If the database is not mounted, mount it before checking. Subsequent permission checks may be faster.
0 = Do not mount the database if it is not mounted.
Return Values:
Comma delimited list of permissions the process has on the global, or "" for no access/invalid parameters.
e.g. READ,WRITE
In the case where an ECP database is not mounted, and the mount flag is not specified, the return value may be "UNKNOWN"
Examples:
Check for READ access on the global ^GLOBALNAME("Subscript1")
S x=$SYSTEM.Security.GlobalPermissionCheck("READ","USER","GLOBALNAME","(""Subscript1"")")
Check READ and WRITE access on the global ^ABC("Subscript1",2)
S x=$SYSTEM.Security.GlobalPermissionCheck("READ,WRITE","USER","GLOBALNAME","(""Subscript1"",2)")

GetRoutinePermission

ClassMethod GetRoutinePermission(Namespace As %String = "", Routine As %String = "", Mount As %Boolean = 1) As %String

Return the permissions the process has for a routine.
This method will follow the mapping of where the routine is mapped to to find out the access to it.
If the database where it maps to is read-only, then the method can only return "READ" or "".
Parameters:
Namespace - Namespace where the routine exists. The namespace specified may either be a real namespace, or an implied namespace in the format ^system^directory.
Routine - Name of the routine. If not specified or "", then the method returns the permissions for the default routine database of the namespace.
Mount - Default = 1 - 1=If the database is not mounted, mount it before checking. Subsequent permission checks may be faster.
0 = Do not mount the database if it is not mounted.
Return Values:
Comma delimited list of permissions the process has on the routine, or "" for no access/invalid parameters.
e.g. READ,WRITE
In the case where an ECP database is not mounted, and the mount flag is not specified, the return value may be "UNKNOWN"
Examples:
Check the access on the routine ^ROUTINENAME
S x=$SYSTEM.Security.GetRoutinePermission("USER","ROUTINENAME")
Check the access for the default routine database for the namespace
S x=$SYSTEM.Security.GetRoutinePermission("USER")

RoutinePermissionCheck

ClassMethod RoutinePermissionCheck(Permissions As %String, Namespace As %String = "", Routine As %String = "", Mount As %Boolean = 1) As %Boolean

Checks if the caller has the permissions requested on the specified routine.
This method follows the mappings for the namespace and determines if you have the permissions requested on the specified routine.
Parameters:
Namespace - Namespace where the routine exists. The namespace specified may either be a real namespace, or an implied namespace in the format ^system^directory.
Routine - Name of the routine. If not specified or "", then the method returns the permissions for the default routine database of the namespace.
Mount - Default = 1 - 1=If the database is not mounted, mount it before checking. Subsequent permission checks may be faster.
0 = Do not mount the database if it is not mounted.
Return Values:
Comma delimited list of permissions the process has on the routine, or "" for no access/invalid parameters.
e.g. READ,WRITE
In the case where an ECP database is not mounted, the return value may be "UNKNOWN"
Examples:
Check the access on the routine ^ROUTINENAME
S x=$SYSTEM.Security.RoutinePermissionCheck("USER","ROUTINENAME")
Check the access for the default routine database for the namespace
S x=$SYSTEM.Security.RoutinePermissionCheck("USER")

GetRecursedRoleSet

ClassMethod GetRecursedRoleSet(Roles As %String, ByRef RecursedRoles As %String) As %Status

Given a set of roles, recurse through them for the entire set of roles which would be granted.
When a role is granted to a process, the role itself may grant another role. This method takes a comma delimited set of roles as input, and returns the comma delimited entire set of roles which would be granted to the process.
Parameters:
Roles - Comma delimited list of roles to recurse.
Return value:
RecursedRoles - Comma delimited list of recursed roles.

GetUserRecursedRoleSet

ClassMethod GetUserRecursedRoleSet(Username As %String, ByRef RecursedRoles As %String) As %Status

Given a Username, return the entire set of roles which would be granted if they logged in.
When a role is granted to a process, the role itself may grant another role. This method takes a username as input, and returns the comma delimited entire set of roles which would be granted to the user if they logged in.
Parameters:
Username - Username to calculate recursed role set for.
Return value:
RecursedRoles - Comma delimited list of recursed roles.

ResourceExists

ClassMethod ResourceExists(Resource As %String) As %Boolean [ Internal ]

Returns 0/1 if the resource exists

CSPEscalateLogin

ClassMethod CSPEscalateLogin(RoleName As %String, Password As %String) As %Status [ Internal ]

Escalate the user's CSP session to the given escalation role. This role must be one of the current user's configured EscalationRoles. This method should not be used directly, instead Applications should call:
Do %session.EscalateLogin(Role,Password)

EscalateLogin

ClassMethod EscalateLogin(RoleName As %String, Password As %String) As %Status

Escalate the user's login to the given escalation role. This role must be one of the current user's configured EscalationRoles.

• RoleName - specifies the escalation role to assume
• Password - the user's password Both parameters are optional; if absent the user will be prompted for their values. This method must be called from a foreground process.