There are three types of applications: • CSP applications
• Privileged routine applications
• Client applications
8.2.1 CSP Applications
These are applications built with CSP and Zen. They connect to Caché using the %Service_CSP
service.
For CSP 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 CSP 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” ses- sions.
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.
CSP security processing occurs as follows:
1. As each page request is received, its CSP 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 CSP service Use permission 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:
a. 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.
b. If CacheUserName and CachePassword are not present, CSP displays an application-specific login page, if one is defined in the CSP 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 per- mission on the application resource, there is no connection.
To edit a CSP 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
8.2.2 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.
Routine code explicitly identifies the running application and adds application roles:
102 Caché Security Administration Guide Applications
Set sc = $SYSTEM.Security.AddRoles(AppDefName)
where AppDefName is the name of the application definition and sc is a status code.
Note: The $SYSTEM.Security.AddRoles method is the AddRoles method of the
%SYSTEM.Security class.
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.
Note that while AddRoles always (as the name implies) adds roles, it can be used in conjunction with
SET $ROLES and NEW $ROLES if other functionality is required. This allows you to strip a user of any added roles that may grant excess privilege, and then add only those needed for the particular sit- uation.
To edit a privileged routine 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
• Editing an application: the Routines tab
8.2.2.1 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 be created: • The PRATestRtn routine
• The PRATestAddedRole role
• A privileged routine application called PRATestApp, which includes PRATestRtn and has
PRATestAddedRole as an application role
• A resource associated called PRATestRsrc, which is associated with PRATestApp • A role called PRATestRole, which has Use permission on PRATestRsrc
To test this, there are also two users: PRATestUser and NonPRATestUser. PRATestUser is a member of the PRATestRole and %Developer. NonPRATestUser is a member of %Developer only.
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,PRATestAddedRole 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>
104 Caché Security Administration Guide Applications
8.2.3 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 exe- cutable 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