Security Administration Guide
Roles
|
|
A role is a named collection of privileges. Roles are useful because multiple users often need the same set of privileges. For example, all users of an application or all developers working on a particular project might need a common set of privileges. By using a role, such sets of privileges can be defined once (which makes future modification much easier) and shared by the relevant users. Privileges are assigned exclusively to roles; privileges are not assigned directly to users. To assign some privileges to a single user, create a role for that purpose.
Major topics related to roles include:
Every role has the following properties:
Role Properties
Property Name |
Property Description |
Name |
Unique role identifier. See the section “Naming Conventions” for more information on valid names. |
Description |
Any text. |
Privileges |
Resource-permission pair(s) associated with the role. A role can hold zero or more privileges. |
Members |
Users or roles that have been assigned to the role (listed on the Members tab of the Edit Role page). |
Each role also may have members that are assigned to it or other roles to which it is assigned. These relations are described in the next section.
A role is a container that holds one or more privileges. If a user is associated with a role, then that user is able to exercise the role’s privileges. The terminology for the association of a user and role is:
-
The user
is assigned to the role.
-
The user
is a member of the role.
-
The role
includes the user.
These phrases are all equivalent in meaning to each other.
Each user can be assigned to multiple roles and each role can have multiple users as its members. Similarly, each role can also be assigned to multiple roles and can also have multiple roles as its members. A role can have both users and roles as its members.
If one role is assigned to another, that first role holds the privileges associated with the second role. This is analogous to the relationship of assigning a user to role, whereby the user then holds the privileges associated with the role. Hence, if a user is a member of one role and that role is a member of another role, then the user holds privileges associated with both the roles.
For example, suppose a university has three roles available for its students:
UndergraduateStudent,
GraduateStudent, and
GeneralStudent. Each student is assigned to either
UndergraduateStudent or
GraduateStudent, and these two roles are both assigned to
GeneralStudent. If Elizabeth is assigned to
GraduateStudent, she holds the privileges associated with both
GraduateStudent and
GeneralStudent; if James is assigned to
UndergraduateStudent, he holds the privileges associated with both
UndergraduateStudent and
GeneralStudent.
A role’s members are listed on the
Edit Role page’s
Members tab; on this tab, you can also assign new members to a role. If a role has been assigned to other roles, these are listed on the
Assigned To tab of the
Edit Role page; you can also assign a role to additional roles on that tab.
This section provides an example of how users and roles interact in InterSystems IRIS.
Suppose there is a user named Lee, a role named
FirstRole, and a role named
SecondRole.
FirstRole protects a resource called
FirstResource and
SecondRole protects a resource called
SecondResource.
When first created, Lee is not a member of any roles. This is reflected in Lee’s profile:
When Lee is assigned to the role
FirstRole, this changes Lee’s profile:
When the role FirstRole is assigned to the role
SecondRole, this also changes Lee’s profile:
The list of Lee’s privileges specifies which privileges originate with which roles:
You can define roles for use by developers, operators, system managers and other classes of users. Once created, there are various features available to
edit a role.
-
-
-
On the
Edit Role page, the
General tab is visible. Here, enter values for the following properties:
-
Name (required) Specifies the name of the new role. See the following section,
Naming Conventions, for naming rules.
-
Description (optional) Specifies descriptive information about the role.
The role’s resources are listed, but empty, as a role cannot receive resources until it has been created, except under the conditions described in the next step.
-
As a shortcut, if you wish to create multiple roles with similar characteristics, you can use the
Copy from field on the
Role page to begin the process of creating a new role. When you select an existing role from this field’s drop-down menu, all its privileges appear in the list of resources; you can then add or delete privileges as desired, and modify its Description property.
-
Click
Save to create the role.
The name of a user-defined role is subject to the following rules in its use of characters:
-
It can include all alphanumeric characters.
-
-
-
It can include Unicode characters.
Also, a role name is not case-sensitive. This means that:
-
For names that are defined using mixed case, the name is preserved exactly as it is entered.
-
Names that differ only by case are prohibited.
-
When a name is looked up, InterSystems IRIS ignores differences in case.
A role name can be up to 64 characters long.
For example, if there is a role named
BasicUser, any attempt to create another resource named
BASICUSER will fail. References to the resource using name values of
BasicUser,
basicuser, and
BASICUSER will all succeed.
Once you have
created a role, you modify it in a number of different ways, each of which is described in one of the following sections. The actions fall into several categories:
-
General tasks. This includes:
-
Creating, modifying, and removing a role’s privileges. This includes:
-
Creating and removing assignments among roles and users. This includes:
-
Note:
Changing a user’s roles or changing a role’s privileges does not affect the assigned privileges associated with the user’s existing processes. For new privileges to become active, the user must log out and log in again, restart the process, or perform an equivalent action.
-
Name The role’s name (cannot be edited)
-
Description Any text that has been provided to describe the role
-
Created By What user created the role
-
Edit the role’s properties, which includes all actions for privilege management, assignment management, and SQL-related options.
-
-
-
InterSystems IRIS displays a confirmation dialog. Click
OK to delete the role and
Cancel otherwise.
To give a role new privileges:
-
-
This displays a page listing all resources. To select a resource to assign to the role, click it. You can select multiple resources simultaneously using the
Ctrl or
Shift keys.
-
To add the selected resources to the role, click
Save. This gives the role all possible permissions on the resource; you can then modify the available permissions for the resource (such as changing permissions on a database from Read-Write to just Read).
To modify the privileges that a role holds:
-
-
On the
Roles page, click
Edit for the role you wish to modify. This displays the
Edit Role page.
-
On the
Edit Role page, in the
Resources table, click
Edit for the resource whose privileges you wish to modify.
-
This displays the page for editing the permissions on the selected resource. Check or clear the boxes for each permission as appropriate.
Note:
This page does not let you clear all permissions for an individual resource. This is because eliminating all a role’s permissions for a resource is equivalent to
deleting the role’s privileges for the resource.
-
Click
Save to save the privileges in their new state.
These changes should be reflected in the
Resources table on the
Role page.
To remove privileges from a role:
-
-
On the
Roles page, click
Edit for the role you wish to modify. This displays the
Edit Role page.
-
On the
Edit Role page, in the
Resources table, click
Delete. This removes the privileges for the resource from the role.
-
Click
Save to save the privileges in their new state.
A role can have users or other roles as members that are assigned to it. If a user is assigned to a role, then that user holds the privileges associated with that role. If one role is assigned to another role, then a user assigned to the first role holds the privileges associated with both roles.
To assign a user or role to the current role, the procedure is:
-
-
On the
Roles page, click
Edit for the role you wish to modify. This displays the
Edit Role page.
-
-
On the
Members tab, choose either the Users or Roles option to specify whether to assign users or roles to the role. (Users is the default.)
-
The list of users or roles that can be assigned to the current role appears in the
Available list. You can move them to and from the
Selected list using the arrow buttons between the lists.
-
When you have the final list of users or roles to add, click
Assign or
Assign with Grant Option. Clicking
Assign simply assigns the new members (users or roles) to the role being edited. Clicking
Assign with Grant Option also gives the new members the ability to assign other users or roles to the current role when using SQL commands.
If a user or role has been assigned to the current role, it is known as a member of that role. The procedure to remove a member from a role is:
-
-
On the
Roles page, click
Edit for the role you wish to modify. This displays the
Edit Role page.
-
-
On the
Members tab, there is a table of users and roles assigned to the current role. For the specified members, click the

