Create and Edit Applications

This section describes several topics:

Create an Application

To create an application, the procedure is:

In the Management Portal menu, select System Administration > Security > Applications, which displays the different application types.
Choose Web Applications, Privileged Routine Applications, Client Applications, or Doc DB Applications. This displays the page for the selected application type.
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
- Edit a Privileged Routine Application, a Client Application, or Document Database Application: The General Tab

Edit a Web Application: The General Tab

To edit a web application:

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).
Select an application, click Edit, and enter or change the information.
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:

The fields described here are only those that are relevant for InterSystems IRIS REST-based web applications. The other type of web application, called a CSP/ZEN application, is a legacy InterSystems application type. Because new applications based on InterSystems IRIS should be REST applications, 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 that 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 or CSP/ZEN

Whether this is a REST application or a CSP/ZEN application, which is a type of InterSystems legacy application. For new applications, InterSystems recommends the use of REST, which supports modern third-party front-end technologies.

If you have an existing application that uses CSP, InterSystems supports ongoing development using that technology and provides documentation for the CSP settings in Editing a CSP Application: The General TabOpens in a new tab.

Dispatch Class

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

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

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

JWT Access Token Timeout

The number of seconds until the JWT expires.

JWT Refresh Token Timeout

The number of seconds until the refresh token for the JWT expires.

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:

Always — Default. 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:

In the Management Portal menu, select System Administration > Security > Applications, which displays the different application types.
Choose Web Applications, Privileged Routine Applications, Client Applications, or Doc DB Applications. This displays the page for the selected application type.
On the applications page, select the application to edit by clicking on its name. This displays the Edit page for the application.
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:

In the Management Portal menu, select System Administration > Security > Applications, which displays the different application types.
Choose Web Applications, Privileged Routine Applications, or Client Applications. This displays the page for the selected application type.
On the applications page, select the application to edit by clicking on its name. This displays the Edit page for the application.
On the Edit page, go to the Application Roles tab.
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.
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:

In the Management Portal menu, select System Administration > Security > Applications, which displays the different application types.
Choose Web Applications, Privileged Routine Applications, or Client Applications. This displays the page for the selected application type.
On the applications page, select the application to edit by clicking on its name. This displays the Edit page for the application.
On the Edit page, go to the Matching Roles tab.
On the Matching Roles tab, choose the role to be a matching role from the Select a matching role drop-down.
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.
Click Assign to establish the matching role and its target role(s).

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:

In the Management Portal menu, go to the Privileged Routine Applications page (System Administration > Security > Applications > Privileged Routine Applications).
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.
On the Edit Privileged Routine Application page, go to the Routines/Classes tab.
In the Routine/Class name field, enter the name of the routine or class to be added to the application.
Specify whether you are adding a Routine or a Class by selecting the corresponding check box.
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:

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.
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

Application Types