fwAccessControl  8.4.0
JCOP Framework Access Control component

Introduction

The JCOP Framework Access Control component allows to implement access control mechanisms at the level of the PVSS panels.

It provides the developers with a simplified infrastructure for implementing the access control in their panels. For advanced use, the API (Access Control library) also provides exhaustive set of functions that may be used to perform all the activities related to the management and configuration of the access rights. For convenience, however, the panels provided with the component should rather be used.

A distributed Access Control management tool ("Access Control Server") is also provided to ease the integration and management of the access control in large distributed systems.

Integrating access control mechanism into a panel

To implement access control mechanism in a panel requires the use of two functions:

, adding two functions to the panel, and, unless already done, configuring the access control system to have domains, privileges, groups and users.

Assume an example panel, with a button called ExpertAction, which should be enabled only for the users who are authorized to perform the expert action. The access control is enforced by changing the state of the UI elements to enabled/disabled. To start with, implement a function that disabled all of the elements that you wish to protect with access control (note, however, that certain elements, such as "Cancel" button, should probably not be protected).
The function performing this task may be called, according to conventions, DisableAllInPanel . For the case of the discussed example, it should be placed in the General section of panel's scripts, and should contain the statement that disables the ExpertAction button:

* void DisableAllInPanel()
* {
* ExpertAction.enabled = FALSE;
* // other UI elements might be disabled in the same way
* }
*

Then, implement a function that enables the UI elements, depending on the access rights of the user currently being logged in. The function needs to accept two (dummy) string parameters and, according to conventions, is called ApplyPanelAccessControl ; the function should be placed in the general section of the panel's scripts. For the case of the example discussed here, it might be implemented in the following way:

* void ApplyPanelAccessControl(string s1, string s2)
* {
* // at first, disable whatever was enabled to this moment
* DisableAllInPanel();
*
* dyn_string exceptionInfo;
* bool hasExpertPrivilege=FALSE;
*
* // check if current user has privilege level "Control" in domain "MyDCS":
* fwAccessControl_isGranted("MyDCS:Control", hasExpertPrivilege, exceptionInfo);
*
* // check and handle exceptions that might have been thrown by the function above
* if (dynlen(exceptionInfo)) {fwAccessControl_displayException(exceptionInfo);return;};
*
* // enable UI elements, depending on the access rights:
* if (hasExpertPrivilege) ExpertAction.enabled = TRUE;
* }
*

The function above is going to be a "callback" function, called asynchronously whenever a user logs in or logs out.

The final step is therefore to register the function to the access control subsystem. to obtain this, the following piece of code needs to be put into the Initialize script of the panel:

* main()
* {
* DisableAllInPanel();
* dyn_string exceptionInfo;
* fwAccessControl_setupPanel("ApplyPanelAccessControl",exceptionInfo);
*
* // check and handle exceptions that might have been thrown by the function above
* if (dynlen(exceptionInfo)) {fwAccessControl_displayException(exceptionInfo);return;};
* }
*

Note, that the name of the callback function is passed as the first argument to the fwAccessControl_setupPanel function. Note also that in the code samples we used the fwAccessControl_displayException function for handling the exceptions - this function is equivalent to the fwExceptionHandling_display function of the Framework core. For more details about exceptions in the Access Control component refer to subsection Exception Handling below.

Setting up integrated Access Control in a distributed system

Since version 2.5.0 of the Access Control component it is possible to enable integrated mode for the management and configuration of the access control data in distributed systems, which run Framework-based projects. The integrated mode of operation allows to manage the access control - related data on a single system (referred to as "Access Control Server"), and automatically distribute any changes (new user accounts, group definitions, etc) to all systems that are managed by the Access Control Server.

