Privileges and Permissions
Permissions allow users to perform some action, such as reading or writing data, or using a tool. Permissions are associated with resources, forming privileges. A privilege is written as a resource name followed by a permission separated by a colon, such as %DB_Sales:Read, which describes an action a user can perform.
A group of privileges, in turn, is called a role. Performing an action requires a user to be a member of a role that holds the appropriate privilege. This model provides precision when specifying what tasks a user (or group of users) can do – to make an adjustment, simply adjust the privileges in that user’s role.
How Privileges Work
A privilege associates a resource with a permission, so that a role that holds the privilege can perform a particular action, such as read or write to a database or use an application. The possible permissions are:
-
Read — View (but not change) the contents of a resource, such as in a database
-
Write — View or change the contents of a resource, such as in a database
-
Use — Run or otherwise employ an executable program or tool, such as an application or an InterSystems service
The meaning of each permission depends on the resource with which it is used. Permission names can appear as the full word or the first letter of the word; their names are not case-sensitive.
Public Permissions
For each resource, permissions can be designated as Public. Effectively, this is equivalent to all users holding that permission on the resource. For example, if the %DB_SALES:Read privilege is Public, then any user can read from any database protected by the %DB_SALES resource. This does not, however, enable all users to write those databases because (in this example) the %DB_SALES:Write privilege is not Public.
The following database privileges are Public by default:
Default Public Privileges
| Resource |
Permission |
| %DB_IRIS |
Read |
| %DB_IRISLIB |
Read |
| %DB_IRISTEMP |
Read, Write |
Check the Privileges of a Process
InterSystems IRIS® data platform provides a method, $SYSTEM.Security.Check, to check on privileges held by the current process. Its one-argument form lists what privileges the process holds on a particular resource; its two-argument form returns whether or not the process holds privileges for a particular resource. (There are also methods with built-in privilege checks, described in the next section.)
The one-argument form returns a comma-delimited list of the permissions held by the process on a resource. For example:
$SYSTEM.Security.Check("%DB_TESTDATABASE")
returns READ,WRITE if the process holds Read and Write permissions for %DB_TESTDATABASE. The permission names are always returned as full words in uppercase letters. The function returns an empty string if the process holds no permissions on the resource.
The two-argument form returns True or False (1 or 0) to indicate whether the process holds a specific privilege. For example:
$SYSTEM.Security.Check("%DB_TESTDATABASE", "WRITE")
returns 1 if the process holds the Write permission on the %DB_TESTDATABASE resource.
You can also call the function with a list of permissions, such as:
$SYSTEM.Security.Check("%DB_TESTDATABASE", "WRITE,READ")
It returns 1 if the process holds all of the requested permissions and 0 otherwise. You can also simply use the first letter of the privileges to be checked:
$SYSTEM.Security.Check("%DB_TESTDATABASE", "W,R")
The method has the following general behaviors:
-
The method always returns 1 for a public resource privilege, whether or not the process explicitly holds that privilege.
-
Permission names are not case-sensitive.
-
Permission names can be fully spelled out, as in the example above, or abbreviated by their first character. Also, permission names are not case-sensitive. Thus, “WRITE,READ”, “W,R”, and “R,Write” are equivalent.
Use Methods with Buillt-In Privilege Checks
InterSystems IRIS allows methods to require that the process that calls them has certain specified privileges.
This feature uses the Requires method keyword. The Requires method keyword has a quoted string value that is a comma-delimited list of privileges. Each privilege names a resource and its associated permission (Use, Read, or Write) in standard format.
For example, if the MyAction method requires the Service_FileSystem:Use privilege, its signature might be:
ClassMethod MyAction() [ Requires="Service_FileSystem:Use"]
{
// Method content
}
If the Requires keyword has a value, the method may only run if the calling process has the required privilege at the time that it invokes the method. If the process does not have the required privilege, the system generates a <PROTECT> error.
Methods that inherit this keyword may require additional resources by overriding and setting a new value for the keyword. There is no way to remove requirements.
When Changes in Privileges Take Effect
InterSystems IRIS maintains a persistent database of the security settings. When InterSystems IRIS starts, it extracts this information and places it into a segment of shared memory that allows quick access to the consolidated settings. While a process is executing, it maintains its own per-process cache of the privileges it has been granted. This is updated as new privileges are needed (and authorized).
Editing roles, privileges, and so on makes changes to the persistent copy of the information. This becomes visible to users or applications the next time they are subsequently authenticated.
