Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.3 / Application Development / Security Administration Guide / Assets and Resources
Previous section   Next section

Assets and Resources

Once a user has authenticated, the available resources are determined by the authorization facilities in InterSystems security. Authorization protects InterSystems IRIS™ components from inappropriate use, and involves the following concepts:
  1. An asset is something that is protected. For instance, an InterSystems IRIS database is an asset, the ability to connect to InterSystems IRIS using SQL is an asset, and the ability to perform a backup is an asset.
  2. Assets are protected via resources. Sometimes there is a one-to-one correspondence between assets and resources, that is a single asset (such as a database) is protected by one resource. In other cases, multiple assets are protected by a single resource, in order to simplify security management. For instance, a variety of system management functions are protected by a single resource.
  3. A privilege grants permission to do something with one or more assets protected by a resource, such as being able to read the orders database. A privilege is written as a resource name followed by a permission separated by a colon, such as:
    %DB_Sales:Read
    
    For more information on privileges, see the chapter “Privileges and Permissions.”
InterSystems IRIS includes a set of resources for assets that it protects — that is, to which it provides access for users based on the rights that they hold. You can also define your own resources.
This chapter addresses issues related to resources and the assets that they protect. Topics include:

About Resources

There are multiple resource types:
  • System Resources — For controlling the ability to perform various actions for an InterSystems IRIS instance. For more information on these resources, see the “System Resources” section of this chapter.
    These resources are %Admin_Journal, %Admin_Manage, %Admin_Operate, %Admin_Secure, %Admin_Task, %Development, %DocDB_Admin, %Secure_Break, and %System_Callout.
  • Database Resources — For controlling read and write access to InterSystems IRIS databases. For more information on these resources, see the “Database Resources” section of this chapter.
    The database resources for a newly installed InterSystems IRIS instance are %DB_IRISLOCALDATA, %DB_IRISAUDIT, %DB_IRISLIB, %DB_IRISLOCALDATA, %DB_IRISSYS, %DB_IRISTEMP, %DB_ENSLIB.
  • Service Resources — For controlling the ability to connect to InterSystems IRIS using various InterSystems connection technologies. For more information on these resources and the functionality that they control, see the chapter “Services.”
    Not all services have associated privileges — only those services for which InterSystems IRIS provides user-based access; other services, such as data check, are not user-based and, as a result, do not have associated security resources. For more information on managing services, see the chapter “Services.”
    The service resources are %Service_CallIn, %Service_ComPort, %Service_Console, %Service_DocDB, %Service_Login, %Service_Object, %Service_SQL, %Service_Telnet, %Service_Terminal, and %Service_WebGateway.
  • Application Resources — Either for controlling the whole of a user-defined application or for perform authorization checks anywhere in user code. For information on these resources generally, see the “Application Resources” section of this chapter. For information on creating these resources, see the “Creating or Editing a Resource” section of this chapter.

System Resources

InterSystems IRIS comes with a set of built-in resources that govern actions in relation to the installed InterSystems IRIS instance. (These were formerly known collectively as the administrative and development resources.) System resources include:
System resources also include the resources associated with resource-based services. For more details on services, see the “Services” chapter.

Administrative Resources

If you receive privileges involving an administrative resource, then you can perform designated InterSystems IRIS systems administration tasks. Their associated permission is Use — Read and Write are not relevant for them.
%Admin_Journal
Having the Use permission on this resource allows users to set and clear the no-journaling process flag via the DISABLE^%SYS.NOJRN and ENABLE^%SYS.NOJRN entry points, respectively, in programmer mode in the Terminal. This resource allows you to establish users who can perform this action without having to give them the Use permission on the %Admin_Manage resource, which might give them more privileges than necessary or desired.
%Admin_Manage
Most visibly, this resource controls access to various pages in the Management Portal. Specifically, it controls the ability to:
  • Create, modify, and delete InterSystems IRIS configurations.
  • Create, modify, and delete backup definitions.
  • Add databases, modify database characteristics, and delete databases.
  • Modify namespace map.
  • Perform database and journal restores.
  • Set and clear the no-journaling process flag via the ENABLE^%SYS.NOJRN and DISABLE^%SYS.NOJRN entry points, respectively, in programmer mode in the Terminal. Note that if you wish for a user to be able to perform this task without other managerial privileges, use the %Admin_Journal resource.
%Admin_Operate
Most visibly, this resource controls access to various pages in the Management Portal. Specifically, it controls the ability to:
  • Start and stop InterSystems IRIS.
  • Examine and terminate processes.
  • Mount and dismount databases.
  • Perform integrity checks.
  • Start, stop, and switch journals.
  • Perform database backups.
  • Examine and delete locks.
  • Examine logs.
  • Start and stop services.
