Skip to main content

Zen Security

You can provide application-level security for Zen using a combination of a Zen form and system configuration settings. For background information, see the section “Application Resources and Their Privileges” in the “Assets and Resources” chapter of the Caché Security Administration Guide. For instructions, see the next section, “Controlling Access to Applications.”

There are additional techniques for controlling access to individual pages and components within a Zen application. See the sections later in this chapter, “Controlling Access to Pages” and “Controlling Access to Components.”

Controlling Access to Applications

By default, when a user starts your Zen application it prompts the user to log in by displaying the standard Caché username and password dialog box. If you wish your application to present a custom login form, you must create and configure this form as follows:

  1. Create a new Zen page class.

  2. Within XData Contents, provide a <loginForm> component. <loginForm> is a special-purpose component that simplifies the development of login pages and ensures that login processing is handled entirely by CSP.


    To create a custom login form, you must use <loginForm>. Other approaches for creating login pages in Zen applications can cause problems of various kinds.

  3. Make sure that the <loginForm> contains the following controls:

    • <text name="CacheUserName"/> for the username

    • <password name="CachePassword"/> for the password

    Ensure that you provide a name attribute for each of these controls and that the corresponding name values are exactly as shown above: "CacheUserName" and "CachePassword". You may provide other attributes for the controls as desired; a label is useful for each control so that the user knows what to enter.

  4. Provide a <submit> button. By default, pressing Enter triggers a form submit. If you do not want this behavior, add the attribute ondefault="return true;" to the <loginForm> definition. Your minimal user login form now looks like this:

    <page xmlns="" title="">
      <loginForm id="loginForm" >
        <text name="CacheUserName" label="User:" />
        <password name="CachePassword" label="Password:" />
        <submit caption="Login" />
  5. Define other characteristics of the form as desired.

  6. Start the Management Portal.

  7. Navigate to the Web Applications page (System Administration > Security > Applications > Web Applications).


    For background information about this step, see the “Zen Application Configuration” section in the chapter “Zen Application Programming.”

  8. Find the appropriate web application in the list and click its Edit button. The Web Applications page (System Administration > Security > Applications > Web Applications) displays.

  9. In the Login Page field, enter the package and class name of your new Zen page class. Be sure to include the Web application Name at the start of the path, for example:


  10. Click Save.

A change password form is also possible using the <password> component. You must use "CacheOldPassword" as the name of the control containing the old password value, "CachePassword" as the name of the control containing the new password value, and "CacheRepeatPassword" as the name of the control where the user retypes the new password value for verification. Also, when you configure the application you must identify this Zen page as the Change Password Page rather than the Login Page:

<page xmlns="" title="">
    <text name="CacheUserName" label="Name:"/>
    <password name="CacheOldPassword" label="Old Password:"/>
    <password name="CachePassword" label="New Password:"/>
    <password name="CacheRepeatPassword" label="Retype New Password:"/>
    <submit caption="Submit"/>

Controlling Access to Pages

Each Zen page has a class parameter called RESOURCE that, if defined, provides the name of a system Resource for which the current user must hold USE privileges in order to view this page or to invoke any of its server-side methods from the client.

For background information about class parameters such as RESOURCE, see the “Page Class Parameters” section in the chapter “Zen Application Programming.” To understand what a system Resource is and what the USE privilege means, see the section “Application Resources and Their Privileges” in the “Assets and Resources” chapter of the Caché Security Administration Guide.

Controlling Access to Components

Each Zen component (subclass of %ZEN.Component.componentOpens in a new tab) has a server-only property called %resource that determines whether or not this component should be added to the set of page components. The component projects this property to XML as an attribute called resource. You can use this resource when adding a component to XData Contents. For example:

<button id="myButton" caption="Press Me" resource="ADMIN" />

If a resource value is specified, the current user must hold USE privileges on this resource or the component is not added to the set of page components when the user attempts to display the page. This property is not available from the client.

Legacy Application Access

It is possible to use Web Application Configuration page of the Management Portal, as described in “Zen Application Configuration,” to permit “Unauthenticated Access.” This setting allowed applications implemented prior to Cache 5.2 to continue working without requiring changes. InterSystems does not recommend using this setting on production systems for any application. The only time this setting should be used on a production server is for a legacy application for a short period of time until the existing application is modified to run securely with access controlled by Roles and Resources. There may be cases on development systems where it is convenient to allow an application to run with “Unauthenticated Access” until the application under development is ready to interact with Caché Security. But you must be aware that %UnknownUser of such a web application is running with %ALL as a role and likely has the privileges of the account used to start and stop the system with regard to operating system level privileges.

FeedbackOpens in a new tab