Skip to main content

Configuring a CSP-Based Web Application

You can use the same Management Portal pages (and the same APIs) to configure CSP-based web applications as you do for other applications. This page primarily discusses the settings that are specific to CSP-based applications.

To configure a CSP-based web application:

  1. Follow the instructions in Create and Edit Applications to display the application definition (creating it first if needed).

  2. For the General tab, use the information below to define the web application.

  3. For the other parts of the application definition, see Create and Edit Applications.

  4. Ensure that the Web Gateway configuration is also updated to provide access to this web application. (For background, see Components of a CSP-Based Web Application.)

General Settings for a CSP-Based Web Application

For a CSP-based web application, specify values in the initial section of the General tab as follows:

Name

Specifies the 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

Specifies a text description of the application.

Namespace

Specifies 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

Specifies whether 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

Specifies whether 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

Select CSP/ZEN.

Analytics

Specifies whether to enable use of Business Intelligence and Natural Language Processing within this application.

Inbound Web Services

Specifies whether to serve SOAP requests from within this application. Uncheck to disable.

Prevent login CSRF attack

Specifies whether the application automatically prevents Cross-Site Request Forgery (CSRF) attacks. InterSystems recommends that you enable this option for all new applications; it is also recommended for all existing applications except if there is code that programmatically requests pages from the application.

Security Settings

For a CSP-based web application, specify security settings as follows:

Resource Required

A resource for which users must have the Use permission so they can run the application.

Note that you can also specify required resources within CSP page classes. Both mechanisms are applied.

Group by ID

For use by By-ID groups to enable you to share authentication across multiple web applications. Enter a group name for this application to share authentication privileges with all other applications with this group name.

Allowed Authentication Methods

The application’s supported authentication mechanisms, from the set of defined mechanisms.

Permitted Classes

Specify classes whose methods can be executed within this application. There are three ways to do this:

  • Use an ObjectScript match pattern. Example: 1"myclass".3N allows myclass123.cls to run in this application, but not myclassxy.cls

  • Use an ObjectScript expression that evaluates to a boolean, prefixed with @. The requested class name is passed as a variable named class. Example: @class = "PermittedClasses.PermittedPage"

  • Use a call to a class method (can also use @syntax). Example: ##class(MyPackage).CheckClassIsPermitted(class)

See also Enabling Application Access to %CSP Pages.

Session Settings

For a CSP-based web application, specify Session Settings as follows:

Session Timeout

The default session timeout in seconds. You can override this value programmatically.

Note that a user moves from one web application to another during a session, the timeout period is still controlled by the first web application used during the session. 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. In such a case, you may want to define a session event class to update the session timeout.

Event Class

The default name of the class that handles web application events, such as a timeout or session termination.

Use Cookie for Session

Whether or not the application tracks the browser session by using a cookie. Choices are:

  • Always — Default. Always use a cookie to track the browser session.

  • Never — Never use a cookie to track the browser session.

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

Note that this option does not set whether the 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 uses cookies only if it contains specific code 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.

User Cookie Scope

Controls the default value of the SameSite attribute for application-specific cookies.

About the SameSite Attribute

The SameSite attribute determines how an application handles cookies in relation to third-party applications (aka cross-site requests). 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.)

You can programmatically override this attribute within the CSP page classes.

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

CSP File Settings

The CSP server can serve static files in addition to passing back content generated by the CSP pages. For a CSP-based web application, the CSP File Settings control how the CSP server handles static files. Also see How the CSP Server Handles Static Files.

You can use a traditional configuration of serving static pages from the web server. (In this case, the settings described here are irrelevant.) This may be preferable in certain situations. For example, if you have a system where one web server serves multiple remote InterSystems IRIS instances, it may be more efficient to serve those files from a common location local to the web server machine.

Note, however, that configuring the web server to serve static files may cause problems: for example, if the common web server serves different versions of InterSystems IRIS, the web server may encounter a conflict between two different versions of the same file (for example, hyperevent broker components). Such conflicts do not occur when each CSP server handles static content for its own applications. Additionally, if you have configured the web server itself to serve static files, you must make sure that the static content is present on every single web server in your system.

Serve Files

