Summary

It is sometimes necessary to temporarily prevent access to a system. While this can be done simply by stopping the server, would-be users then encounter an uninformative "page not found" message while the system is unavailable. A better method is to provide a message explaining the service interruption and providing access to those who still must log in to the application, while denying it to everyone else. Once you have set up this capability, it should be possible to invoke it and disable it quickly and smoothly.

This article describes one approach to temporarily block additional logins. While access is blocked, only one or selected users will be able to log in to the system. Any users already logged in, however, will not be forced out.

Note: Some hardware-based load balancers can temporarily redirect user HTTP requests to a fixed "not available" page. If your system includes such capabilities, you can use them instead of the approach described here.

Suggested Approach

1. Create a RuleSet and Version to hold the rules needed for this capability.
2. Provide a way of displaying a user-friendly message.
3. Create an activity that checks whether a Dynamic System Setting is "true" or "false", and accordingly allows or prevents user log-ins.
4. Associate the new RuleSet Version with the system's "unauthenticated" access group.
5. Prepare a method to override the rule in an emergency.
6. Test the activity by preventing a specific operator from logging in.
7. Adjust the activity to allow only a specific operator ID or access group to log in when the Dynamic System Setting value is "false".

Step by step:

1. Create a new RuleSet to hold the rules needed for this behavior. Select Application > New > RuleSet, and give the new RuleSet a name. The RuleSet in this example is VisitorsNotLoggedIn.
   
2. Create a Version for the new RuleSet. Select Application > New > SysAdmin > RuleSet Version and provide a version number.
   
3. Create an image with a helpful message to display on the login screen when the application is not available. You can also create a modified image to display when the application is available, or you can continue to use the default image. The images should be 400 x 600 pixels, and .jpg or .gif format.
4. Add the image or images to the RuleSet Version.
   For each image:
   1. Select Application > New > Rule > Technical > Binary File to display the new Binary File form.
   2. Give the image a name of your choice, set its directory as "webwb", specify the file format of the image you will use, and make sure it is in the RuleSet Version you created for this function.
      
   3. Click Create. On the next screen, click Upload File to display the File Upload dialog. Specify the source file for this image and click Upload file.
      
   4. Save each rule once the image has been uploaded.
5. Create a Dynamic System Settingto hold a Boolean (true/false) value. If this value is "true", all users will be able to log in. If it is "false", the application will prevent new logins except by an authorized user and will display an appropriate message.
   1. Select Application > New > Rule > SysAdmin > Dynamic System Settings. Enter the name of the RuleSet you created as the Owning Ruleset and give the dynamic system setting a meaningful name in the Setting Purpose field. (A dynamic system setting is a data instance, not a rule, although the first key part identifies a RuleSet.)
      
   2. Click Create. On the next screen, set the Value to "true". Save the rule.

   To learn more about dynamic system settings, read Understanding System Settings.

6. Create an Operator ID, or select an existing one, to test the function when it is complete. This will be the only user account that will be able to log in when the AllowLogins dynamic system setting is set to false. In this example, the operator ID is "[email protected]".
7. Create a When Rule that will check the dynamic system setting.
1. Select Application > New > Rule > Decision > When. Enter "@baseclass" in the Applies To field, give the When rule a meaningful name, and make sure the RuleSet and Version you created for this function are selected.
   
2. Click Create. On the next screen specify the dynamic system setting the When rule will evaluate. The formula is
   When @getDataSystemSetting(RuleSetName, DynamicSystemSettingName) COMPARISON VALUE.
   
   When you write the When rule condition, the screen will look like this:
   
3. Save the When rule.
8. Modify the login screento display the appropriate image depending on whether AllowLogins is true or false.
   1. Open the standard HTML rule @baseclass.Web-Login.
   2. Save a copy of the rule into the RuleSet Version you created for this feature, preserving the name.
   3. The default image on the login screen is image19.gif. In your copy of the rule, locate the section of HTML code that references that image:
      
   4. Edit the section to display a standard image when the AllowLogins dynamic system setting is true, and to display an image with a useful message when AllowLogins is false. Use a pega:choose section to check the dynamic system setting. The HTML code should look like this (in this example "image19nologin.jpg" is the image with the helpful message that will display when users cannot log in):
      
      div#logo span{
      border: 1px solid #393b43;
      display: block;
      width: 600px;
      height: 400px;
      <pega:choose>
        <pega:when name="IsAllowLogins">
         background-image: url(images/image19.jpg);
        </pega:when>
       <pega:otherwise>
        background-image:   url(images/image19nologin.jpg);
       </pega:otherwise>
      </pega:choose>
      }
      
      If you have not provided an image to overwrite the default image when users are able to log in, then the eighth line of the sample above would read
      background-image: url(images/image19.gif);.
   5. Save the HTML rule.
