Skip to main content

Applications

Applications are the primary way that most users interact with Caché. Because of this, application security can provide a key set of tools for regulating user actions. Application security uses Caché authorization tools to ensure that only the appropriate users can use an application. An application can also escalate its users’ privileges.

This chapter 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 Caché authorization tools. If an application is formally defined with Caché, then it can use this functionality. There are three 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, Caché supports what is called an application definition, which is a set of information that represents the application within Caché. (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 Caché. 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 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 the section “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 the section “Applications and Privilege Escalation”.

All applications have these properties. Each of the three 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 Caché 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, Caché 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 the section “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 the section “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 Caché 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 Caché 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.

Checking 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 three types of applications:

Web Applications

These are applications built with CSP and Zen (which itself uses CSP). They connect to Caché using the %Service_CSP service.

For web applications, security information is maintained as part of the CSP 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 (whether they are built with Caché Server Pages, Zen, or with some other technology), 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 CSP session, then there is already a connection, so no further security checking is required.

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

  4. If the application or the CSP service require authentication and the user has not already been authenticated, then Caché checks if the request includes CacheUserName and CachePassword parameters:

    1. If CacheUserName and CachePassword are present, the CSP server 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 CacheUserName and CachePassword are not present, CSP 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.

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

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, Caché Basic, or MVBasic. To use a privileged routine application:

  1. As an administrative task, create an application definition in the Management Portal, as described in the “Creating and Editing an Application: The General Tab” section.

  2. As an administrative task, add classes or routines to it, as described in the “Editing an Application: The Routines/Classes Tab” section.

  3. As a development task, edit the application definition’s classes or routines in your development environment to escalate roles, as described in the “Escalating Roles in a Privileged Routine Application: The AddRoles Method” section.

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

Escalating 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 “Editing an Application: The Application Roles Tab”) and any relevant matching roles (as described in “Editing 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 the “User-Defined Code” chapter of Using Caché ObjectScript.

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 the “Programmatically Managing Roles” section of the “Roles” chapter.

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 Caché Direct to connect to Caché.

Important:

Regarding client applications:

  • Security is available only for applications using Caché Direct. Any client/server application using other technology, such as ActiveX, cannot use application security. For these applications, use the authentication tools described in chapter “Authentication.”

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

Caché enables executables built using Caché Direct to be identified to the system. When such an executable attempts to connect to the server, Caché performs the following processing:

  1. If the %Service_CacheDirect is not enabled, there is no connection. If %Service_CacheDirect is enabled, the attempt to connect proceeds.

  2. If the Use permission for the %Service_CacheDirect service is not public and the user does not hold the permission on the service, then the connection is rejected.

  3. If the Use permission for a resource specified in the application definition is not public and the user does not hold the permission on the application, then the connection is rejected.

  4. If the process has Read or Write permission on the namespace to which the connection is being made, the connection is accepted; otherwise, the connection is rejected.

  5. Once the connection is accepted, application roles are added. Similarly, if the user is a member of any matching roles, then the appropriate target roles are added.

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

Creating and Editing Applications

This section describes several topics:

Creating and Editing an Application: The General Tab

For creating and editing an application, the General tab holds fields that specify information needed for basic operation of the application:

Creating 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, or Client 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. Depending on the application you are attempting to create, select Create New Web Application, Create New Privileged Routine Application, or Create New Client 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 the next section.

Editing a CSP Application: The General Tab

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:

  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; a CSP-based utility included with Caché).

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

  3. When finished with edits, restart Caché for the new settings to take effect.

The General tab displays the following options:

