Working with OpenPetra Security

Overview

OpenPetras' security system is based on PETRA 2.x's security system.

• Module Security is implemented in OpenPetra.
• Table Security is implemented in OpenPetra.
• Security Groups: not fully implemented - while security groups exist in the DB, they can at present not be assigned to users.

Enhancements that would allow more fine-grained security and other special features are planned. Provision for those enhancements are already in the DB Schema, but no functionality to access those DB Tables is implemented yet.

Specifying OpenPetra Module-level Security for Screens (Client-side)

• UINavigation.yaml file
  • The 'PermissionsRequired' Element of a Task, Sub-Module or Module determines the Module-level security of the Task/Tasks. This is used solely for the purpose of disabling Tasks in the Main Menu that the user hasn't got access to, and for prohibiting the launching of such Tasks, should the disabling somehow not work. In other words, this doesn't prevent the opening of the screen from anywhere other than from the Main Menu in case the user hasn't got access to that screen (e.g. when that screen gets launched from another screen)!
  • Petra 2.x equivalent: There isn't an equivalent to that concept in Petra 2.x - Menu Items are always enabled there, no matter whether users have access to them, or not.
• Screens usually load data from the server when they are opened. For those screens the server-side specification of OpenPetra Module-level Security for Screens is sufficient as that will prevent the opening of the screen in case the user hasn't got access to that --> Details.
  • Petra 2.x equivalent: calls to {sm22001.i} in the 'Main Block' of a Form.
• Screens that do not issue a server call when they are opened: relevant security checks will need to be 'hand-coded' in the Load Event of a Form --> Details.
  • Petra 2.x equivalent: calls to {sm22001.i} in the 'Main Block' of a Form.

Specifying OpenPetra Module-level Security for Screens and their functionality (Server-side)

A public Method of a WebConnector can be decorated with a [RequireModulePermission("xxx")] Attribute, where 'xxx' is the Module, e.g. 'FINANCE-1', or 'NONE' (the latter enforces nothing!). Whenever a Method that has that Attribute is called trough its Instantiator Class the Module security is enforced (by a call to Method 'Ict.Petra.Server.App.Core.Security.TModuleAccessManager.CheckUserPermissionsForMethod, which throws an Exception in case the user doesn't have access to the specified Module).

Advanced: It is also possible to AND and to OR Modules in the following way: AND(xxx, yyy) or OR(xxx, yyy). Examples:

• RequireModulePermission("AND(PERSONNEL,PTNRUSER)")
• RequireModulePermission("OR(PTNRUSER,PERSONNEL,FINANCE-1)")

Special case: if ALedgerNumber is contained in the Arguments of a WebConnector Method that has got a [RequireModulePermission("xxx")] Attribute: In that case a check that the user has got access to the Ledger that is requested in this Argument is done, too!

Extending OpenPetra Module-level Security Model for new Argument Types

If a new, so far unrecognized Argument Type is used in a server-side Method that has got a [RequireModulePermission("xxx")] Attribute, the 'glue' will get generated, but when the Method gets called an error occurs ('Error: Missing definition of access permission for method abc in Connector class xyz').

To add a new Argument Type, two files need to be modified:

• csharp\ICT\BuildTools\GenerateGlue\CreateConnectors.cs, Method 'CreateModuleAccessPermissionCheck'
• \csharp\ICT\Petra\Server\app\Core\ModuleAccessManager.cs, Method 'CheckUserPermissionsForMethod'

For an example of this see https://git.ict.om.org/OpenPetraTeam/openpetra/-/tags/REV_4247

Programmatically Accessing an OpenPetra Users' Security Details

An OpenPetra Users' Security Details can be easily accessed both on the client and on the server side, using the same mechanism.

UserInfo Class

• The UserInfo Class is populated with data from the DB when the user logs in. Refreshing of that data is not possible at present once the user has logged in (that could be desirable when the System Administrator changes permissions for a logged-in user, though).
• The GUserInfo property has various Methods to check different security aspects: IsInModule. IsTableAccessOK, etc.

Note: Though the TPetraPrincipal Class has Fields 'FRoles' and 'FFunctions' Fields and a Method 'IsInRole', those aren't populated/are not returning anything useful as they tie in with the planned improvements to the security model.

TODO

Client-side specific

• On the client side we have a convention of coding OpenPetra Users' Security checks into Forms and UserControls in a standard way: we create a Method called 'ApplySecurity' in the relevant *ManualCode.cs file and add code to that that performs the necessary checks. That Method is usually called when a Form is opened or a UserControl gets instantiated.

For an example of such a Method refer to \csharp\ICT\Petra\Client\MCommon\Gui\UC_PartnerAddresses.cs. There you also see the standard XML Documentation that we decorate such a Method with.

TODO