Roles

docs.intersystems.com

Home / Security Features of InterSystems IRIS / Security Administration Guide / Roles

Security Administration Guide

Roles

InterSystems: The power behind what matters

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:

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.

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:

From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
On the Roles page, click Create New Role. This displays the Edit Role page.
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.

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:

It can include all alphanumeric characters.
It can include symbols, except for the following prohibited characters: “,” (comma), “:” (colon), and “/” (slash).
It cannot begin with “%” (the percent-sign character), which is reserved for InterSystems IRIS predefined roles.
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.

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:

General tasks. This includes:
- Viewing Existing Roles
- Deleting a Role
Creating, modifying, and removing a role’s privileges. This includes:
Creating and removing assignments among roles and users. This includes:
Modifying a Role’s SQL-related Options

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:

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

For each role, you can

Edit the role’s properties, which includes all actions for privilege management, assignment management, and SQL-related options.
Delete the role

Deleting a Role

To delete a role:

On the Roles page (System Administration > Security > Roles), for the role you wish to delete, click Delete in that role’s row.
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:

On the Edit Role page (System Administration > Security > Roles > Edit Role) for an existing role, click Add in the Privileges table.
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).

Modifying Privileges for a Role

To modify the privileges that a role holds:

From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
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.

Removing Privileges from a Role

To remove privileges from a role:

From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
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.

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:

From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
On the Edit Role page, select the Members tab.
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.

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:

From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
On the Edit Role page, select the Members tab.
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.

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:

From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
On the Edit Role page, select the Assigned To tab.
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.

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:

From the Management Portal home page, go to the Roles page (System Administration > Security > Roles).
On the Roles page, click Edit for the role you wish to modify. This displays the Edit Role page.
On the Edit Role page, select the Assigned To tab.
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.

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:

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.

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:

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:
- ALTER
- DELETE
- INSERT
- REFERENCES
- SELECT
- UPDATE
- 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.

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:

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:
- ALTER
- DELETE
- INSERT
- REFERENCES
- SELECT
- UPDATE
- 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.
Below this window, click Add, which displays the Grant procedure privilege... dialog.
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).

Predefined Roles

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.
%SecureBreak — The %Secure_Break:Use privilege, which enforces use of the secure debug shell. For more information on the secure debug shell, see the “The Secure Shell” section in the “System Management and Security” chapter.

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.

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.