The %Admin_Operate:Use privilege is required to mount a database, either explicitly (such as when using an ObjectScript utility) or implicitly (such as when making a global reference to an un-mounted database).
%Admin_Secure
Most visibly, this resource controls access to various pages in the Management Portal. Specifically, it controls the ability to:
  • Create, modify, delete users.
  • Create, modify, delete roles.
  • Create, modify, delete application definitions and application resources.
  • Modify audit settings.
  • Modify services.
%Admin_Tasks
Most visibly, this resource controls the ability to create, modify, or run a task, such as through the Management Portal’s Task Manager (System Operation > Task Manager).
Note that users holding privileges on %Admin_* resources can carry out administrative functions without having any database privileges (%DB_<database-name>:R/W). For example, a user (presumably a system operator) holding the %Admin_Operate:Use privilege can perform backups without holding privileges on any of the databases being backed up. This is as it should be, since there is no reason for an operator to have access to the contents of databases other than through applications such as the InterSystems IRIS database backup system.

The %Development Resource

The %Development resource controls access to InterSystems IRIS development facilities and various pages in the Management Portal. Specifically, it controls the ability to:
  • Enter direct mode.
  • Use Studio. The %Development:Use privilege is checked whenever the Studio connects to a server.
  • Use the global, routine, class, table, or SQL capabilities of the InterSystems IRIS system manager utility. (This privilege is also required to call any APIs that provide programmatic access to this functionality.)
  • Use the debugging facilities of InterSystems IRIS, including the BREAK and ZBREAK commands and the debug option of the process display in the InterSystems IRIS system manager utility.
The %Development:Use privilege works in conjunction with database privileges to control developer access to InterSystems IRIS as follows:
  • For Studio, the %Development:Use privilege is checked whenever the Studio connects to a server. In order to connect, the user must have the %Development:Use privilege for the server and be able to read the default globals database for the namespace (that is, have the %DB_<database-name>:R privilege for it). In order to open a routine, class or other definition, the user must have the Read privilege for the database in which it is stored (which may or may not be the default routines database). In order to compile or save a definition, the user must have the Write privilege for that database.
  • For the global, routine, or class capabilities of the InterSystems IRIS system manager utility, the user must have the Read or Write privileges for the database to access or modify globals.
  • For the SQL capabilities of the InterSystems IRIS system manager utility, the user must have the appropriate SQL privileges for the tables, views, stored procedures, or other SQL assets. If you have some form of SQL access to a table in a database, you are also granted Read or Write access to that database.
To debug an InterSystems IRIS application, you need no specific database privileges. If you hold the %Development:Use privilege for the system, you can set a breakpoint in any routine stored in any database on that system. However, you must have the Read privilege for a database to:
  • View routine source via the debugger
  • Execute a routine

The %DocDB_Admin Resource

The %DocDB_Admin resource controls the ability to manage a document database application. For more information on this feature, see the Using Document Database guide.

The %System_Callout Resource

The %System_Callout resource controls access to various tools that perform actions outside of InterSystems IRIS. These include:
Note:
%System_Callout also controls interactions with the deprecated $ZF(-1) and $ZF(-2) functions.

The %Secure_Break Resource

The %Secure_Break resource enforces the use of the secure debug shell, which restricts programmer access at a <BREAK> prompt. For more information on the secure debug shell, see the “The Secure Shell” section in the “System Management and Security” chapter.

Database Resources

Database resources control access to the contents of InterSystems IRIS databases. The name of the database resource that governs access to a database is stored in the label block of that database.
All database resource names must start with the string “%DB_” and, for custom resources, the first character after the underscore should not be the percent sign. The default database resource name is %DB_<database-name>. You can change the resource name assigned to a database by using the Management Portal.

Database Resource Privileges

The available database privileges are:
Database Privileges
Permission Enables
Read Data access and routine execution
Write Modification and deletion of data (including executable code)
Read and Write permissions provide access to all contents of a database, including source and executable code as well as data. InterSystems security management utilities automatically grant the Read permission for any database resource where there is Write access.
Database privileges do not enable protection of individual items, such as routines or globals, within a database. Rather, the same protection is applied to all items of a resource within a database. You can establish higher granularity of protection by storing globals and routines in separate databases. InterSystems IRIS namespace mapping allows you to do this without any application-level modifications.
Note:
SQL security grants table-level access, specifying which particular action can be performed, such as SELECT or UPDATE. For more information on SQL and security, see the chapter “SQL Security.”

Shared Database Resources

Often, there is a one-to-one correspondence between databases and the resources used to protect them. For instance, protection for the IRISSYS database is specified using the %DB_IRISSYS resource. However, this is not a requirement and, when several databases share the same security definitions they can share the same security resource.
Consider a sales application with three databases. Rather than define access for each of these individually, the system manager has the choice option to:
  1. Create a new database resource, such as %DB_SALES.
  2. Assign this resource to the three databases.
  3. Specify suitable access to %DB_SALES which then governs access to all three databases.

