Skip to main content

Applications

Applications are the primary way that most users interact with InterSystems IRIS® data platform — and application security provides a key set of tools for regulating user access and user actions. Application security uses InterSystems authorization tools to ensure that only the appropriate users can use an application. An application can also escalate its users’ privileges.

This topic covers the following topics:

Applications, Their Properties, and Their Privileges

From a security standpoint, an application:

  • Is an entity that allows users to perform actions

  • Is associated with one or more resources

  • Has properties that govern its behavior

  • Can enhance its users’ privileges while they are running it

  • Can include programmatic privilege checks

All these characteristics and capabilities are part of the InterSystems authorization tools, which manage how an application and its users can interact with InterSystems products and other security resources. There are several kinds of applications:

This section covers:

Applications and Their Properties

Applications allow you to specify a set of permitted actions, such as reading from and writing to databases or using other assets. To do this, InterSystems IRIS supports what is called an application definition, which is a set of information that represents the application within InterSystems IRIS. (The relationship of an application definition to an application is analogous to that of the relationship of a resource to an asset.) By establishing an application definition, you can control and manage the application.

Important:

Applications and application definitions are frequently referred to interchangeably. The distinction is only important in settings where the executable code or user experience of that code differs from the representation of that code within InterSystems IRIS. The former is the application itself and the latter is the application definition.

Each application, through its application definition, has the following properties:

Name

The name of the application. This must start with a forward slash (“/”) and must be followed by an alphanumeric or any of the following characters:

/ , - , _ , . , or %.

The application definition’s name is independent of the name of any resource.

Description

A description of the application.

Enabled

A switch that specifies if the application is available for use. If the application is not enabled, no one can run the application — not even a member of the %All role. For more details on how this property governs each kind of application, see the appropriate section: Web Applications, Privileged Routine Applications, or Client Applications.

Resource

A resource that manages application behavior. The resource has different effects for different application types: for web applications and client applications, it controls whether or not users have access to the application; for privileged routine applications, it controls the application’s privilege escalation. If a web or client application has no resource, then any user can run the application; if a privileged routine application has no resource, then the application escalates privileges for any user.

Each application definition can only be associated with a single resource. For more details on how this property affects each kind of application, see the appropriate section: Web Applications, Privileged Routine Applications, or Client Applications. For more information on how applications interact with resources, see Associating Applications with Resources.

Application Roles

One or more roles to which application users are assigned. While running the application, the user is assigned to its application roles by appending these roles to the list of roles in the $Roles variable. For more information on using application roles, see Applications and Privilege Escalation.

Matching Roles

One or more roles that cause the user be assigned to some additional roles (called “target roles”) while running the application. If users are assigned to a matching role, then, while using the application, they are also assigned to any target roles. This is done by appending these roles to the list of roles in the $Roles variable. For example, if %Admin_Manage is a matching role, then being a member of that role might cause the application user to also become a member of the target role of %Admin_Secure. For more information on using matching roles, see Applications and Privilege Escalation.

All applications have these properties. Each of the application types also has its own other, unique characteristics.

Associating Applications with Resources

When an application (and therefore its application definition) is a single, unitary whole, it has a single resource — a one-to-one relationship. You can also specify that multiple applications (and therefore multiple application definitions) are associated with a single resource — a many-to-one relationship. For any number of applications, the situation reduces to some combination of these two conditions.

A more complex case is when an application is composed of separate parts, each of which is known as a sub-application. An application made up of a group of sub-applications is designed to behave as a single, unitary whole, while allowing different sub-applications to require different kinds of or levels of security. In this situation, it is useful to give each sub-application its own application definition and to associate it with a separate resource. This way, each sub-application can have its own independent security-related behavior. While, from the application perspective, there are multiple sub-applications that compose the larger application, from the InterSystems security perspective, there are simply multiple, individual applications — each with its own application definition — and users pass among them without knowing it. Again, this reduces to the one-to-one and many-to-one cases, except that the multiple application definitions represent what appears to the end-user as a single application. Because the users have already authenticated and by that process have established their roles, then passing from one sub-application to another requires no authentication.

For example, suppose there is an expense-reporting application where all employees can enter expense reports, but only accounting officers can generate checks. In this case, the application might appear as a single whole and the functionality to generate checks would be grayed out for all employees except the accounting officers. To accomplish this, there would be two separate sub-applications, one for entering reports and another for generating checks. All users would be able to use the former and only accounting officers would be able to use the latter. For them, there would be no visible difference between what might simply appear as two separate screens in a single application.

Applications and Privilege Escalation

