Skip to main content
Previous section   Next section

Privileges and Permissions

Permissions allow you to perform some action, such as reading or writing data, or using a tool. Permissions are associated with resources, forming privileges. This model allows a user to perform a particular action in relation to a particular resource.

Topics in this chapter include:

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

Checking Privileges

InterSystems IRIS® 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")
Copy code to clipboard

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")
Copy code to clipboard

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")
Copy code to clipboard

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")
Copy code to clipboard

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.

Using Methods with Built-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
}
Copy code to clipboard

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.

Previous section   Next section