Access Control component
|
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.
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.
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:
"fwAccessControl/fwAccessControl_Server.ctc"
script to the PVSS Project Console on the server machine.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.
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.
_Users
for the critical systems!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.
The functions are grouped in the following sections
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_raiseException | fwException_raise |
fwAccessControl_displayException | fwExceptionHandling_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.
ITCONTROLS.SUPPORT
team.Copy the file containing the "logo" picture in the BMP format, into the pictures/logo.bmp
file in your project (or components) folder.
pictures/logo_*
.bmp files of the FSM component installation directory.