To activate the Integrated Access Control mode of operation, perform the following steps:

  1. Choose the PVSS system that you wish to use as the Access Control server. It does not need to be a dedicated system, yet it needs to be able to contact all the systems (in the distributed system) that you wish to manage. Verify the distributed systems connection.
  2. Open the Access Control Toolbar on the server, and configure (create/update) the domains, groups and users. You may also want to import the AC objects (domains/groups/users definitions) from the "postInstall" scripts, the use of which is described in subsection Using the exported Access Control data. .
  3. Activate the Access Control server in PMON: append a CTRL Manager running the "fwAccessControl/fwAccessControl_Server.ctc" script to the PVSS Project Console on the server machine.
  4. Start the CTRL Manager that runs the AC Server (appended in the previous point).
  5. Configure the "client" machines in your system to be managed by the server. Two ways are possible
    • on each of the client machines you wish to be managed by the AC Server, open the AC Setup panel (available from Toolbar), and select the server name in the "Host" selector, in the "Integrated Mode" part of the panel.
    • alternatively, open the Access Control Server console panel on the system that runs the server. The panel will display the names of all systems currently connected to the server system. It will also indicate what is the current setting for AC Server on each of them.
      For each system you wish to manage with AC Server, right-click on its line in the table, and select "Bring up" - this will set its "AC Server" field to be the name of the server machine. Shortly after you should see that the machine is being managed by the server (see the output of the AC Server in the log window, and the status in the panel.
  6. To disable the integrated management for any of machines, either set empty "Host" in the AC Setup panel, or use the AC Server console to "release" the managed host, as above.
Note
Once a client machine is "managed" by the AC Server, all of its Access Control data is being overwritten by the data defined on the server, i.e. the user definitions, and password may be changed!
Once the integrated mode is activated for a "client" system, it will not be possible to perform the management of domains, groups and users locally!
A user may still change the password on a "client" system - the new password will be announced to the AC Server, and automatically populated to all managed hosts!
the "Host" field of AC Setup panel on the server machine will automatically be set to the name of the local system. Do not try to change it!

Exporting Access Control data for use with the Installation Tool

To export (a subset of) Access Control data one might use the Export... button of the Access Control Setup panel, or make use of the _fwAccessControl_exportToPostInstall function. These will bring up the panel that allows to select the Domains, Groups and Users that are to be selected, then it will create the file with given name, that will contain the CTRL script, suitable for using as a postInstall script for the installation tool, with commands that will create/update the objects that were exported.

Using the exported Access Control data.

To import the Access Control data from the "postInstall" script, simply run the script through the CTRL Manager. Note, however, that the postInstall scripts are by default placed in the config/ subdirectory, not in the scripts/ subdirectory, hence you may need to copy the file in an appropriate place to make it accessible to the CTRL Manager.

The scripts are built of calls to fwAccessControl_checkAddDomain , fwAccessControl_checkAddGroup and fwAccessControl_checkAddUser functions. These function does not "overwrite" the existing account, but rather updates them (i.e. they "append" access rights or group memberships to the exising ones, rather than overwrite them). If this is not a desired way to import the data, consider a review of the scripts beforehand.

Note
In the current release, no backup copy is created when AC Data is imported! Consider making backups (e.g. ASCII exports) of the datapoints of type _Users for the critical systems!

The use of API (advanced)

This documentation contains the descriptions of the high-level functions that are supposed to be widely available for developers. We believe that the only functions that are of general interest are the ones already described in section Integrating access control mechanism into a panel . For all the access control management purposes we believe that the set of panels provided with the component are sufficient. Nevertheless, custom solutions may be implemented based on functions described here.

Groups of functions

The functions are grouped in the following sections

Exception Handling

The use of dedicated exception-related routines in the Access Control component is motivated by the need of making the AC component independent of the Framework Core.

Exception handling in the Access Control component is fully compatible with exception handling provided by the Framework Core component. The exceptionInfo variables may be freely exchanged between both implementations. In fact, if the Core component is installed, the AC exception functions are only wrappers over the Framework Core's function:

fwAccessControl:fwCore:
fwAccessControl_raiseExceptionfwException_raise
fwAccessControl_displayExceptionfwExceptionHandling_display

there are however simplified implementations for the case when Fw core is not installed.

A similar "wrapper" functionality exists for the online-help buttons used in the panels.

Technical details of the AC Server

  • there is a request-response protocol for communication between clients and servers. it uses the elements of the internal AC datapoints, and a dpQueryConnect-based mechanism. Clients write their requests to their own datapoints, and these requests are tracked by the AC Server. For the clients managed by the AC Server, the requests are actually processed by the Server, and replies are sent as dpSets to the client's datapoints.
  • requests for password change that are sent from clients to the AC Server are encrypted using an algorithm based on a popular (yet non-trivial) symmetric key encryption scheme. Because of that we distribute the Access Control component in form of the encrypted PVSS library. If you are interested in the actual implementation details, or using the encryption/decryption functions for your projects, please contact the ITCONTROLS.SUPPORT team.
  • to protect your AC Server, you may consider "firewalling" the AC Server - either by means provided by the operating systems, or PVSS's Access Control Lists

Customizing the Access Control component

How to change the default "logo" picture in the login an password-change panels?

Copy the file containing the "logo" picture in the BMP format, into the pictures/logo.bmp file in your project (or components) folder.

  • Hint: Note that the FSM component already contains the logos for the LHC experiments: you may want to reuse them - they are in the pictures/logo_*.bmp files of the FSM component installation directory.

How to customize the authentication method?

Note
Customizing the authentication method (i.e. implementing a custom mechanism of password checking, based, for instance, on NICE, AFS, Kerberos, LDAP or Oracle) is not yet possible in version 2.5.0 of the component.