Controls whether to serve static files from the directory specified by Physical Path.

  • No — Never serve files from this application path.

  • Always — Default. Always serve files from this application path and ignore the CSP security setting for this path for static files. This is the default for new applications; it is backward compatible with applications that previously had static files served from the web server.

  • Always and cached — Always serve files from this application path and allow the Web Gateway to cache these files to avoid having to request them from InterSystems IRIS. This is the mode that deployed applications are expected to use.

  • Use CSP Security — If you have permission to view a CSP page in this application, then you can also view static files. If you do not have permission to view a page, then you see a 404 page not found message.

Serve Files Timeout

Specifies the length of time for which the browser should cache static files (in seconds). Default is 3600.

Physical Path

The directory on the InterSystems IRIS server from which to serve files for this web application. The path is relative to the install-dir/csp/ directory.

Ignore the options Package Name, Default Superclass, Recurse, Auto Compile, and Lock CSP Name, which apply only to tag-based development. (If needed, see Editing a CSP Application: The General Tab in the Caché/Ensemble documentation.)

Custom Pages

For a CSP-based web application, specify Custom Pages as follows:

Login Page

Optionally specifies the name of a CSP page class, which may be prefixed with the full web application path. For example: /csp/user/MyApp.LoginPage.cls

Usually, the login page is loaded before the user has logged in to InterSystems IRIS, so the requesting process runs under the CSPSystem user (or whatever user connects the CSP Gateway to InterSystems IRIS). As a result, the CSPSystem user must have sufficient privileges to load and run the code in the login page, which generally requires READ permissions on the resource protecting the database in which the login page is located.

Change Password Page

Optionally specifies the name of the page class to use when changing password.

Custom Error Page

Optionally specifies the name of a CSP error page class to display if an error occurs when generating a page within this application.

Enabling Access to Pages and Classes

The following rules govern access to pages and classes from within a web application:

  1. By default, a user application is allowed to access the following pages:

    • Pages of the /csp/sys/ application and all of its subapplications are allowed.

    • Pages of the /isc/studio/templates/ and /isc/studio/usertemplates/ applications are allowed.

  2. By default, a user application is allowed to access all non-% classes in the current namespace.

  3. A user application can also access the following classes:

Checking for allowed classes is performed in addition to checking the setting in the web application.

To permit access to additional classes, configure the global ^SYS("Security","CSP","category") in the %SYS namespace, where category is AllowClass, AllowPrefix, or AllowPercent. The following sections describe these options.

Important:

Checking is done by applying the default rules first, then the categories in the order listed.

Also, each keyword can be invoked more than once. This means that you can make an entire package accessible, and then restrict access to one class in that package.

Background Information on the ^SYS Global

The ^SYS global is available in the %SYS namespace and contains configuration information. You may find it helpful to start by examining the current contents of the relevant part of this global. To do so, open the Terminal and switch to the %SYS namespace. Then enter the following command:

 zw ^SYS("Security", "CSP")

The system then displays one line for each node, showing its current value. For example:

^SYS("Security","CSP")=1
^SYS("Security","CSP","AllowClass","/csp/samples/","%CSP.UI.Portal.About")=1
^SYS("Security","CSP","AllowClass","/csp/samples/","%SOAP.WebServiceInfo")=1
^SYS("Security","CSP","AllowClass","/csp/samples/","%SOAP.WebServiceInvoke")=1
^SYS("Security","CSP","AllowPrefix","/csp/samples/","%DeepSee.")=1

Category: AllowClass

If your application relies on invoking a particular class, use the AllowClass option to make that class available.

Important:

If your application relies on invoking any class other than those listed as allowed at the beginning of Enabling Application Access to %CSP Pages, it could potentially be unsafe to use. InterSystems recommends that you determine if calling this class is required, and perform a risk assessment for your deployment, so that you understand the implications of making the class available.

To enable a given web application to invoke a particular class, use the following command in the %SYS namespace:

 Set ^SYS("Security", "CSP", "AllowClass", "web-app-name", "package.class") = value

Where:

  • web-app-name is the name of the web application, followed by a trailing slash.

    To enable all web applications to use the given class or package, specify web-app-name as 0; in this case, you can omit the enclosing quotes.

  • package.class is the fully qualified name of a class. If you omit class, then all classes in the specified package are allowed.

  • value is either 1 or 0.

    If you specify this as 1, the web application can invoke this class (or package).

    If you specify this as 0, this web application cannot invoke this class (or package).

For example, to enable the /csp/webapps application to use the class %User.Page, you would use the following command:

 Set ^SYS("Security", "CSP", "AllowClass", "/csp/webapps/", "%User.Page") = 1