Since you can use application resources to escalate a user’s roles, they provide a mechanism for meeting authorization needs that shift dynamically. To perform privilege escalation for an application:

  1. Given an existing application, create a resource and then associate the application with the resource.

  2. Create one or more roles that hold the Use permission for the resource.

  3. Determine the list of privileges that the application requires in order to run. If the application has sub-applications, there may be more than one such list.

  4. Associate each list of privileges with a particular role. Establish each role as an application role for the application or sub-application.

  5. Establish any matching roles for the application or sub-application. Each matching role has one or more target roles associated with it.

  6. When a user successfully invokes an application, InterSystems IRIS performs two actions:

    • For the duration of application use, it assigns the user to any application roles. (For privileged routine applications, this depends on successfully invoking the AddRoles method, as described in Privileged Routine Applications.)

    • If the user is assigned to any matching role, the application assigns the user to any target roles for the duration of application use. (Again, for privileged routine applications, this depends on successfully invoking the AddRoles method, as described in Privileged Routine Applications.)

For example, suppose that an application has its own resource, called AppRsrc. Two roles hold the AppRsrc:Use privilege; these are AppUser and AppOperator. AppOperator is also a matching role, where the target role is %Manager. In this scenario, when a user belonging to the AppUser role invokes the application, the value of $Roles does not change; when a user belonging to AppOperator invokes the application, the value of $Roles expands to include %Manager. If the application has an application role of AppExtra, then a user belonging to the AppUser role receives the AppExtra role when invoking the application. In the first scenario (matching role only), belonging to the AppOperator role causes privilege escalation; in the second scenario (matching role and application role), belonging to either role results in privilege escalation.

User-Based and Application-Based Security

The InterSystems security model allows for flexible privilege assignment that can be user-based, application-based, or both. The use of an application can be limited to specific users or open to any users. For those users authorized to use the application, there can be several behaviors:

  • The application can run with the user’s privileges alone.

  • The application can escalate privileges for only some users (using matching and target roles).

  • The application can escalate privileges for all users (using application roles).

  • The application can escalate some privileges for all users and only escalate other privileges for certain users (using a combination of matching/target roles and application roles).

Hence, you have control of whether application use is limited to specific users or open to any users; simultaneously, you also have control of whether an application runs with the user’s privileges or with its own privileges. This enables InterSystems IRIS to provide a very flexible model:

Protection/Escalation Matrix for Secured Applications
Privilege Level / Protection Level Public Application Restricted Application
With User-Dependent Privileges 1. Any user can run the application. Application runs with user privileges. 2. Only specified users can run the application. Application runs with user privileges.
With Privilege Escalation 3. Any user can run the application. Application runs with (expanded) application privileges through application roles and matching roles. 4. Only specified users can run the application. Application runs with (expanded) application privileges through application roles and matching roles.

Each of the scenarios described in the previous table is commonly used for a different authorization model:

1. Public Application with User-Dependent Privileges

This describes an application available to any authenticated user; when run, the application grants no additional privileges. For example, for a company’s contact database, any user belonging to the company-wide role can get the office phone number and email address for any employee; managers hold greater privileges, which entitle them to view employee home phone numbers; HR staff hold even greater privileges, which entitle them to view and update full records. The application is accessible to all employees, and its behavior depends on privileges that each user already has when invoking it — the application itself grants no roles.

2. Restricted Application with User-Dependent Privileges

This describes an application available only to a user who belongs to a specified role; when run, the application grants no additional privileges. For example, a company may have a payroll application for its hourly employees, which displays the number of hours worked, pay rate, and so on. To run the application, a user has to be a member of either the HourlyEmployee role or the HourlyManager role. Once running, the application checks which role was present: members of HourlyEmployee can see and not edit their own data, while members of HourlyManager can see and edit data for their own reports. An employee who is a member of the HourlyEmployee role can run the application to check the accuracy of personal data; any other employee (such as one on a salary and who is not a member of the required role) cannot even run the application.

3. Public Application with Privilege Escalation

This describes an application available to any authenticated user; when run, the application escalates privileges based on the roles to which the user belongs. (The application can also escalate privileges only for certain roles.) For example, suppose a university has an application where students can review and update their records. Here, any student is an authenticated user and can edit his or her own contact information. To support this functionality, the application includes code for editing an entry; this code checks that the entry being edited matches the authenticated user and, if so, escalates its own privileges to update the record, and then restores the privileges to their previous state. If one student attempts to update another’s record, then the check fails, there is no privilege escalation, and the update does not occur. The application might also check if the user is a member of the registrar’s office role, in which case it would be possible to update information more widely.

4. Restricted Application with Privilege Escalation

This describes an application available only to a user who belongs to a specified role; when run, the application escalates privileges based on the roles to which the user belongs. (The application can also escalate privileges only for certain roles.) For example, a hospital’s emergency room might have an application that grants the attending doctor special, wider privileges for viewing the records of patients currently admitted for emergency care. Because of the potentially critical nature of emergency-room cases, the doctor needs to be able to view more information in this setting than while simply making rounds; hence, the privileges are escalated.

