docs.intersystems.com
Home / Security Administration Guide / Roles

Security Administration Guide
Roles
Previous section           Next section
 InterSystems: The power behind what matters   
Search:  

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:
Note:
For SQL access to data in tables, InterSystems IRIS™ supports row-level security. For information on setting this up, see the section “Adding Row-Level Security” in the chapter “Other Options for Persistent Classes” in the book Defining and Using Classes.
About Roles
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).
These are displayed on the General tab of the Edit Role page, which is accessible by selecting Edit in the row for any role in the table on the Roles page (System Administration > Security > Roles).
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.
Roles, Users, Members, and Assignments
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:
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.
Suppose one role is assigned to another role. In this case, if role A is assigned to role B, then role A is described as a “member” of role B; this is equivalent to saying that role A is assigned to role B or that role B includes role A.
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.
An Example of Multiple Role Assignment
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:
Creating 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.
To create a new role:
  1. From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
  2. On the Roles page, click Create New Role. This displays the Edit Role page.
  3. On the Edit Role page, the General tab is visible. Here, enter values for the following properties:
    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.
  4. 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.
  5. Click Save to create the role.
Once a role exists, you can edit it as described in the section “Managing Roles.” For example, the Resources table allows you to add new privileges to the role; do this by clicking Add.
Note:
InterSystems recommends that you do not modify predefined roles.
Naming Conventions
The name of a user-defined role is subject to the following rules in its use of characters:
Also, a role name is not case-sensitive. This means that:
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.
Managing Roles
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:
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.
Viewing Existing Roles
To view a list of the currently existing roles, see the Roles page in the Portal (System Administration > Security > Roles). This page displays information on the following fields:
For each role, you can
Deleting a Role
To delete a role:
  1. On the Roles page (System Administration > Security > Roles), for the role you wish to delete, click Delete in that role’s row.
  2. InterSystems IRIS displays a confirmation dialog. Click OK to delete the role and Cancel otherwise.
Giving New Privileges to a Role
To give a role new privileges:
  1. On the Edit Role page (System Administration > Security > Roles > Edit Role) for an existing role, click Add in the Privileges table.
  2. 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.
  3. 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).
Modifying Privileges for a Role
To modify the privileges that a role holds:
  1. From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
  2. On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
  3. On the Edit Role page, in the Resources table, click Edit for the resource whose privileges you wish to modify.
  4. 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.
  5. Click Save to save the privileges in their new state.
These changes should be reflected in the Resources table on the Role page.
Removing Privileges from a Role
To remove privileges from a role:
  1. From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
  2. On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
  3. On the Edit Role page, in the Resources table, click Delete. This removes the privileges for the resource from the role.
  4. Click Save to save the privileges in their new state.
Assigning Users or Roles to the Current Role
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.
The role being edited is known as the “current” role. The users and roles that are assigned to the current role are listed on the Members tab of the Edit Role page (these users and roles are known as its members).
To assign a user or role to the current role, the procedure is:
  1. From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
  2. On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
  3. On the Edit Role page, select the Members tab.
  4. 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.)
  5. 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.
  6. 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.
Removing Users or Roles from the Current Role
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:
  1. From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
  2. On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
  3. On the Edit Role page, select the Members tab.
  4. 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.
  5. A prompt appears to confirm the removal. Click OK.
The user or role has now been removed from the current role.
Assigning the Current Role to Another 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.
The role being edited is known as the “current” role. The roles to which the current is assigned are listed on the Assigned To tab of the Edit Role page.
To assign the current role to another role, the procedure is:
  1. From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
  2. On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
  3. On the Edit Role page, select the Assigned To tab.
  4. 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.
  5. 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.
Removing the Current Role from Another Role
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:
  1. From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
  2. On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
  3. On the Edit Role page, select the Assigned To tab.
  4. 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.
  5. A prompt appears to confirm the removal. Click OK.
The current role has now been removed from that role.
Modifying a Role’s SQL-Related Options
For every role, you can grant or remove the following SQL-related characteristics:
General SQL Privileges
On the SQL Privileges tab of the Edit Role page, you can add or remove SQL privileges for a role:
The following privileges are available:
Privileges for Tables
On the SQL Tables tab of the Edit Role page, you can add or remove table-related SQL privileges for a role:
  1. Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s tables appears.
  2. To change privileges for a table, click Edit in that table’s row. This displays a window for altering privileges.
  3. In this window, you can check or clear any of the following items:
  4. 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.
Privileges on Views
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:
  1. Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s views will appear.
  2. To change privileges for a view, click Edit in that view’s row. This displays a window for altering privileges.
  3. In this window, you can check or clear any of the following items:
  4. 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:
  1. Choose the relevant namespace from the drop-down near the top of the page. A list of the namespace’s stored procedures then appears.
  2. Below this window, click Add, which displays the Grant procedure privilege... dialog.
  3. 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.
  4. 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.
  5. 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.
  6. 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).
Predefined Roles
InterSystems IRIS includes a number of predefined roles. These include:
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.
%All
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.
Important:
A user who is assigned to the %All role does not automatically have access to rows in a table that are protected with row-level security. The application must explicitly provide the %All role with access to such a row. For detailed information about how to do this, see the section “Adding Row-Level Security” in the chapter “Other Options for Persistent Classes” in the book Defining and Using Classes.
Default Database Resource Roles
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.
Login Roles and Added Roles
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.
Matching Role Added Roles
OrderEntryUser OrderEntryAppNormal
OrderEntryManager OrderEntryAppSpecial, OrderEntryAppReporting
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.
A Note on Added Roles and Access in the Management Portal
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.
Programmatically Managing Roles
Certain routines can directly modify the application roles of a running process by setting the $ROLES system variable, such as 
 SET $ROLES = "Payroll"
$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"
$ROLES has the value “Employee,Manager,Payroll,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 statement
 SET $ROLES = ""
removes all added roles.
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.
With the exception of a null string argument, SET $ROLES = <role_name> is a system capability. NEW $ROLES and SET $ROLES = "" can be executed by any code.

Previous section           Next section
View this book as PDF
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-02-21 00:53:44