Default Database Resource

When mounting an existing database that has no database resource name, InterSystems IRIS assigns the default resource, %DB_%DEFAULT, to the database. By default, %DB_%DEFAULT has the following permissions:
%DB_%DEFAULT Privileges
Role Permissions
%Developer Read, Write
%Manager Read, Write
While you can change the privileges associated with %DB_%DEFAULT resource, you cannot delete the %DB_%DEFAULT resource itself, since it must be available if an unnamed database is mounted.

Unknown or Non-Valid Resource Names

With one exception (see below), if you attempt to mount a database that has an unknown or invalid database resource name, the attempt fails. (This might occur if a database were moved from one InterSystems IRIS instance to another.) An automatic mount attempt fails with an error and an explicit mount attempt prompts you with the choice of creating the resource named in the database label or changing the database to use a valid resource.
The one exception to this rule is that a user who is a member of the %All role can mount a database that does not have a resource (such as if its resource was deleted or the database was previously on a different system).

Namespaces

Users and applications interact with InterSystems IRIS databases through namespaces. While there are no privileges associated with namespaces, access to a namespace is granted or denied based on the privileges associated with the underlying databases. More specifically, to access a namespace, you must hold the Read privilege on the default globals database associated with that namespace. This requirement is checked when:
  • A process attempts to change to a different namespace, such as by using the $NAMESPACE special variable, the ZNSPACE command, or the %CD utility
  • There is an attempt to connect to InterSystems IRIS using any service that connects to a namespace, such as an SQL connection or an object connection
Note:
This requirement is not checked when a global or routine reference is made, implicitly or explicitly, to a namespace.
The fact that namespace privileges depend on privileges for the underlying databases can lead to unexpected behavior. For example, suppose that namespace NSCust refers to data in three databases: DBCust1, DBCust2, and DBCust3. Suppose also that the role AverageUser has the privileges %DB_DBCust1:R and %DB_DBCust3:R. Because the role has no privilege associated with DBCust2, any attempt to access data in that database fails (including if it is through the namespace).

IRISSYS, the Manager’s Database

InterSystems IRIS ships with a database that provides a repository for administrative routines and globals. This is the IRISSYS database, and is sometimes known as the manager’s database.
Within this database, there are groups of globals and routines whose names begin with the percent sign (these are often known as “percent globals” or “percent routines”). These globals and routines have a special role in the management of an InterSystems IRIS site and have special rules that apply to them:
  • All users have Read permission for percent routines and percent globals.
    Note that via mappings, it is possible to change where these items are stored, but that has no effect on their visibility. Percent globals and percent globals are always visible in all namespaces.
  • All percent routines have Write permission for all globals located in the same database (percent as well as non-percent). For instance, percent routines in the IRISSYS database have Write access to globals stored in that database, but not to globals in any other database. Simultaneously, percent routines in any other database have implicit Write access to globals stored in that same database but not to percent globals in IRISSYS. This implicit Write permission is only available during normal routine execution. It is disabled if the routine has been modified and it is not available in XECUTE commands or through argument indirection.
  • You can control Write access to percent globals from non-percent routines with the Enable writing to percent globals field on the System-wide Security Parameters page (System Administration > Security > System Security > System-wide Security Parameters); this page is described in the System-wide Security Parameters section of the “System Management and Security” chapter.
Caution:
Do not move, replace, or delete the IRISSYS database.

Special Capabilities

