Applications

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.

Each application, through its application definition, has the following properties:

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.

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")

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.

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:

• Creating and Editing an Application: The General Tab

• Editing an Application: The Application Roles Tab

• Editing an Application: The Matching Roles Tab

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):

• Creating and Editing an Application: The General Tab

• Editing an Application: The Application Roles Tab

• Editing an Application: The Matching Roles Tab

• Editing an Application: The Routines/Classes Tab

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

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 an Application: The General Tab

• Editing an Application: The Application Roles Tab

• Editing an Application: The Matching Roles Tab

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

• Editing a CSP Application: The General Tab

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

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.