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

abstract class %SYSTEM.Security

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
15


Summary

Methods
AddRoles Audit AuditID ChangePassword
Check CheckRolesPermission CheckUserPermission GetGlobalPermission
GetRecursedRoleSet GetRoutinePermission GetUserRecursedRoleSet GlobalPermissionCheck
Login RoutinePermissionCheck ValidatePassword


Methods

• classmethod AddRoles(ApplicationName As %String, Hash As %String = "") as %Status
Add the extra roles associated with the named application
• abstract classmethod Audit(Source As %String, Type As %String, Name As %String, EventData As %String, Description As %String) as %Status
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.
• abstract classmethod AuditID(AuditIndex As %Integer, EventData As %String, Description As %String) as %Status
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.
• 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.
• abstract classmethod Check(ResourceName As %String, Permissions As %String) as %RawString
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.
• 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.
• 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
• 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)")
• 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.
• 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")
• 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.
• 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)")
• 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 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 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.
• 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")
• 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


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