Or to enable all web applications to use the %User.Page, you would use the following command:

 Set ^SYS("Security", "CSP", "AllowClass", 0, "%User.Page") = 1

For another example, to enable the /csp/myapp application to use all classes in the %User package except for the %User.Other class, you would use the following two commands:

 Set ^SYS("Security", "CSP", "AllowClass", "/csp/myapp/", "%User") = 1
 Set ^SYS("Security", "CSP", "AllowClass", "/csp/myapp/", "%User.Other") = 0

Category: AllowPrefix

If your application relies on invoking multiple classes or packages that begin with the same set of characters, use the AllowPrefix option.

Important:

If your application relies on invoking any class other than those listed above, it could potentially be unsafe to use. InterSystems recommends that you determine if calling this class is required, and perform a risk assessment for your deployment, so that you understand the implications of making the class available.

To enable a given web application to invoke classes or packages that begin with the same set of characters, use the following command in the %SYS namespace:

 Set ^SYS("Security", "CSP", "AllowPrefix", "web-app-name", "prefix") = value

Where:

  • web-app-name is the name of the web application, followed by a trailing slash.

    To enable all web applications to use the given classes or packages, specify web-app-name as 0; in this case, you can omit the enclosing quotes.

  • prefix is the first characters in the name.

  • value is either 1 or 0.

    If you specify this as 1, the web application can invoke these classes (or packages).

    If you specify this as 0, this web application cannot invoke these classes (or packages).

For example, to enable the /csp/webapps application to invoke the entire MyApp package, use the following command:

 Set ^SYS("Security", "CSP", "AllowPrefix", "/csp/webapps/", "MyApp.") = 1

Note that prefix is "MyApp." and the period in the prefix means that the web application cannot access the packages such as MyAppUtils. The web application can, however, access the packages MyApp.Utils and MyApp.UnitTests.

For another example, to enable all applications to access all packages that begin with My, use the following command:

 Set ^SYS("Security", "CSP", "AllowPrefix", 0, "My") = 1

For another example, suppose that the /csp/myapp application should be able to access all classes in the %MyPkg package except for the class %MyPkg.Class1. In that case you would use the following two commands:

 Set ^SYS("Security", "CSP", "AllowClass", "/csp/myapp/", "%MyPkg.Class1") = 0 
 Set ^SYS("Security", "CSP", "AllowPrefix", "/csp/myapp/", "%MyPkg.") = 1

Category: AllowPercent

If your application relies on invoking the packages that begin with the % character generally, the AllowPercent option makes those classes available.

Important:

If your application relies on invoking any class other than those listed above, it could potentially be unsafe to use. InterSystems recommends that you determine if calling this class is required, and perform a risk assessment for your deployment, so that you understand the implications of making the class available.

To enable all web applications to use all packages that begin with the % character, use the following command in the %SYS namespace:

 Set ^SYS("Security", "CSP", "AllowPercent") = 1
Note:

Or use the value 0 to explicitly forbid any web application from accessing these packages.

How the CSP Server Handles Static Files

For a web application that is configured to serve static files, the CSP server — specifically its Stream Server component — processes static files. It uses the file extension to determine:

  • The file type (the MIME type)

  • Whether the file is a binary file

  • The character encoding of the file (if applicable)

For JavaScript files, the Stream Server determines the character encoding in a manner consistent with major web servers, described below. You can override the default behavior if needed.

Character Encoding of JavaScript Files

The modern convention is for all JavaScript files to be marked as Content-Type of application/javascript. With JavaScript files marked this way:

  • If a file contains a BOM (byte-order mark), the browser automatically detects this and uses the correct character set to read it.

  • If the file does not contain a BOM, then the browser assumes the file is UTF-8.

If you need to override this behavior to specify a character set for JavaScript files, set the global ^%SYS("CSP","MimeFileClassify","JS") to the list value $listbuild(contenttype, binary, charset). For example,

 Set list=$listbuild("text/javascript", 0 ,"ISO-8859-1")
 Set ^%SYS("CSP", "MimeFileClassify", "JS") = list

This sets the older content-type and uses the ISO-8859-1 character set. Also, if the default InterSystems IRIS translate table is defined to be something other than an empty string or if the global node ^%SYS("CSP","DefaultFileCharset") is set to a null value, InterSystems IRIS will use this character set for all JavaScript and other text files. By default, neither of these global nodes are set.

Next sectionCreating a CSP Page Class
Previous sectionIntroduction to CSP-Based Web Applications
FeedbackOpens in a new tab