Using Resources to Protect Assets
Authorization protects InterSystems IRIS® data platform components from inappropriate use. InterSystems uses the following terminology when discussing these components:
-
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.
-
Resources protect assets. 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 example, a variety of system management functions are protected by a single resource.
Each instance of InterSystems IRIS can have up to 10,240 resources.
-
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 Privileges and Permissions.
This topic addresses issues related to resources and the assets that they protect. InterSystems IRIS includes a set of resources for assets that it protects — and provides access for users based on the rights that they hold. You can also define your own resources.
Types of 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 System Resources.
These resources are %Admin_ExternalLanguageServerEdit, %Admin_Journal, %Admin_Manage, %Admin_OAuth2_Client, %Admin_OAuth2_Registration, %Admin_OAuth2_Server, %Admin_Operate, %Admin_RoleEdit, %Admin_Secure, %Admin_Task, %Admin_UserEdit, %Development, %DocDB_Admin, %IAM, %System_Callout, %System_Attach, and %Secure_Break.
-
Database resources — For controlling read and write access to InterSystems IRIS databases. For more information on these resources, see Database Resources.
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.
-
Gateway resources — For controlling access to external language servers. For more information on these resources, see Gateway Resources.
The gateway resources for a newly installed InterSystems IRIS instance are %Gateway_Object, %Gateway_SQL, and %Gateway_ML.
-
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 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 Services.
The service resources are %Native_ClassExecution, %Native_Concurrency, %Native_GlobalAccess, %Native_Transaction, %Service_CallIn, %Service_ComPort, %Service_Console, %Service_DocDB, %Service_EscalateLogin, %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 Application Resources. For information on creating these resources, see Create or Edit a Resource.
System Resources
InterSystems IRIS comes with a set of built-in resources that govern actions in relation to the installed InterSystems IRIS instance. System resources include:
System resources also include the resources associated with resource-based services. For more details on services, see Services.
Administrative Resources
The administrative resources are:
Privileges on %Admin_* resources allow users to carry out administrative functions without having any database privileges (%DB_<database-name>:R/W). For example, a user such as a system operator with the %Admin_Operate:Use privilege can perform backups without holding privileges on any of the databases being backed up. This is because there is no reason for the operator to have access to the contents of databases other than through applications such as the InterSystems IRIS database backup system.
%Admin_ExternalLanguageServerEdit
This resource controls the ability to create, modify, or delete an external language server (also known as a gateway), including changing the gateway resource associated with it and using the methods in the %SYSTEM.java.SQL and %SYSTEM.python.SQL classes.
This resource takes the Use permission.
By default, the %Manager role holds the %Admin_ExternalLanguageServerEdit:USE privilege.
%Admin_Journal
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.
This resource takes the Use permission (not Read or Write).
%Admin_Manage
This resource controls multiple sets of privileges:
-
It controls access to various pages in the Management Portal, including the System Administration page.
-
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.
-
This resource takes the Use permission.
%Admin_OAuth2_Client
This resource controls configuration settings for using InterSystems IRIS as an OAuth2 client. It allows users to access the System > Security Management > OAuth 2.0 Client page in the management portal. From this page, you can set the OAuth2 authorization server for InterSystems IRIS to use as a client. Once you set the authorization server, you can create a client configuration. See Using InterSystems IRIS as an OAuth 2.0 Client for more details.
%Admin_OAuth2_Registration
This resource controls creating, reading, updating, and deleting of client configurations when you use InterSystems IRIS as an OAuth2 authorization server. You can access the management portal page for the client configurations at the below URL, using the <baseURL> for your instance.
https://<baseURL>/csp/sys/sec/%25CSP.UI.Portal.OAuth2.Server.ClientList.zen
It also allows users to access the System > Security Management > OAuth 2.0 Administration — (security settings) page in the management portal. From this page, you can revoke tokens for a specific user.
%Admin_OAuth2_Server
This resource controls configuration settings for using InterSystems IRIS as an OAuth2 authorization server. It allows users to access the System > Security Management > OAuth 2.0 Authorization Server Configuration — (security settings) page in the management portal. See Using InterSystems IRIS as an OAuth 2.0 Authorization Server for more details.
%Admin_Operate
This resource controls multiple sets of privileges:
-
It controls access to various pages in the Management Portal, including the System Operation page.
-
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).
This resource takes the Use permission.
%Admin_RoleEdit
This resource controls the following privileges:
-
For SQL, it controls the ability to:
-
Create or delete a role.
-
This resource takes the Use permission.
%Admin_Secure
This resource controls multiple sets of privileges:
-
It controls access to various pages in the Management Portal.
-
When working with the RBAC security model, it controls the ability to:
-
Create, modify, or delete a user.
-
Create, modify, or delete a role.
-
Create, modify, or delete application definitions and application resources.
-
Modify audit settings.
-
Modify services.
-
-
For SQL, it controls the ability to:
-
Create, modify, or delete a user.
-
Create, modify, or delete a role.
-
See the privileges granted to a user.
-
See the privileges granted to a role.
-
Revoke SQL privileges that were granted by another user.
-
This resource takes the Use permission.
%Admin_Tasks
This resource’s privileges include the ability to create, modify, or run a task, such as through the Management Portal’s Task Manager (System Operation > Task Manager).
This resource takes the Use permission.
%Admin_UserEdit
This resource controls the following privileges:
-
For SQL, it controls the ability to:
-
Create, modify, or delete a user.
-
This resource takes the Use permission.
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 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 an IDEOpens in a new tab to connect to an InterSystems IRIS server, it must authenticate as a user with the %Development:Use privilege. The user must also have Read or Write privileges on databases that contain code which the user wishes to view or edit. The predefined %Developer role enumerates additional privileges that a user may require to complete all desired tasks using an IDE.
-
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 %IAM Resource
The %IAM resource controls the ability to obtain a license from InterSystems IRIS to run the InterSystems API Manager (IAM).
The %System_Callout Resource
The %System_Callout resource controls access to various tools that perform actions outside of InterSystems IRIS. These include:
-
In ObjectScript, using the $ZF(-100) function, which supports invoking operating system commands from within ObjectScript code. Also see Issuing Operating System Commands, which includes detailed instructions for adding the %System_Callout:Use privilege.
-
At the Terminal, using “!” and “$” as control characters for operating system access. For details, see the $ZF(-100) documentation.
-
In local interprocess communication with ObjectScript, opening an interprocess communications device in Q mode.
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 Secure Debug Shell.
The %Service_Native Resource
The %Service_Native resource is deprecated. Refer to the four %Native_* resources for controlling whether the user can issue Native API calls via Python, Java, .NET, and Node.js. You can find the four Native API resources under %Service_Bindings.
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:
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.
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 SQL Users, Roles, and Privileges.
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:
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
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 routines 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); for a description of this page, see System-wide Security Parameters.
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.SecurityOpens in a new tab class).
-
Invoking the two-argument form of the $SYSTEM.Security.ChangePassword function (which is the ChangePassword method of the %SYSTEM.SecurityOpens in a new tab class). (Note that the new password must conform to the general password constraints described in User Account Properties and the instance-specific password constraints described in the Password Strength and Password Policies.
-
Invoking one of the $ZF functions, which allow you to call non-ObjectScript programs or functions from ObjectScript routines.
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.
Gateway Resources
Gateway resources control access to the external language servers (also known as gateways) provided in InterSystems IRIS. The gateway resources and the types of external language server they are associated with by default are listed in the following:
-
%Gateway_ML — IntegratedML
-
%Gateway_Object — .NET, Java, Python, R, and XSLT
-
%Gateway_SQL — JDBC
These resources take the Use permission.
The %Admin_ExternalLanguageServerEdit resource controls the ability to create, delete, and modify external language servers, including changing the gateway resources associated with them. You can replace the default gateway resource associated with a gateway with a user-defined resource, or remove it without replacing it, in which case it the gateway is public and can be used by anyone.
InterSystems strongly recommends protecting all gateways by associating a gateway 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:
-
Supplementary authorization checking for a Portal page — for more information, see Use Custom Resources with the Management Portal.
-
Authorization checking at a particular point in an application — for more information, see the next section, Create or Edit a Resource.
-
Authorization for the whole of an application
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 Create or Edit a Resource) and use it in association with the application as described in either Edit a Web Application: The General Tab or Edit a Privileged Routine Application, a Client Application, or Document Database Application: The General Tab.
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 Applications.
Create or Edit 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 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 Check the Privileges of a Process 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 case-sensitive, but also prohibit naming as if insensitive. This means that:
-
Names that differ only by case are prohibited.
-
Names are defined using mixed case and the name is preserved exactly as it is entered.
-
When a name is looked up, InterSystems IRIS acknowledges differences in case.
For example, if there is a resource named Accounting, then you cannot create a resource named ACCOUNTING, accounting or any combination of letter casing therein. References to the Accounting resource using capitalization such as accounting or ACCOUNTING do not succeed. If you delete the Accounting resource and subsequently make an accounting resource, references to Accounting fail. You must specify the correct letter casing when referencing a resource.
Use 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:
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.
Define and Apply a Custom Resource to a Page
To define and apply a custom resource, the procedure is:
-
Log in as a user who holds the %Admin_Secure:Use privilege or is a member of the %All role.
-
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.
-
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.
-
Assign the custom resource to the page. To do this:
-
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.
-
At the very bottom of the page’s action pane, click Assign. This displays the Assign Custom Resource dialog.
-
In that dialog, select the desired resource from the Custom Resource Name list and click OK.
-
Remove a Custom Resource from a Page
To disassociate a custom resource from a page, the procedure is:
-
Log in as a user who holds the %Admin_Secure:Use privilege or is a member of the %All role.
-
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.
-
At the very bottom of the page’s action pane, click Assign. This displays the Assign Custom Resource dialog.
-
In that dialog, select the empty item from the Custom Resource Name list and click OK.