CSP Application Settings

When a CSP server receives an incoming HTTP request, it uses the local Caché CSP application settings to determine how to process the request. This section describes how Caché processes CSP application requests using CSP application settings.

Enabling Application Access to %CSP Pages

The following rules govern access to pages and classes:

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
By default, a user application is allowed to access all non-% classes
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 CSP application. You can view and change the application settings by navigating to System Administration > Security > Applications > Web Applications on the Management Portal. So a class reference must pass both sets of tests in order to be allowed. (See in the Permitted Classes setting in the table in the section “Editing Web Application Settings” in this book.)

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, including the details described in this book. 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 the “Enabling Application Access to %CSP Pages” section, 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:

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.

Special Case: DeepSee

For a web application to use DeepSee, it needs access to all the classes in the %DeepSee package. To enable a particular application to use DeepSee, use the following command in the %SYS namespace:

Do EnableDeepSee^%SYS.cspServer("/csp/webapp/")

Where web-app-name is the web application’s name with a trailing slash. The previous command is equivalent to the following commands:

Set ^SYS("Security","CSP","AllowClass","web-app-name","%DeepSee.") = 1
Set ^SYS("Security","CSP","AllowClass","web-app-name","%CSP.UI.Portal.About")=1

Where web-app-name is the web application’s name with a trailing clash. Note that the first line uses %DeepSee. with a trailing period.

Or to enable all applications to use DeepSee, use the following variation:

Do EnableDeepSee^%SYS.cspServer(0)

For example, to enable the /csp/webapp web application to use DeepSee, use the following command:

Do EnableDeepSee^%SYS.cspServer("/csp/webapp/")

To disallow a specific web application from using DeepSee, use the following command:

Set ^SYS("Security", "CSP", "AllowPrefix", "web-app-name", "%DeepSee.") = 0

Editing Web Application Settings

You can create or modify settings for how you want Caché to process a specific CSP application on the Edit Web Application page of the Management Portal as follows:

Select System > Security > Web Applications.
This lists configured web applications. The Type column identifies an application as a user application (CSP) or a system application (CSP,System; a CSP-based utility included with Caché).
Select an application, click Edit, and enter or change the information.
When finished with edits, restart Caché for the new settings to take effect.

The General tab holds fields that specify information needed for basic operation of the application. See “Editing an Application” in the Caché Security Administration Guide for more information on these fields.

The Application Roles tab lets you select roles to which to assign the user during use of the application. The Application Roles that you select here are added to the set of roles to which the user is already assigned.

The Matching Roles tab lets you assign the application user to additional roles during use of the application, based on current role assignments.

For more on roles and custom login pages, see “Applications” in the book Caché Security Administration Guide.

Defining a New Application

To define a new CSP application named /myapp on a CSP server, follow the steps below:

In the Management Portal, select System > Security > Web Applications and click Create New web application.
Type in the URL for the new application name, /myapp in this case, and click OK.
Fill in any needed application properties (most are optional). (See the table in the section Application Settings.)The most important are:
- Enable/Disable Authentication allowed — the valid authentication technologies for connecting to the application
- Namespace — the Caché Namespace in which this application is run
- Caché Physical Path — the physical location of CSP files (if you are using HTML-based development)
Click Save.
Click the Application Roles tab to select roles to assign the user to during use of the application. These Application Roles are added to the set of roles the user is already assigned to.
Click the Matching Roles tab to assign the application user to additional roles during use of the application, based on current role assignments.