Check for Privileges Programmatically

An application can also include code to check if its users have privileges required to perform a particular action. To do this, use the $SYSTEM.Security.Check method. The syntax of this call is:

 Set status = $SYSTEM.Security.Check(app_resource, app_permission)

where

  • app_resource is the resource for which the user must hold a permission

  • app_permission is the permission that must be held.

  • status is the method’s return value of TRUE or FALSE (1 or 0).

For example, if an application requires a user to have Write permission on the Application_Order_Customer resource, then the Check call would be:

 Set status = $SYSTEM.Security.Check("Application_Order_Customer", "WRITE")
Note:

No privilege is required to call $SYSTEM.Security.Check.

Application Types

There are several types of applications:

Web Applications

These applications connect to InterSystems IRIS using the %Service_WebGateway service.

For web applications, security information is maintained as part of the Web session. That is, the values of $USERNAME and $ROLES are preserved across page requests. (More specifically, when processing begins for a page, $ROLES contains the user’s roles as well as roles defined for the application. It does not contain roles that have been dynamically added during processing of a previous page via SET $ROLES or $SYSTEM.Security.AddRoles. This is true for both stateless and “state-full” sessions.

With Web applications, the client (that is, the browser) typically does not send a username and password to the server when it connects. Instead, the user requests a page and the server responds with a login page that must be completed before the rest of the application can be accessed. If two-factor authentication is enabled, then, once the user has provided a username and password, the server displays a page for entering the security code; if authentication succeeds, the user has access to the application.

Note:

With two-factor authentication, the server always displays the page for entering the one-time security token — even if the username-password pair is not valid. After the user enters the one-time security token, the server displays a message that access is denied, and provides a minimum of information that could be used against the system.

CSP security processing occurs as follows:

  1. As each page request is received, its application is determined from the URL. If the application is not enabled, there is no connection.

  2. If the application is the same as the application for the last page processed for the web session, then there is already a connection, so no further security checking is required.

  3. If the Use permission for %Service_WebGateway is not public and the user does not hold this permission, there is no connection.

  4. If the application or %Service_WebGateway requires authentication and the user has not already been authenticated, then InterSystems IRIS checks if the request includes IRISUsername and IRISPassword parameters:

    1. If IRISUsername and IRISPassword are present, InterSystems IRIS attempts to log in; if the login succeeds, it checks if the user has the Use permission for the application resource. If either of these fail, there is no connection.

    2. If IRISUsername and IRISPassword are not present, InterSystems IRIS displays an application-specific login page, if one is defined in the web application configuration. (This is the only page in a secure application that can be used prior to login.) If there is no application-specific login page, the username and password fail authentication, or the user does not have the Use permission on the application resource, there is no connection.

For information about editing a web application, see:

Also see Secure Custom Web Application Logins.

An Example of Programmatically Escalating Roles in a Web Application

The following example demonstrates how to escalate application roles for a web application. It performs the following actions:

  1. It changes control to the %SYS namespace. This is required to invoke the required calls, because the code for role management and escalation is only available there.

  2. It adds the application’s target roles.

    1. All users receive the MYAPP role. This is because there is no matching role listed before the colon in the line that initially sets the value of matchroles. The syntax is matchrole:targetrole, where an empty value for matchrole means that all users receive targetrole.

    2. It adds the MYAPP2 roles for users who already have the MYAPPSPECIAL role. The syntax here is matchrole1:targetrole1,matchrole2:targetrole2. Hence, if a user has the MYAPPSPECIAL role, then the applications adds the MYAPP2 role. (The leading comma follows the syntax for second and subsequent match and target roles; see the Security.Applications.CreateOpens in a new tab method for more details.)

  3. It uses the local variable that holds role escalation information to update the application’s MatchRoles property. The Security.Applications.ModifyOpens in a new tab method only updates the properties for which it has values; it leaves the others unchanged.

  4. Finally, if role escalation succeeds, announce this.

The code is:

Method UpdateRoles() As %Status {
 // ********************* modify application roles *********************
 write !, "All users receive the added MYAPP role."
 write !, "Users who have MYAPP2 receive MYAPPSPECIAL also."  
 
 // Change to the %SYS namespace.
 new $NAMESPACE
 set $NAMESPACE="%SYS"
 
 // Add roles for the application.
 //
 // Add the MYAPP role for all users.
 set matchroles=":MYAPP"
 // Also add MYAPP2 for users who already have the MYAPPSPECIAL role.
 set matchroles=matchroles_",MYAPPSPECIAL:MYAPP2"
 
 // Use the matchroles variable to 
 // set the applications's MatchRoles property. 
 set MyAppProps("MatchRoles")=matchroles
 set status=##class(Security.Applications).Modify("/csp/MyApp",.MyAppProps)
 
  // Announce success.
  if $$$ISOK(status) {
    write !, "Roles were successfully modified."
 }
}

Privileged Routine Applications

A privileged routine application grants the privilege to escalate roles to one or more classes or routines for the users of those classes or routines. The classes or routines in a privileged routine application are written in ObjectScript. To use a privileged routine application:

  1. Create an application definition in the Management Portal, as described in Create an Application.

  2. Add classes or routines to it, as described in Edit an Application: The Routines/Classes Tab.

  3. Edit the application definition’s classes or routines in your development environment to escalate roles, as described in Escalate Roles in a Privileged Routine Application: The AddRoles Method.

The Portal provides the following pages to edit a privileged routine application (which includes the first two mentioned above):

Escalate Roles in a Privileged Routine Application: The AddRoles Method

To escalate roles in a privileged routine application, invoke the AddRoles method of the %SYSTEM.SecurityOpens in a new tab class. To call AddRoles, the syntax is:

 Set sc = $SYSTEM.Security.AddRoles("AppDefName")

where AppDefName is the name of the application definition and sc is a status code. If a class or routine is part of an application definition and the user is appropriately privileged, then calling AddRoles from that class or routine escalates privileges to include any application roles (as described in “Edit an Application: The Application Roles Tab”) and any relevant matching roles (as described in “Edit an Application: The Matching Roles Tab”).

Important:

If a routine does not use curly braces to delimit code in its entry points, then control can pass from one entry point to another, possibly resulting in overprivileged users and unintended levels of access. For more information on structuring routines, see User-Defined Code.

Processing of the call to AddRoles occurs as follows:

  1. If the call is not from a privileged class or routine, then the call fails.

  2. If the required resource specified in the application definition is not public and the user invoking the method or routine does not have Use permission on this resource, then the call fails.

  3. Otherwise, the call succeeds.

Tip:

To cause the user to give up any application roles and to revert to login roles when control passes out of scope for the routine that escalates privileges, include the following command prior to the call to AddRoles:

 New $Roles

For more information on these topics, see Programmatically Manage Roles.

An Example of Using a Privileged Routine Application

Suppose there is an application that uses a database called DB1. This application’s users hold the %DB_DB1 role only, so they all have privileges for DB1. Some of the application’s users also require temporary access to another database, DB2. Those users get access to DB2 through the PRAEscalate method (“PRA” for “Privileged Routine Application”) of the PRATestClass class, which escalates their privileges; specifically, PRAEscalate adds the %DB_DB2 role, which provides access to DB2.

To enable the PRAEscalate method to add the %DB_DB2 role for the appropriate users, the following security items must exist:

  • A resource called PRATestResource, which is not public.

  • A role called PRA_DB2, which has only one privilege: PRATestResource:Use.

  • The %DB_DB2 role, which was created when the DB2 database was created.

  • A privileged routine application called PRATestApp. Related to PRATestApp:

    • Users must have the PRATestResource:Use privilege to run the PRATestApp application, Therefore, users who require access to the DB2 database must have the PRA_DB2 role (which grants the PRATestResource:Use privilege).

    • The PRATestClass class is part of the PRATestApp application. (To include the class in the application, do so on the Routines/Classes tab of the Edit page for PRATestApp.)

    • The %DB_DB2 role is an application role for PRATestApp. (To specify an application role, do so on the Application Roles tab of the Edit page for PRATestApp.)

Given this setup and two users, PRATestBasicUser and PRATestDB2User:

  • PRATestBasicUser is a member of %DB_DB1 only. Therefore, the PRATestApp application does not escalate PRATestBasicUser’s roles, and the user cannot use the part of the application that requires access to DB2.

  • PRATestDB2User is a member of the %DB_DB1 and PRA_DB2 roles. Therefore, the PRATestApp application does escalate PRATestBasicUser’s roles, and the user can use the part of the application that requires access to DB2.

Here is the code of PRAEscalate:

Method PRAEscalate()
 {
   Write "This method is a part of the privileged routine application ",!
   Write "called PRATestApp.",!
   Write "The user invoking this routine is ",$Username,!
   Write "The current value of $Roles is ",$Roles,!,!
   Write "Calling the AddRoles method...",!,!
   New $Roles
   Set sc = $SYSTEM.Security.AddRoles("PRATestApp")
   If sc = 1
   {
      Write "Application roles have been added.",!
      Write "$Roles now is ",$Roles,!,!
   } Else {
      Write "The call to AddRoles has failed.",!
      Do $system.Status.DecomposeStatus(sc,.Err)
      Write Err(Err),! 
   }
 }

Here is the terminal session where PRATestDB2User runs this routine:

Username: PRATestDB2User
Password: ********
USER>set x = ##class(PRATestClass).PRATest()
This method is a part of the privileged routine application
called PRATestApp.
The user invoking this routine is PRATestDB2User
The current value of $Roles is %DB_DB1, PRA_DB2
 
Calling the AddRoles method...
 
Application roles have been added.
The current value of $Roles is %DB_DB1, %DB_DB2, PRA_DB2 
Removing %DB_DB2 from $Roles...
$Roles now is %DB_DB1, PRA_DB2

USER>

Here is the terminal session where PRATestBasicUser runs this routine:

Username: PRATestBasicUser
Password: ********
USER>set x = ##class(PRATestClass).PRATestMethod()
This method is a part of the privileged routine application
called PRATestApp.
The user invoking this routine is PRATestUser
The current value of $Roles is %DB_DB1
 
Calling the AddRoles method...
 
The call to AddRoles has failed.
ERROR #862: User is restricted from running privileged application PRATestApp 
-- cannot execute.
 
USER>

Client Applications

These are applications that use the client application type to connect to InterSystems IRIS.

Important:

Regarding client applications:

  • They are only supported on Windows. Therefore, options in the Management Portal for these applications are only available on Windows.

  • For setting up their authentication, use the tools described in Authentication.

To edit a client application, the Portal provides the following pages:

Document Database Applications

These are applications that connect to InterSystems IRIS using the document database.

Important:

For applications, use the authentication tools described in Authentication.

To edit a document database application, the Portal provides the following pages:

Create and Edit Applications

This section describes several topics:

Create an Application

To create an application, the procedure is:

  1. In the Management Portal menu, select System Administration > Security > Applications, which displays the different application types.

  2. Choose Web Applications, Privileged Routine Applications, Client Applications, or Doc DB Applications. This displays the page for the selected application type.

  3. In the upper-left corner of the applications page, click the button to create a new application. This displays the application editing page for the selected application type. You can then edit the application as if it already existed using the information in either:

Edit a Web Application: The General Tab

To edit a web application:

  1. In the Management Portal menu, select System Administration > Security > Applications > Web Applications.

    This lists configured web applications. The Type column identifies an application as a user application (CSP) or a system application (CSP,System).

  2. Select an application, click Edit, and enter or change the information.

  3. When finished with edits, restart InterSystems IRIS for the new settings to take effect.

General Settings

The initial section of the General tab displays various options.

Note:

This section does not describe fields exclusively related to CSP/ZEN applications. (If you have migrated a CSP/ZEN application to InterSystems IRIS from another InterSystems product, documentation is available for the relevant fieldsOpens in a new tab.)

Name

An identifier for the application. The name must include a leading slash (/), such as in the /myorg/myapp application.

Note:

Web applications cannot be named /csp/{namespace}/images, /csp/{namespace}/portal, or /csp/{namespace}/deepsee. The name /csp/docbook is reserved.

Description

A text description of the application.

Namespace

The namespace where this application runs. When you select a different namespace, the dialog immediately displays the default application for that namespace to the right of this drop-down menu.

Namespace Default Application

Whether or not the application is the default application for this namespace. The %System.CSP.GetDefaultApp method returns the default application for the namespace. InterSystems IRIS import functions, such as $system.OBJ.Load or $system.OBJ.ImportDir, use the default application when importing a page without an associated application.

Enable Application

Whether or not the application is available for use. When enabled, an application is available, subject to user authentication and authorization; when disabled, it is not available.

Enable REST, WSGI, or CSP/ZEN

The type of web application:

Dispatch Class

(For a REST application) The corresponding custom subclass of %CSP.RESTOpens in a new tab for implementing a REST service. For more information, see Creating a REST Service Manually.

Redirect Empty Path

(For a REST application) Whether the application directs empty paths to /. For example, for application /csp/appname, a request for /csp/appname will be redirected to /csp/appname/.

Use JWT Authentication

(For a REST application) Whether the application supports JSON web token (JWT) authentication.

JWT Access Token Timeout

(For a REST application) The number of seconds until the JWT expires.

JWT Refresh Token Timeout

(For a REST application) The number of seconds until the refresh token for the JWT expires.

Application Name

(For a WSGI application) The name of the file that contains the callable Python application.

Callable Name

(For a WSGI application) The name of the callable application, if it is not the default (application).

WSGI App Directory

(For a WSGI application) The directory that contains the callable Python application.

Security Settings

The security settings are:

Resource Required

A resource for which users must have the Use permission so they can run the application. For information on resources and permissions, see About Resources.

Group by ID

Do not use. This field is for migrated legacy applications only and documentationOpens in a new tab is available for it.

Allowed Authentication Methods

The application’s supported authentication mechanisms. The options available here depend on what is selected on the Authentication Options page (System Administration > Security > System Security > Authentication/Web Session Options). If an application supports multiple authentication mechanisms, authentication occurs as follows:

  • If more than one option is enabled including Unauthenticated, then the user can log in without providing a username and password.

  • If multiple options are enabled and the user enters a username and password, then InterSystems IRIS attempts cascading authentication.

  • If the selected options are Kerberos authentication and instance authentication (password), but Unauthenticated is not selected, then the user must provide a username and password. InterSystems IRIS attempts to perform authentication first using Kerberos and then instance authentication. If either succeeds, the user is authenticated; if both fail, the user is denied access.

For more information, see Authentication.

Permitted Classes

Do not use. This field is for migrated legacy applications only and documentationOpens in a new tab is available for it.

Session Settings

This settings in this section allow you to manage the session properties for a web application.

Important:

To use these settings, you must first set the UseSession parameter of the application’s dispatch class to a non-zero value; otherwise, changes in the value of any of these settings have no effect. For more information, see Creating a REST Service Manually.

The session settings are:

Session Timeout

The default session timeout in seconds. You can override this value using the AppTimeout property of the %CSP.SessionOpens in a new tab object.

Note that if a session changes web applications during its life span, the new application does not uses its default timeout to update the session’s timeout value. For example, if a session starts out in Web Application A, with a default timeout of 900 seconds, and then moves into Web Application B, which has a default timeout of 1800 seconds, the session still times out after 900 seconds.

To cause an application change to update the session timeout value, then, in a session event class, override the OnApplicationChange callback method to add code to update the AppTimeout property of the %session object.

If you disable automatic logouts for Interoperability pages in the InterSystems Management Portal, the session timeout does not apply to those pages. That is, the pages will not time out. Disabling automatic logouts is not recommended. For more information, see Automatic Logout Behavior in the Management Portal.

Event Class

The default name of the class (a subclass of %CSP.SessionEventsOpens in a new tab) whose methods are invoked for web application events, such as a timeout or session termination. To override this value, specify the value of the EventClass property of the %CSP.SessionOpens in a new tab object, using a class name without an extension (such as .cls) as the value.

Use Cookie for Session

Whether or not the application tracks the browser session by using cookies or a URL-rewriting technique that places a value in each URL. Choices are:

  • AlwaysDefault. Always use cookies.

  • Never — Never use cookies.

  • Autodetect — Use cookies unless the client browser has disabled them. If the user has disabled cookies, the application uses URL rewriting.

Note that this option does not set whether an application uses cookies; rather, it controls how the application manages sessions, subject to the user’s preferences. Further, even with values of Always or Autodetect, an application only uses cookies if its code is written to do so.

Session Cookie Path

The portion of the URL that the browser uses to send the session cookie back to InterSystems IRIS for this application. If you do not specify a value for this field, the application uses the value of the Name field with leading and following slashes as its default scope. Hence, for an application named myapp, specifying no value here means that /myapp/ is the scope.

The application only sends the cookie for pages within the specified scope. If you restrict the scope to pages required by a single web application, this prevents other web applications on this machine from using this session cookie; it also prevents any other web application on this web server from seeing the cookie.

Note that a primary application and its subapplications can have different security settings while simultaneously sharing a session cookie (if they all use the primary application’s path).

Session Cookie Scope

Controls the default value of the SameSite attribute for session cookies associated with the web application. For more details, see “About the SameSite Attribute,” below.

User Cookie Scope

Controls the default value of the SameSite attribute for user-defined cookies created with %CSP.Response.SetCookieOpens in a new tab. For more details, see “About the SameSite Attribute,” below.

About the SameSite Attribute

The SameSite attribute determines how an application handles cookies in relation to third-party applications (aka cross-site requests).

The Session Cookie Scope and User Cookie Scope fields allow you to set SameSite for an application’s cookies. Session Cookie Scope sets the value of the attribute for session, login, CSRF, and Group ID cookies; User Cookie Scope sets it for user-defined cookies.

SameSite can have a value of:

  • None — The application sends cookies with cross-site requests. If SameSite has a value of None, browsers may require applications to use HTTPS connections.

  • Lax — The application sends cookies with safe, top-level cross-site navigation.

  • Strict — The application does not send cookies with cross-site requests. (The default for system web applications and new or upgraded user applications.)

To exercise more granular control over an application’s cookies, use the %CSP.Response.SetCookieOpens in a new tab method, which overrides the default SameSite value for a particular cookie. If you use %CSP.Response.SetCookieOpens in a new tab to specify that a cookie has a SameSite value of None, then you must use an HTTPS connection.

The SameSite attribute is part of an initiative from the IETFOpens in a new tab and is addressed in several of their documents.

Edit a Privileged Routine Application, a Client Application, or Document Database Application: The General Tab

The procedure is:

  1. In the Management Portal menu, select System Administration > Security > Applications, which displays the different application types.

  2. Choose Web Applications, Privileged Routine Applications, Client Applications, or Doc DB Applications. This displays the page for the selected application type.

  3. On the applications page, select the application to edit by clicking on its name. This displays the Edit page for the application.

  4. By default, the General tab appears. For privileged routine applications and client applications, the page’s fields are:

    The name field (varies by application type)

    An identifier for the application.

    Description

    A text description of the application.

    Enabled

    Whether or not the application is available. When enabled, an application is available, subject to user authentication and authorization; when disabled, it is not available.

    Resource required to run the application

    A resource for which users must have the Use permission (enabled as part of a privilege in a role) in order to perform certain actions. For web and client applications, this resource is required in order to simply operate the application; for privileged routine applications, this resource is required to invoke the AddRoles method, which gives the application its ability to escalate roles.

Edit an Application: The Application Roles Tab

For web applications, privileged routine applications, or client applications, you can configure an application so all its users receive certain roles, which are known as application roles.

To specify application roles for an application, the procedure is:

  1. In the Management Portal menu, select System Administration > Security > Applications, which displays the different application types.

  2. Choose Web Applications, Privileged Routine Applications, or Client Applications. This displays the page for the selected application type.

  3. On the applications page, select the application to edit by clicking on its name. This displays the Edit page for the application.

  4. On the Edit page, go to the Application Roles tab.

  5. To specify one or more application roles, click on the roles listed in the Available list. Move them into the Selected list with the arrows.

  6. Click Assign to establish the application roles.

Edit an Application: The Matching Roles Tab

For web applications, privileged routine applications, or client applications, you can configure an application to support what are called matching roles and target roles. If a user is assigned to a matching role, then running the application causes InterSystems IRIS to assign the user to any associated target roles. An application can have multiple matching roles; for each matching role, it can have multiple target roles; and multiple matching roles can have the same target role.

To establish a matching role and its target roles for an application, the procedure is:

  1. In the Management Portal menu, select System Administration > Security > Applications, which displays the different application types.

  2. Choose Web Applications, Privileged Routine Applications, or Client Applications. This displays the page for the selected application type.

  3. On the applications page, select the application to edit by clicking on its name. This displays the Edit page for the application.

  4. On the Edit page, go to the Matching Roles tab.

  5. On the Matching Roles tab, choose the role to be a matching role from the Select a matching role drop-down.

  6. To select the accompanying target role(s), click on the roles listed in the Available list. Move them into the Selected list with the arrows.

  7. Click Assign to establish the matching role and its target role(s).

Edit an Application: The Cross-Origin Settings Tab

Web applications can allow specific origins running in another domain to access to the system through cross-origin resource sharing (CORS). After configuring your web application to accept a CORS header, you can permit access only to cross-origin requests that come from a particular origin or include a specific header in the management portal to ensure that the requests come from a trusted source. For more information on accepting or processing a CORS header, see “Supporting CORS in REST Services.”

To specify origins that can access the system, follow theses steps:

  1. Modify your REST service to accept the CORS header.

  2. In the Management Portal menu, select System Administration > Security > Applications > Web Applications to display a list of web applications.

  3. Select the web application you would like to edit by clicking on its name. This displays the Edit page for the application.

  4. On the Edit page, go to the Cross-Origin Settings tab.

  5. On the Cross-Origin Settings tab, add allowed origins or headers. To add an origin or header, enter the name in the corresponding box, then click Add New. You can enter a wildcard asterisk (*) to allow every origin; however, note that in this case you should define how to process the CORS header, as the default CORS header processing is not suitable for REST services handling confidential data when any origin may send a CORS request.

  6. Remove an allowed origin or headers individually by clicking the Delete button next to the origin or header name. Alternatively, you can remove all allowed origins or headers by clicking the corresponding Delete All button.

  7. Select the Set Access-Control-Allow-Credentials box to add a Access-Control-Allow-Credentials header to the response, which tells origins that the server allows cross-origin requests to include credentials.

Edit an Application: The Routines/Classes Tab

This tab is for privileged routine applications only. On this tab, you can specify the classes or routines that are part of a privileged routine application.

To add a class or routine to privileged routine application, the procedure is:

  1. In the Management Portal menu, go to the Privileged Routine Applications page (System Administration > Security > Applications > Privileged Routine Applications).

  2. On the Privileged Routine Applications page, there is a list of applications that can be edited. Click the Name of the relevant application. This displays the Edit Privileged Routine Application page for the application.

  3. On the Edit Privileged Routine Application page, go to the Routines/Classes tab.

  4. In the Routine/Class name field, enter the name of the routine or class to be added to the application.

  5. Specify whether you are adding a Routine or a Class by selecting the corresponding check box.

  6. Click Assign to add the routine or class to the application.

Set the Web Application for an Interoperability–Enabled Namespace

InterSystems IRIS enables you to use a different web application for each interoperability-enabled namespace in a given instance. Consequently, you can enable different sets of users to access different interoperability-enabled namespaces within the same InterSystems IRIS instance.

To set the web application for an existing interoperability-enabled namespace, the procedure is:

  1. Create a web application that is a copy of the initial web application for the namespace.

    When you create a namespace, the system creates an initial web application named /csp/namespace, where namespace is the name of the namespace.

    For instructions, see Create an Application. You can use the Copy from field to specify the application to copy.

  2. Set the ^%SYS("Ensemble","InstalledNamespace","namespace") global node to the name of the web application that you created. The namespace value is the name of the namespace that will use the new web application.

    For example, if you created a web application named /csp/ensdemocopy and you want to use the web application for the ENSDEMO namespace, then execute the following command in the Terminal:

    set ^%SYS("Ensemble","InstalledNamespace","ENSDEMO")="/csp/ensdemocopy"
    

    When a user navigates to the interoperability pages for the namespace, the new web application appears.

Built-In Applications

Each InterSystems IRIS instance comes with a number of built-in applications. This includes a group of system applications; there is always access to system applications, even if the %Service_WebGateway service is disabled.

InterSystems IRIS Built-In Web Applications
Name Purpose or Managed Interactions Associated Resource System Application
/api/atelier REST API used by the InterSystems VS Code extensions (%Api.Atelier dispatch class). %Development No
/api/deepsee REST API used by InterSystems IRIS Business Intelligence (%Api.DeepSee dispatch class).   No
/api/docdb DocDB REST API (%Api.DocDB dispatch class).   No
/api/iam InterSystems API Manager (IAM) REST API (%Api.IAM dispatch class); used for obtaining an IAM license from InterSystems IRIS. %IAM No
/api/iknow iKnow REST API (%Api.iKnow dispatch class).   No
/api/interop-editors Rule Editor REST API (%Api.InteropEditors dispatch class).   No
/api/mgmnt API Management REST API (%Api.Mgmnt dispatch class).   No
/api/monitor Monitoring REST API (%Api.Monitor dispatch class)   No
/api/uima UIMA REST API (%Api.UIMA dispatch class).   No
/csp/broker Common static file store. For InterSystems internal use only.   Yes
/csp/documatic InterSystems class reference documentation. %Development Yes
/csp/sys General Portal access.   Yes
/csp/sys/exp Data management options in the Portal. %Development Yes
/csp/sys/mgr Configuration and licensing options in the Portal. %Admin_Manage Yes
/csp/sys/op Operations options in the Portal. %Admin_Operate Yes
/csp/sys/sec Security management and encryption options in the Portal. %Admin_Secure Yes
/csp/user Default application for the USER namespace.   No
/isc/pki InterSystems public key infrastructure (PKI).   Yes
/isc/studio/rules* Mapping to the CSP rules files.   Yes
/isc/studio/templates* Mapping to system-defined Studio template files. %Development Yes
/isc/studio/usertemplates* Mapping to user-defined Studio template files.   No
/oauth2 When InterSystems IRIS is configured as an OAuth 2.0 authorization server, used by that server. %Admin_Secure No
/ui/interop/rule-editor User interface for the Rule Editor.   No

*Note that these web applications are only used in conjunction with Studio, which has been removed as of the 2024.2 release. See Deprecated and Discontinued Features for more information.

On IRIS for Health and Health Connect instances, when you create an interoperability-enabled namespace the following built-in web applications are also created:

Additional IRIS for Health and Health Connect Built-In Web Applications
Name Purpose or Managed Interactions Associated Resource System Application
/csp/healthshare/namespace General Portal access within the namespace.   No
/csp/healthshare/namespace/bulkfhir Bulk FHIR Coordinator user interfaces.   No
/csp/healthshare/namespace/bulkfhir/api REST API used to invoke bulk FHIR operations.   No
/csp/healthshare/namespace/fhirconfig FHIR Server user interfaces.   No
/csp/healthshare/namespace/fhirconfig/api REST API used to configure and manage a FHIR Server.   No
/csp/healthshare/namespace/services This web application is not used and can be safely disabled.   No
FeedbackOpens in a new tab