Edit Web Application Settings — General Tab
Field Description
Name Enter a name for the application. The name must include a leading slash (/), such as in the /csp/acme application.
Description Enter a description.
Namespace The Caché namespace in which pages for this application are run.
Namespace Default Application Sets this application as the default application for this namespace. A call to %System.CSP.GetDefaultApp returns this application as the default for the namespace. Caché import functions use this to deal with cases such as importing a CSP page from an XML file where the current namespace does not have the CSP application that the CSP file was exported from. CSP imports the CSP file into the default CSP application for the namespace.
Application Controls whether an application is available. When selected, an application is available, subject to user authentication and authorization; when unchecked, it is not available.
CSP/Zen Enables CSP to serve CSP and Zen pages. Uncheck to disable. For more information on Zen, see the book Using Zen.
DeepSee Enables the %-class required for DeepSee. Uncheck to disable.
iKnow Enables the %-class required for iKnow. Uncheck to disable.
Prevent login CSRF attack Whether or not the application enables functionality to prevent Cross-Site Request Forgery (CSRF) attacks. InterSystems recommends that you enable this feature for all new applications; it is recommended for all existing applications except if there is code that programmatically requests pages from the application.
Inbound Web Services Enables CSP to serve SOAP requests. Uncheck to disable. For more information on SOAP and Caché web services, see the book Creating Web Services and Web Clients in Caché.
Permitted Classes Specify classes that may be run in this application in three ways: 1) ObjectScript match pattern. Example: 1"myclass".3N allows myclass123.cls to run in this application, but not myclassxy.cls. 2) ObjectScript expression that evaluates to a boolean, prefixed with @. The requested class name is passed as a variable named class. Example: @class = “PermittedClasses.PermittedPage” 3) Call to a class method (can also use @syntax). Example: ##class(MyPackage).CheckClassIsPermitted(class) See also “Enabling Application Access to %CSP Pages”.
Resource Required Specifies a resource for which users must have the Use permission (enabled as part of a privilege in a role) in order to run the application. For information on resources and permissions, see the “About Resources” section in the Caché Security Administration Guide.
Group by ID

Enter a group name for this application to share authentication privileges with all other applications with this group name. All applications with this group name stay in authentication sync. If you log out of any of these applications, you are logged out of all of them. If you then try to return to a page of any of these applications, you need to log in again. Once logged in, however, you can go from one application to another without logging in again. (The only exception is that if any of these applications are unauthenticated, they are not treated as part of the authentication cluster.) Note that Group by ID is attached to an application, not a namespace. So applications with the same Group by ID share authentication regardless of namespace. For more specifics, see the section “By-ID Groups”.

Allowed Authentication Methods

Specifies the available authentication mechanisms for connecting to the application. The options displayed here are determined by what is checked on the Authentication Options page (Management Portal >System Administration > Security > System Security > Authentication/CSP Session Options). If an application supports multiple authentication mechanisms, authentication occurs as follows:

  • If more than one option is enabled including Unauthenticated, the user has the choice of logging in without providing a username and password.

  • If all options are enabled and the user enters a username and password, then Caché attempts to perform cascading authentication.

  • If the selected options are Kerberos and Password and Unauthenticated is not selected, then the user must provide a username and password. Caché attempts to perform authentication first using Kerberos and then Caché password login. If either authentication succeeds, the user is authenticated; if both fail, the user is denied access to the application.

For more information on authorization, see the chapter Authentication in the Caché Security Administration Guide.

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 CSP applications during its life span, its timeout value will not be updated according to the default timeout defined in the application that the session moved into. For example, if a session starts out in CSP Application A, with a default timeout of 900 seconds, and then moves into CSP Application B, which has a default timeout of 1800 seconds, the session will still timeout after 900 seconds.

If you want an application change to result in the session timeout being updated to that of the new application, use a session event class, override the OnApplicationChange callback method, and add code to handle the update of the AppTimeout property of the %session object.

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

Event Class Specifies the default name of the CSP class (a subclass of %CSP.SessionEventsOpens in a new tab) whose methods are invoked for CSP application events, such as a timeout or session termination. You can override this value using the EventClass property of the %CSP.SessionOpens in a new tab object. Note: Use only a class name without an extension (such as .cls or .zen) as a value of this setting, for example MyApplication.SessionEvents.
Use Cookie for Session Whether you want CSP to track which session a browser is in by using cookies or a URL-rewriting technique (placing a value in each URL). (In order for an application to actually use cookies, regardless of this setting, the application has to be written to use cookies.) Choices are always use cookies, never use cookies, or, the default, automatically detect whether a user has disabled cookies. The specific choices are: a) (default) Use cookies (Always), b) Do not use cookies (Never), c) Use cookies unless the client browser has disabled cookies (Autodetect). This option does not set whether an application uses cookies (this is dependent on how the application is written); it merely controls how CSP manages sessions. If the user has disabled cookies, the application uses URL rewriting.
Session Cookie Path Specifies the portion of the URLs that the browser uses to send the session cookie back to Caché for this application. If your application name is myapp, it defaults to /myapp/ meaning it only sends the cookie for pages under /myapp/. If you restrict this to only what is required by your application, it prevents this session cookie being used by other CSP applications on this machine, or from being seen by any other application on this web server. On the other hand, browsers and cookies are case-sensitive. Setting the session cookie to '/' can prevent license or session problems if, for example, an application name changes from capital to lowercase letters.
Session Cookie Scope Available starting in version 2018.1.5 only. 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 Available starting in version 2018.1.5 only. 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.
Dispatch Class Identifies the corresponding custom subclass of %CSP.RESTOpens in a new tab for implementing a REST service. See Creating Rest Services for more information.
Serve Files