There are special capabilities available to code located in the IRISSYS database. These capabilities are sometimes called “restricted system capabilities.” They are:
  • Invoking protected VIEW commands and $VIEW functions.
  • Using protected class methods.
  • Modifying the roles of a process with a SET $ROLES = ... call.
  • Invoking the single-argument form of the $SYSTEM.Security.Login function (which is the Login method of the %SYSTEM.Security class).
  • Invoking the two-argument form of the $SYSTEM.Security.ChangePassword function (which is the ChangePassword method of the %SYSTEM.Security class). (Note that the new password must conform to the general password constraints described in “Properties of Users” section of the “Users” chapter and the instance-specific password constraints described in the “Password Strength and Password Policies” section of the “System Management and Security” chapter.
Note:
You need no database privileges to read or write database blocks with the VIEW command.
The only code that can perform these actions is:
  • Routines stored in the IRISSYS database, but only during “normal” routine execution. They are disabled if a ZINSERT into the current routine has modified the routine, and they are also not available in XECUTE commands or through argument indirection.
  • Processes with the Write permission on the %DB_IRISSYS resource.

Application Resources

InterSystems IRIS supports several forms of custom authorization, all of which depend on user-defined resources, known as Application resources. These include:
For the whole of an application, InterSystems IRIS allows you to create an application definition associated with a user-defined application (which itself is defined as a named entity composed of executable code). Application resources then allow you to perform authorization checking for the application. There are several types of applications:
  • Web application definitions
  • Privileged Routine application definitions
  • Client application definitions
  • Document database definitions
Application resources provide a means of controlling access to applications. To use this feature, create a custom resource as described in the next section, “Creating or Editing a Resource” and use it in association with the application as described in either the “Editing a Web Application: The General Tab” or “Editing a Privileged Routine Application, a Client Application, or Document Database Application: The General Tab” section of the “Applications” chapter.
For example, if a web application has an associated resource, then users can only run the application if they have Use permission on the resource. If an application uses other resource-regulated entities, such as databases, then users must also have appropriate permissions on those resources in order to operate the application effectively. For more information on applications, consult the “Applications” chapter.

Creating or Editing a Resource

To create a new resource, on the Resources page (System Administration > Security > Resources), click Create New Resource.
To edit an existing resource, on the Resources page (System Administration > Security > Resources), click the Edit button to the right of the resource you wish to edit.
This displays the Edit Resource page. The Edit Resource page has fields for the following:
  • Resource Name — The string by which the resource is identified. For more information on resource names, see the section “Resource Naming Conventions.” When creating a resource, this is an editable field; when editing an existing resource, this is a non-editable, displayed string.
  • Description — Optional text related to the resource.
  • Public Permission —
    • Read — When selected, specifies that all users can view this resource.
    • Write — When selected, specifies that all users can view or change this resource.
    • Use — When selected, specifies that all users can run or otherwise employ this resource.
Once you have added a resource, it appears in the table of resources and is of type Application. You can then use it as part of application-specific authorization. See the section “Checking Privileges” in the “Privileges and Permissions” chapter for more information.

Resource Naming Conventions

The names of InterSystems IRIS resources begin with a percent sign character. The names of application-defined resources should not begin with a percent sign character.
Resource names are not case-sensitive. This means that:
  • Names are defined using mixed case and 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.
For example, if there is a resource named “Accounting”. An attempt to create another resource named “ACCOUNTING” will fail. References to the resource using name values of “Accounting”, “accounting”, and “ACCOUNTING” will all succeed.

Using Custom Resources with the Management Portal

By default, the %Admin_Manage, %Admin_Operate, %Admin_Secure, and %Development system resources control access to the Management Portal. As a supplement to these that allows for more granular Portal security, you can associate an additional custom resource with each Portal page. If a Portal page has an associated custom resource, then the user must hold both the system and custom resource for the page in order to view that page.
For example, access to the Lock Table page requires the %Operator role. You can also associate a custom resource (for example, called MyLockTable) with the Lock Table page; once you have created this association, a user must both be a member of the %Operator role and also have the MyLockTable:Use privilege in order to view the Lock Table page. With this arrangement, the %Operator role grants access to fewer pages than in an instance with default settings, and you can define a new role that can view the Lock Table page and all the other pages to which %Operator role grants access. You can also create multiple custom resources, so that various roles would have access to various subsets of what a predefined role would have available by default.
This section describes:
Important:
Because there can be complex interactions among the various pages, resources, and roles, system administrators should plan carefully before implementing custom resources for the Management Portal.

Defining and Applying a Custom Resource to a Page

To define and apply a custom resource, the procedure is:
  1. Log in as a user who holds the %Admin_Secure:Use privilege or is a member of the %All role.
  2. Create the custom resource. To do this, on the Resources page (System Administration > Security > Resources), click Create New Resource. When creating the resource, make sure that you properly set its public permissions according to the instance’s needs.
  3. Associate the privilege to use the custom resource with a role. For an existing role, on the Roles page (System Administration > Security > Roles), simply add the privilege to the role; alternately, (also on the Roles page), create a new role and then add the privilege to it immediately after creating it. Either way, the privilege consists of the custom resource and the Use permission.
  4. Assign the custom resource to the page. To do this:
    1. Use the finder feature of the Portal to select the page. Note that clicking on the name of the page takes you directly to that page; click inside the box (but not on the name itself) to display the page’s action pane.
    2. At the very bottom of the page’s action pane, click Assign. This displays the Assign Custom Resource dialog.
    3. In that dialog, select the desired resource from the Custom Resource Name list and click OK.

Removing a Custom Resource from a Page

To disassociate a custom resource from a page, the procedure is:
  1. Log in as a user who holds the %Admin_Secure:Use privilege or is a member of the %All role.
  2. Use the finder feature of the Portal to select the page. Note that clicking on the name of the page takes you directly to that page; click inside the box (but not on the name itself) to display the page’s action pane.
  3. At the very bottom of the page’s action pane, click Assign. This displays the Assign Custom Resource dialog.
  4. In that dialog, select the empty item from the Custom Resource Name list and click OK.
Previous section   Next section