9. Create an activity to prevent logins.
   1. Open the standard activity Code-Security.ApplicationProfileSetup. Save a copy to the RuleSet and Version you created for this feature, without changing the rule key. This activity is an empty "extension point" that is called during logon.
   2. Your ApplicationProfileSetup activity checks whether IsAllowLogins is set to false. If it is false, the activity intercepts new log-in attempts (except those using a specific operator ID) and redirects users to the logged-out page. It does not affect the session of anyone who is already logged in.
      
      To test the activity, first write it so it only intercepts login attempts using the test operator ID you created in step 6. Expand the Precondition by clicking the check mark to the right of the Description field.
      
   3. Enter a description of the activity in the Description field, and enter "Call Code-Security.logoff" in the Method field (note the comment below about a warning).
   4. Create two rows in the Preconditions section. The first row checks whether IsAllowLogins is true. If it is, the activity ends. If it is false--that is, if one or more accounts are to be prevented from accessing the application--the activity continues to the next Precondition.
   5. The second row checks whether the current login attempt should be blocked. Enter 'OperatorID.pyUserIdentifier=="[email protected]"' (using the operator ID you created) in the When field. Set the if True field to "Skip Whens" (that is, stop checking conditions and just perform the log-out) and the if False field to "Exit Activity".
   6. Save the activity. Note the warning that appears:
      
      In this case it is appropriate to ignore the warning.
   7. Important: if you make a mistake it is possible that the activity will log out everyone, not just the people you intend to log out. In that case you will not be able to use or repair the application until a database administrator can delete the activity from the pr4_rule table. Click the Rule Data icon on the tool bar to display the activity's pzInskey:
      
      Copy the pzInskey and paste the information in a text file outside of the application, in case there is a problem and the database administrator needs it.
      
10. Associate the RuleSet Version with the 'unauthenticated' group. Your system includes an access group for visitors who have not yet logged in to, and those who have logged out of, the application. Typically, this is the PegaRULES:unauthenticated access group. Locate this Access Group in Security > Access Group and associate with it the RuleSet Version you created for this function.
    
11. Test the Dynamic System Setting.
1. Set the Dynamic System Setting to true and try to log in using the test operator ID you created in step 6, and then with your own credentials. In both cases you should see the "good" image on the login screen and be able to log in normally.
2. Set the Dynamic System Setting to false. You should see the login screen image with the helpful message, but you should still be able to log in normally with your own credentials.
   
   You should not be able to log in with the test Operator ID, as you set the application to reject that account in step 9. When you try, the application redirects you to the logged-out screen.
12. Put the activity in its final form. When you are satisfied that the function is working properly, modify the Application Profile Setup activity you created so that it prevents anyone exceptthe test account from logging in.
    1. Open the ApplicationProfileSetup activity you created.
    2. Modify the When statement in the Activity Precondition by changing "==" to "!=".
       
    3. Save the activity, log out of the application, and try to log in with the test operator ID you created. You should be able to to log in with no problem. However, you now should not be able to log in with any other account.
    4. When you are sure the entire configuration works properly, replace the test Operator ID with one related to the account of the person who will be responsible for enabling and disabling logins. Verify that the function continues to behave as outlined. (Alternatively, you can allow access based on an access group name, organization or division, or other clipboard property.)
    5. Set AllowLogins to true.
13. Lock the RuleSet Version. Check the Lock this Version? check box on the Security tab, and provide a password in the Password to Unlock this Version field.
    
14. Document your work. Document the steps to toggle the dynamic system setting, the Operator ID that will always be allowed to log in, the password to unlock the RuleSet Version, and the pzInskey of the activity that may be needed if there is an access problem.