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:
-
Follow the instructions in Create and Edit Applications to display the application definition (creating it first if needed).
-
For the General tab, use the information below to define the web application.
-
For the other parts of the application definition, see Create and Edit Applications.
-
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:
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.
Specifies a text description of the application.
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.
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® data platform import functions, such as $system.OBJ.Load() or $system.OBJ.ImportDir(), use the default application when importing a page without an associated 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.
Select CSP/ZEN.
Specifies whether to enable use of Business Intelligence and Natural Language Processing within this application.
Specifies whether to serve SOAP requests from within this application. Uncheck to disable.
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:
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.
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.
The application’s supported authentication mechanisms, from the set of defined mechanisms.
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)
Session Settings
For a CSP-based web application, specify Session Settings as follows:
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.
The default name of the class that handles web application events, such as a timeout or session termination.
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.
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).
Controls the default value of the SameSite attribute for session cookies.
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.
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.
Specifies the length of time for which the browser should cache static files (in seconds). Default is 3600.
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:
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.
Optionally specifies the name of the page class to use when changing password.
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:
-
By default, a user application is allowed to access pages of the /csp/sys/ application and all of its subapplications.
-
By default, a user application is allowed to access all non-% classes in the current namespace.
-
A user application can also access the following classes:
-
%CSP.BrokerOpens in a new tab, %CSP.StreamServerOpens in a new tab, %CSP.LoginOpens in a new tab, %CSP.PasswordChangeOpens in a new tab, %CSP.PageLookupOpens in a new tab are allowed.
-
%ZEN.SVGComponent.svgPageOpens in a new tab and %ZEN.Dialog.* are allowed, with the following additional conditions:
-
All other %ZEN.* classes are not allowed.
-
All other %Z* classes are allowed.
-
-
All %z* classes are allowed.
-
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.
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.
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. The web application name must be in lowercase and must start and end with 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.
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. The web application name must be in lowercase and must start and end with 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.
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
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.
