Caché Security Administration Guide
Applications
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Almost all users interact with Caché using applications. 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 also has features that allow it to escalate its users’ privileges.

This chapter covers the following topics:
Applications, Their Properties, and Their Privileges
From a security standpoint, an application:
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 web applications, privileged routine applications, and client applications.
This section covers:
Applications and Their Properties
Applications allow you to establish a limited 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 an alphabetic character and must be followed by alphabetic, numeric, or underscore characters. 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. There are three application types and each 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, which can be referred to as “sub-applications.” The sub-applications are designed to behave as a single, unitary whole, but different sub-applications 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 of 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. 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 application resources can be used to enhance a user’s roles, they provide a mechanism for meeting dynamically shifting authorization needs.
To take advantage of this functionality, the process is:
  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 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:
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
For example, if an application required that a user 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 (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 one or more routines the privilege to escalate roles for their users. The routines in a privileged routine application are written in Caché ObjectScript, Caché Basic, or MVBasic. These routines are registered with Caché on the Routines tab of the application editing page for such an application, as described in the section Editing an Application: The Routines Tab.” The routines that are registered have the ability to execute the AddRoles method for this application definition.
The AddRoles call refers to the AddRoles method of the %SYSTEM.Security class. A call to AddRoles is of the form:
 Set sc = $SYSTEM.Security.AddRoles("AppDefName")
where AppDefName is the name of the application definition and sc is a status code. If a routine is part of an application definition and the user is appropriately privileged, then calling AddRoles from that 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 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 occurs as follows:
  1. If the call is not from a privileged routine, it fails.
  2. If the privilege specified in the application definition is not public and the user invoking the routine does not hold this privilege, then the call fails.
  3. Otherwise, the call succeeds.
Once a user has additional roles from a call to AddRoles, the user retains these roles unless there is an action that removes them. To explicitly remove any added roles, issue the following command:
 Set $Roles = ""
You can also 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 escalated privileges. To do this, include the following command prior to the call to AddRoles:
 New $Roles
To edit a privileged routine application, the Portal provides the following pages:
An Example of Using a Privileged Routine Application
Suppose there is a need to have a routine for which only certain users can escalate privileges. This routine is called PRATestRtn (for “Privileged Routine Application”) and the privilege to be added is associated with the role PRATestAddedRole. To enable users to receive PRATestAddedRole as a role while running PRATestRtn, the following entities and items must exist:
Here is the content of PRATestRtn:
PRATestRtn
 Write "This routine 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...",!,!
 Set sc = $SYSTEM.Security.AddRoles("PRATestApp")
 If sc = 1 {
 Write "Application roles have been added.",!
     Write "$Roles now is ",$Roles,!,!
     Write "Removing PRATestAddedRole from $Roles...",!
     Set $Roles = ""
     Write "The current value of $Roles is now ",$Roles,!,!     
 } Else {
     Write "The call to AddRoles has failed.",!
     Do $system.Status.DecomposeStatus(sc,.Err)
     Write Err(Err),!
 }
Here is the terminal session where PRATestUser runs this routine:
Username: PRATestUser
Password: ****
USER>Do ^PRATestRtn
This routine is a part of the privileged routine application
called PRATestApp.
The user invoking this routine is PRATestUser
The current value of $Roles is %Developer,PRATestRole
 
Calling the AddRoles method...
 
Application roles have been added.
The current value of $Roles is now %Developer,PRATestRole,PRATestAddedRole
 
Removing PRATestAddedRole from $Roles...
$Roles now is %Developer,PRATestRole

USER>
Here is the terminal session where NonPRATestUser runs this routine:
Username: NonPRATestUser
Password: ****
USER>d ^PRATestRtn
This routine is a part of the privileged routine application
called PRATestApp.
The user invoking this routine is NonPRATestUser
The current value of $Roles is %Developer
 
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:
Client application security is available only for applications using Caché Direct. Any client/server application using other technology, such as Jalapeño or ActiveX, cannot use application security. For these applications, use the authentication tools described in chapter Authentication.”
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 makes available choices of various application types. Choose Web Applications, Privileged Routine Applications, or Client Applications. This displays the page for the selected application type.
  2. 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 an Application
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 be in lowercase and include an ending slash (/). Example: /csp/acme/
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.
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) Caché ObjectScript match pattern. Example: 1"myclass".3N allows myclass123.cls to run in this application, but not myclassxy.cls. 2) Caché 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.Session 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.
Event Class Specifies the default name of the CSP class (a subclass of %CSP.SessionEvents) 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.Session 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) Use cookies (Always), b) Do not use cookies (Never), c) (default) 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 Scope of the session cookie. This determines which URLs the browser uses to send the session cookie back to Caché. 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.
Dispatch Class Identifies the corresponding custom subclass of %CSP.REST for implementing a REST service. See Creating Rest Services for more information.
Serve Files
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 CSP gateway to cache these files to avoid having to request them from Caché. This is the mode we expect deployed applications 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.Page.
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.Page 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.
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 makes available choices of various application types. Choose Web Applications, Privileged Routine Applications, or Client Applications. This displays the page for the selected application type.
  2. On the applications page, there is a list of applications that can be edited. Click Edit in the row of the relevant application. This displays an editing page for the application.
  3. The General tab is initially displayed for this page. For privileged routine applications and client applications, the page’s fields are:
Editing an Application: The Application Roles Tab
You can configure an application so all its users are given certain roles. These roles are known as application roles.
To establish any application roles for an application, the procedure is:
  1. In the Management Portal menu, select System Administration > Security > Applications, which makes available choices of various application types. Choose Web Applications, Privileged Routine Applications, or Client Applications. This displays the page for the selected application type.
  2. On the applications page, there is a list of applications that can be edited. Click Edit in the row for the relevant application. This displays an editing page for the application.
  3. On the application editing page, go to the Application Roles tab.
  4. 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.
  5. Click Assign to establish the application role(s).
Editing an Application: The Matching Roles Tab
An application can 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. There can be multiple matching roles and multiple target roles for each matching 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 makes available choices of various application types. Choose Web Applications, Privileged Routine Applications, or Client Applications. This displays the page for the selected application type.
  2. On the applications page, there is a list of applications that can be edited. Click Edit in the row for the relevant application. This displays an editing page for the application.
  3. On the application editing page, go to the Matching Roles tab.
  4. On the Matching Roles tab, choose the role to be a matching role from the Select a matching role drop-down.
  5. 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.
  6. Click Assign to establish the matching role and its target role(s).
Editing an Application: The Routines Tab
This tab is for privileged routine applications only. On this tab, you can specify the routines that are part of a privileged routine application.
To add a routine to privileged routine application, the procedure is:
  1. 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.
  2. On the Routines/Classes tab, choose the database that contains the relevant routine or class from the Routine/Class location drop-down.
  3. In the Routine/Class name field, enter the name of the routine or class to be added to the application.
  4. Specify whether you are adding a Routine or a Class by selecting the corresponding check box.
  5. Click Assign to add the routine or class to the application.
System Applications
Each Caché instance comes with a number of system applications. There is always access to these applications, even if the %Service_CSP service is disabled. The system applications are:
Caché System Web Applications
Name Purpose or Managed Interactions Associated Resource
/csp/broker Common static file store. For InterSystems internal use only.  
/csp/docbook InterSystems main documentation (including this book).  
/csp/documatic InterSystems class reference documentation. %Development
/csp/sys General Portal access.  
/csp/sys/exp Data Management options in the Portal. %Development
/csp/sys/mgr Configuration and Licensing options in the Portal. %Admin_Manage
/csp/sys/op Operations options in the Portal. %Admin_Operate
/csp/sys/sec Security Management and Encryption options in the Portal. %Admin_Secure
/isc/studio/rules Mapping to the CSP rules files.  
/isc/studio/templates Mapping to system-defined Studio template files. %Development
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 Caché Studio.