%SYSTEM.Security
abstract class %SYSTEM.Security
Method Inventory
- AddRoles()
- Audit()
- ChangePassword()
- Check()
- CheckRolesPermission()
- CheckUserPermission()
- GetGlobalPermission()
- GetRecursedRoleSet()
- GetUserRecursedRoleSet()
- Login()
- ValidatePassword()
Methods
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.
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.
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 CACHESYS database or the calling routine is stored in the CACHESYS 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.
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 CACHESYS database or the calling routine is stored in the CACHESYS 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 %CacheString
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_CACHETEMP") => "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.
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_CACHETEMP") => "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 %CacheString
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_CACHESYS") => "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.
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_CACHESYS") => "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 %CacheString
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_CACHESYS") => "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
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_CACHESYS") => "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) as %String
Return the permissions the process has for a global.
Parameters:
NameSpace - Namespace where the global exists.
Global - name of the global
Subscripts - Fully specified subscript including "()"
Return Values:
Comma delimited list of permissions process has on the global, or "" for no access/invalid parameters.
e.g. READ,WRITE
Remarks:
This method will follow the mapping of where the global actually is mapped to to find out the access to it.
Examples:
Check the access on the source code for the %SS routine, which is stored in the global ^ROUTINE("%SS")
S x=$SYSTEM.Security.GetGlobalPermission("USER","ROUTINE","(""%SS"")")
Parameters:
NameSpace - Namespace where the global exists.
Global - name of the global
Subscripts - Fully specified subscript including "()"
Return Values:
Comma delimited list of permissions process has on the global, or "" for no access/invalid parameters.
e.g. READ,WRITE
Remarks:
This method will follow the mapping of where the global actually is mapped to to find out the access to it.
Examples:
Check the access on the source code for the %SS routine, which is stored in the global ^ROUTINE("%SS")
S x=$SYSTEM.Security.GetGlobalPermission("USER","ROUTINE","(""%SS"")")
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.
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.
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.
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.
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 CACHESYS database or the calling routine is stored in the CACHESYS 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.
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 CACHESYS database or the calling routine is stored in the CACHESYS 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.
Validate a password against system password policy.