No — Never serve files from this application path.

AlwaysDefault. 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 CSP gateway to cache these files to avoid having to request them from Cache. This is the mode that deployed applications are expected to use.

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

Serve Files Timeout Length of time static files should be cached by the browser in seconds. Default is 3600.
CSP Files Physical Path The directory on the Caché server in which CSP source files are stored. The path is relative to the install-dir/csp/ directory on the Caché server system.
Package Name The name of an optional package prefix used by the CSP compiler. This name is prepended to the package names used for classes created from CSP files. If this field is not specified, the default value of csp is used.
Default SuperClass The name of the default superclass used by the CSP compiler for classes created from CSP files. The default is %CSP.PageOpens in a new tab.
Recurse Specifies whether to include subdirectories within this application or not. If UPath is the URL Path and PPath is the Physical Path, then with Recurse set to Yes, UPath/xxx/yyy looks for CSP files in PPath/xxx/yyy. If Recurse is set to No, only files directly contained in UPath are used.
Auto Compile Auto Compile works with Lock CSP Name to determine when an application is compiled.
Lock CSP Name

If two Web applications both point to the same namespace and Lock CSP Name is set to Yes (true) for both Web applications, then any CSP page in that namespace is displayed only through the Web application where it was last compiled. You can determine which Web application applies to a CSP page by looking at the page class’s CSPURL parameter. For example:Parameter CSPURL = "/csp/samples/zipcode.csp";

If you set Lock CSP Name to Yes, set Auto Compile to No. If Auto Compile is also set to Yes, then a change to any CSP page in the namespace triggers a recompilation of that page (including the CSPURL parameter) when it’s next requested. A change to either Web application definition also triggers recompilation of any pages in the namespace when next requested. In these cases, this allows the next request for a page to use either of the Web applications, and from then on, the page is displayed only through the last Web application used to request it.

For Zen pages in this scenario, if you set Lock CSP Name to Yes, set the CSPURL parameter of each ZEN page. See %CSP.PageOpens in a new tab for details. The AutoCompile setting doesn’t affect ZEN pages.

Login Page The name can be the name of a CSP page, a Zen page, or a CSP-enabled class which may be prefixed with the full CSP application path. All of the following are acceptable: mylogin.csp, /csp/user/mylogin.csp, MyApp.LoginPage.zen, /csp/user/MyApp.LoginPage.cls. In most cases, the login page is loaded before the user has logged in to Cache, so the requesting process runs under the CSPSystem user (or whatever user connects the CSP Gateway to Caché). 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 Name of page to use when changing password.
Custom Error Page The name of a .csp or .cls page that is displayed if an error occurs when generating a page within this application.
About the SameSite Attribute
Note:

Support for the SameSite attribute is available starting in version 2018.1.5.

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.

Editing a Privileged Routine Application or Client Application: The General Tab

To perform general editing on a privileged routine application or a client 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. By default, the General tab appears. For privileged routine applications and client applications, the page’s fields are:

    • Privileged routine application name or Application path and name — An identifier for the application

    • Description — A 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.

Editing an Application: The Application Roles Tab

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.

Editing an Application: The Matching Roles Tab

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 Caché 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).

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

Built-In Applications

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

Caché Built-In Web Applications
Name Purpose or Managed Interactions Associated Resource System Application
/api/atelier Atelier REST API (%Api.Atelier dispatch class) %Development No
/api/deepsee DeepSee REST API (%Api.DeepSee dispatch class)   No
/api/iknow iKnow REST API (%Api.iKnow dispatch class)   No
/csp/broker Common static file store. For InterSystems internal use only   Yes
/csp/docbook InterSystems main documentation (including this book)   Yes
/csp/documatic InterSystems class reference documentation %Development Yes
/csp/samples Default application for the SAMPLES namespace   No
/csp/samples/docserver Sample REST application (REST.DocServer dispatch class)   No
/csp/sys General Portal access   Yes
/csp/sys/bi Business intelligence options in the Portal   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

For more information on the /isc/studio/rules, application, see the chapter “Developing Custom Tags” in Using Caché Server Pages (CSP). For more information on the /isc/studio/templates application, see the chapter “Using Studio Templates” in Using Studio.

FeedbackOpens in a new tab