button in the right-most column of the member’s row.
-
A prompt appears to confirm the removal. Click
OK.
The user or role has now been removed from the current role.
One role can be assigned to another role. If one role is assigned to another role, then a user assigned to the first role holds the privileges associated with both roles.
To assign the current role to another role, the procedure is:
-
-
On the
Roles page, click
Edit for the role you wish to modify. This displays the
Edit Role page.
-
-
The list of roles that the current role can be assigned to appears in the
Available list. You can move them to and from the
Selected list using the arrow buttons between the lists.
-
When you have the final list of roles, click
Assign or
Assign with Grant Option. Clicking
Assign simply assigns the current role to the selected roles. Clicking
Assign with Grant Option also gives the current role the ability to assign other users or roles to the selected role(s) when using SQL commands.
If the current role has been assigned to another role, it is known as a member of that role. The procedure to remove the current role from another role is:
-
-
On the
Roles page, click
Edit for the role you wish to modify. This displays the
Edit Role page.
-
-
On the
Assigned To tab, there is a table of roles to which the current role is assigned. To remove the current role from one of these roles, select the

button in the right-most column of that role’s row.
-
A prompt appears to confirm the removal. Click
OK.
The current role has now been removed from that role.
For every role, you can grant or remove the following SQL-related characteristics:
-
To add a privilege to a role, first move the privilege from the
Available list to the
Selected list (either double-click it or select it and then click the single right-arrow); click
Assign to give the privilege to the role. To also add the privilege of being able to grant the added privilege to other roles, select the relevant check box below the
Available list.
-
To add all privileges to a role, click the double-arrow pointing from the
Available list to the
Selected list; click
Assign to give the privileges to the role. To also add the privileges of being able to grant the added privileges to other roles, select the relevant check box below the
Available list.
-
To remove a privilege from a role, click
Remove to the right of privilege name.
-
To remove all privileges from a role, click
Remove All below the table listing the currently assigned privileges.
The following privileges are available:
-
%ALTER_TABLE For a given namespace, allow the member of the role to run the
ALTER TABLE command.
-
%ALTER_VIEW For a given namespace, allow the member of the role to run the
ALTER VIEW command.
-
%CREATE_FUNCTION For a given namespace, allow the member of the role to run the
CREATE FUNCTION command.
-
%CREATE_METHOD For a given namespace, allow the member of the role to run the
CREATE METHOD command.
-
%CREATE_PROCEDURE For a given namespace, allow the member of the role to run the
CREATE PROCEDURE command.
-
%CREATE_QUERY For a given namespace, allow the member of the role to run the
CREATE QUERY command.
-
%CREATE_TABLE For a given namespace, allow the member of the role to run the
CREATE TABLE command.
-
%CREATE_TRIGGER For a given namespace, allow the member of the role to run the
CREATE TRIGGER command.
-
%CREATE_VIEW For a given namespace, allow the member of the role to run the
CREATE VIEW command.
-
%DROP_FUNCTION For a given namespace, allow the member of the role to run the
DROP FUNCTION command.
-
%DROP_METHOD For a given namespace, allow the member of the role to run the
DROP METHOD command.
-
%DROP_PROCEDURE For a given namespace, allow the member of the role to run the
DROP PROCEDURE command.
-
%DROP_QUERY For a given namespace, allow the member of the role to run the
DROP QUERY command.
-
%DROP_TABLE For a given namespace, allow the member of the role to run the
DROP TABLE command.
-
%DROP_TRIGGER For a given namespace, allow the member of the role to run the
DROP TRIGGER command.
-
%DROP_VIEW For a given namespace, allow the member of the role to run the
DROP VIEWcommand.
On the
SQL Tables tab of the
Edit Role page, you can add or remove table-related SQL privileges for a role:
-
Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s tables appears.
-
To change privileges for a table, click
Edit in that table’s row. This displays a window for altering privileges.
-
In this window, you can check or clear any of the following items:
-
-
-
-
-
-
-
Give the
GRANT option to the role
-
After making your selection(s), click
Apply to establish the new privileges for the table.
If a role has privileges for a table, it is listed in a table on this page. To revoke the role’s privileges for a table, click
Revoke at the far right of the role’s row. Clicking this displays a message containing the namespace and the full name of the table (including the schema), such as the
“SAMPLES Sample.Company” namespace and table.
On the
SQL Views tab of the
Edit Role page, you can add or remove view-related SQL privileges for a role.
To add privileges for the view:
-
Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s views will appear.
-
To change privileges for a view, click
Edit in that view’s row. This displays a window for altering privileges.
-
In this window, you can check or clear any of the following items:
-
-
-
-
-
-
-
Give the
GRANT option to the role
-
After making your selection(s), click
Apply to establish the new privileges for the table.
If a role has privileges for a view, it is listed in a table on this page. To revoke the role’s privileges for a view, click
Revoke at the far right of the role’s row. Clicking this displays a message containing the namespace and the full name of the view (including the schema).
Privileges for Stored Procedures
On the
SQL Procedures tab of the
Edit Role page, you can add or remove a role’s SQL privileges related to stored procedures.
To add privileges for a stored procedure:
-
Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s stored procedures then appears.
-
-
In this dialog, near the top, select the schema from the drop-down that contains the procedure that you wish to add. This displays a list of the schema’s procedures in the
Available window on the left part of the page.
-
Move one or more procedures into the
Selected window. Make sure the
EXECUTE box is checked, so that the role has the privilege to execute the stored procedure.
-
Optionally, you can grant the roles the ability to grant this privilege on other roles; to do this, click the
Grant privilege box near the bottom of the page.
-
Click
Apply to grant the privilege(s) to the role.
If a role has privileges for a stored procedure, it is listed in a table on this page. To revoke the role’s privileges for a stored procedure, click
Revoke at the far right of the role’s row. Clicking this displays a message containing the namespace and the full name of the stored procedure (including the schema).
InterSystems IRIS includes a number of predefined roles. These include:
-
%All The ability to perform all operations.
-
%Developer The privileges typically associated with application development. These are roughly the privileges associated with the Portal’s System Exploration menu. They include the ability to use the WebStress and UnitTest pages in the Management Portal, as well as the documentation class reference (sometimes known as Documatic).
-
%Manager The privileges typically associated with system management. These are roughly the privileges associated with the Portal’s System Administration and System Operation menus.
-
%Operator The privileges typically associated with system operation. These are roughly the privileges associated with the Portal’s System Operation menu.
-
%SQL The privileges typically associated with SQL-related tasks.
-
Note:
InterSystems recommends that you do not modify predefined roles. Rather, create a new role based on the predefined role and modify the role that you have created.
The following table has a column for each role. Each row of the table lists a system-defined resource and the privilege, if any, that the role holds on it.
Predefined Roles and Their Privileges
Resource |
%Developer |
%Manager |
%Operator |
%SQL |
%SecureBreak |
%Admin_Manage |
|
Use |
|
|
|
%Admin_Operate |
|
Use |
Use |
|
|
%Admin_Secure |
|
Use |
|
|
|
%Admin_Task |
|
Use |
|
|
|
%DB_IRIS |
Read |
Read |
Read |
|
|
%DB_IRISAUDIT |
|
Read |
|
|
|
%DB_IRISLIB |
Read |
Read, Write |
|
|
|
%DB_IRISSYS |
|
Read, Write |
Read, Write |
|
|
%DB_IRISTEMP |
Read, Write |
Read, Write |
Read, Write |
|
|
%DB_%DEFAULT |
Read, Write |
Read, Write |
|
|
|
%Development |
Use |
Use |
|
|
|
%DocDB_Admin |
Use |
Use |
|
|
|
%Secure_Break |
|
|
|
|
Use |
%Service_Console |
|
|
|
|
|
%Service_DocDB |
Use |
Use |
Use |
|
|
%Service_Object |
Use |
Use |
|
|
|
%Service_SQL |
Use |
Use |
|
Use |
|
%Service_Telnet |
Use |
Use |
|
|
|
%Service_Terminal |
Use |
Use |
|
|
|
%Service_WebGateway |
Use |
Use |
Use |
|
|
The definitions of these predefined roles are set during a new InterSystems IRIS installation and are not modified during an upgrade installation. With the exception of
%All, the use of predefined roles is optional.
The
%Admin_Secure resource is designed to make all the necessary security assets available or restricted as a single unit. This makes it easy to separate these resources for use by the security administrator.
Note:
The
%Operator role does not hold the
%Admin_Task:Use privilege by default; if you wish for members of that role to be able to manage tasks, include
%Admin_Task:Use among the role’s privileges. Further, any custom roles based on
%Operator must add the
%DB_IRISSYS:RW privilege in order to use the Portal’s
Operator menu. They may also add the
%Admin_Task:Use privilege so that they can manage tasks.
The predefined role,
%All, always holds all privileges for all resources on the system. This is why, for example, a user belonging to the
%All role can still mount a database for which there is no resource available. (One exception is the restrictive
%Secure_Break:Use privilege, which must always be explicitly granted.)
This role cannot be deleted or modified, and there must always be at least one user account holding the
%All role. If there is only one such account, it cannot be deleted or disabled. This is designed to protect a sole InterSystems IRIS system administrator from being inadvertently locked out of the system.
When you create a database resource, the system automatically creates a role with the name
%DB_<database-resource-name> that has Read and Write permissions for that resource. The
%DB_<database-resource-name> roles are read-only and therefore cannot be modified; hence, for each of these roles, you cannot add privileges for other resources in addition to the RW access to the database resource for which the role is named.
Each InterSystems IRIS process has, at any point in time, a set of roles that determine the current privileges for that process. The set of roles includes both
login roles, which come from the definition of the user (received at login time) and
added roles, which come from the currently running application (received by
application role escalation). From a security standpoint, the origin of a role is immaterial: a process either has a required privilege or it does not.
When an application is started, each role currently held by the process is looked up in a table and any associated application roles are added.
For example, suppose there is an order entry application with two classes of users: normal users, who are assigned the
OrderEntryUser role, and managers, who are assigned the
OrderEntryManager role. Both of these roles allow someone to run the order entry application (that is, both are assigned the
%Application_OrderEntry:Use privilege.) But, when the application does role escalation, different roles are used (
OrderEntryAppNormal versus
OrderEntryAppSpecial and
OrderEntryAppReporting) to enable the application to perform different functions on behalf of these user classes.
During the matching sequence, each role held by the process is considered, even if a match has already been found. In other words, multiple roles may match and multiple sets of new roles may be added. However, this process is not recursive: roles added as a result of the matching process are not considered for further matches.
Note:
There is no way to restrict a user’s roles to fewer than the login roles.
When a user goes to a new Portal page, the Portal resets the process to have only the user’s login roles. The Portal then checks if the page’s application requires a resource; if it does, then the Portal checks if the user has the appropriate permissions on that resource. If the user’s privileges do not include the required privileges, the page will not be available.
If the user does have the required privileges, the Portal then adds any application roles and any applicable target roles. The Portal then checks if any links on the page require custom resources; if the user has the appropriate resource(s), the Portal displays those links.
Certain routines can directly modify the application roles of a running process by setting the
$ROLES system variable, such as
$ROLES contains a comma-separated list of the role names assigned to the current process. The union of all the privileges granted to all roles in the list determines the privileges that the process possesses.
$ROLES initially contains the roles assigned at authentication (that is,
login roles).
This command can only be invoked either from a routine that is part of the
IRISSYS database or if the current privileges held include Write permission for the
IRISSYS database (
%DB_IRISSYS:W).
Note that setting
$ROLES only alters a process’s added roles, not its login roles. Thus if a process currently has the login roles Employee and Manager and the added role
Payroll, after the statement
SET $ROLES = "Accounting"
A role can be added to the process’s current roles by concatenating it to the current roles, with a call such as:
SET $ROLES = $ROLES _ ",Payroll"
The
NEW command can be used with
$ROLES to stack the current set of roles (Login and Added) and the current value of
$USERNAME. This allows code to modify the list and, whether control leaves the containing block normally or abnormally, the changes are undone upon exit.
Content Date/Time: 2019-02-21 00:53:44