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.
For SQL access to data in tables, InterSystems IRIS® data platform supports row-level security. For information on setting this up, see Adding Row-Level Security.
About Roles
Every role has the following properties:
| Property Name | Property Description |
|---|---|
| Name | Unique role identifier. See 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 Roles, Users, Members, and Assignments.
About Role Assignment
InterSystems IRIS also supports various role-assignment mechanisms. A role-assignment mechanism allows you to associate particular roles with particular authenticated users. InterSystems IRIS uses these associations to determine the authorized activities for the user. Each role-assignment mechanism is associated with one or more authentication mechanisms; configuring InterSystems IRIS includes specifying the supported combination(s) of authentication and role-assignment mechanisms.
The available role-assignment mechanisms are:
| Authentication Mechanism | Role-Assignment Mechanisms |
|---|---|
| Delegated authentication (ZAUTHENTICATE) | ZAUTHENTICATE |
| Instance authentication | Native authorization (the primary approach described by this guide) |
| LDAP | LDAP |
| Kerberos | Options of:
|
| Operating System authentication | Options of:
|
For an instance that supports unauthenticated access, all users hold the privileges associated with the UnknownUser and _PUBLIC accounts; these accounts are described in The UnknownUser Account and The _PUBLIC Account respectively.
Regardless of how role assignment occurs, role management — that is, associating particular privileges with particular roles — occurs within InterSystems IRIS.
Maximum Number of Roles
Each instance of InterSystems IRIS can have up to 10,240 roles.
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:
Create 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 Manage Roles. For example, the Resources table allows you to add new privileges to the role; do this by clicking Add.
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.
-
It cannot be the same as an existing username.
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, then you cannot create a role named BASICUSER. References to the BasicUser role using capitalization such as basicuser or BASICUSER will succeed.
Manage 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:
-
Creating, modifying, and removing a role’s privileges. This includes:
-
Creating and removing assignments among roles and users. This includes:
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.
View 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 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.
Give 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).
Modify 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.
Remove 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.
Assign 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.
Remove 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 Remove 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.
Assign 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.
Remove 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 Remove 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.
Modify 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 VIEW command.
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:
-
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:
-
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 System Explorer, 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 Secure Debug Shell.
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.
| Resource | %Developer | %Manager | %Operator | %SQL | %SecureBreak |
|---|---|---|---|---|---|
| %Admin_Manage | Use | ||||
| %Admin_Operate | Use | Use | |||
| %Admin_Secure | Use | ||||
| %Admin_Task | Use | ||||
| %DB_IRISLOCALDATA | 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 | ||
| %System_Native | 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.
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.
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 Adding Row-Level Security.
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.
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 Manage 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.
Escalation Roles
InterSystems IRIS supports user based escalation roles. Escalation roles are roles that are temporarily assigned to a user. They are designed to implement a clear separation between regular user privileges and administrative privileges on InterSystems IRIS. This approach minimizes the risk associated with providing continuous administrative access to users. Regular users have the ability to perform certain tasks and privilege escalation occurs selectively when required.
Escalation roles allow a user to maintain one set of credentials for their default limited privilege account and escalate privileges without the need to log out and back in with a separate administrative user account. This adheres to the security principle of least privilege, ensuring that users are granted only the minimum level of access necessary to accomplish specific tasks. Additionally, it increases visibility into audit events as shared credentials are reduced. You can attribute events to specific users using escalation roles to accomplish tasks instead of not knowing which specific user is using the shared administrative account.
Escalating to a different role replaces a user’s original role or roles and all associated privileges and permissions. For the duration of the escalation session, the user only has the privileges and permissions of the escalated role. See the graphic below for an overview of the escalation role process.
Configuring Escalation Roles
You can configure escalation roles for a user using the management portal or the ^SECURITY routine in the terminal. Configuration includes assigning specific roles that a user can escalate to as well as the system wide timeouts for role escalation. See Using Roles for more details on assigning roles.
You can configure the length of time in seconds before the escalation session expires in the Escalated Login Timeout field. The default value is 300 seconds. After this timeout period, you must reauthenticate to maintain the escalation role.
In the Escalated Authentication Timeout field, you can configure the length of time in seconds during which you can escalate to new roles freely. The default value is 0 seconds, meaning that you must always authenticate when you escalate roles. If you set this value to 300 seconds, for example, then you can escalate from one escalated role to another, without needing to reauthenticate, until you reach the timeout. If you de-escalate to your original role, you will need to reauthenticate before escalating again even if 300 seconds has not passed.
These two timeouts only apply to Terminal escalation. For web services, including the Management Portal, the timeout is effectively the session timeout.
Using the Management Portal
To configure escalation roles using the management portal, go to System > Security Management > Users and select the user you wish to have an escalation role. There is a tab labeled EscalationRoles where you can assign roles that the user can escalate to.
You can configure timeouts for the role privilege escalation in System > Security Management > System-wide Security Parameters > (security settings).
Using ^SECURITY
To configure escalation roles using the ^SECURITY routine, follow the steps below.
-
Open the Terminal and authenticate as a sufficiently privileged user.
-
At the terminal prompt, change to the %SYS namespace:
>zn "%SYS" -
Run ^SECURITY:
%SYS>do ^SECURITY -
In ^SECURITY, select option 1) User setup. This presents you with different options for managing users. To edit a user, select option 2) Edit user.
-
Follow the prompts to enter details about the user configuration. It will prompt to keep any escalation roles currently assigned before prompting to add an escalation role.
See Using Roles for more details on assigning roles.
You can configure timeouts for the role privilege escalation in ^SECURITY. To do so, follow the below steps:
-
In ^SECURITY, select option 12) System parameter setup. This presents different options for system security settings.
-
To edit the timeouts for role escalation, select option 1) Edit system options then follow the prompts to change the settings.
Using Escalation Roles
You can escalate roles in the Terminal, the management portal (and other CSP-based web applications), and in REST applications. The user must have %Service_EscalateLogin:U privileges in order to use escalation roles.
You can use any authentication mechanism when escalating to a new role; however, it must be the same authentication method you use for the management portal or Terminal. For example, if you authenticate to the Terminal with password authentication, the escalation role prompts for your password. Similarly, if you authenticate with OS authentication, it uses OS authentication. The authentication method must be enabled as an allowed authentication method in %Service_EscalateLogin. See Services for more details.
With the Terminal
To use an escalation role in the Terminal, first open a session and authenticate with a user that has an escalation role configured. At the terminal prompt, enter $System.Security.EscalateLogin(RoleName, Password). RoleName and Password are optional; if omitted you are prompted to select an available role and then for the user’s password. As a shorthand, you can enter zsu and the session prompts for an available role and then for the user’s password.
Alternatively, you can use zsu:
USER>do $System.Security.EscalateLogin("PrivilegedRole", "<password>")
USER>zsu "PrivilegedRole"
Escalated Login for User: UserA (Role: PrivilegedRole)
Password: <password>
USER (PrivilegedRole)# exit
USER>
The below graphic demonstrates the above example using zsu:
You must reauthenticate using the same method you initially authenticated with when starting the terminal session.
After the escalation timeout period passes, the terminal screen session locks and you must reauthenticate to continue using the terminal.
The session remains in the escalated state until you exit the escalated state; if the session times out, you are prompted to reauthenticate. To exit the escalated state, enter at the terminal prompt: exit, quit, or simply q.
InterSystems IRIS does not support command-line debugging with role escalation. The debugger is disabled in an escalated state.
With the Management Portal
To use an escalation role in the management portal, navigate to the homepage. At the top of the page is information about the instance and user session. As long as the user has at least one assigned escalation role, this will include a section for Escalation Role. On first login, this value is (none). You can click the value and it presents a window for you to select which escalation role you wish to change to. You must authenticate to use the escalation role.
The session remains in the escalated state until the session times out or you remove the escalated role. To remove the escalation role and de-escalate to your regular role, click (Remove) next to the value of Escalation Role.
With Web Applications
For services using CSP Sessions, including CSP and REST web applications, the functionality of escalation roles is similar to that of the management portal. You can call %Session.EscalateLogin(Role, Password) in your application to assume a given permitted role. To remove the escalated state and restore the application’s previous roles, you can call %Session.ClearEscalation().
For services using token authentication, see JWT Authentication for more details.
JDBC and ODBC Client Connections
InterSystems IRIS does not support role escalation for JDBC and ODBC client connections. You can control the permissions for client applications and users with SQL privileges and stored procedures.
Auditing Escalation Roles
You can configure audit events for escalation role usage. If configured, you can see Login, LoginFailure, and Logout events for %Service_EscalateLogin. Replacing an existing escalation role session results in a Logout of the old role and a Login for the new role. Additionally, DirectMode audit events include commands executed from the escalated terminal session. In all audit events, the escalated role is available in the user’s current Role field.
See Auditing for more information.
