User Authorization Interface

13.11. User Authorization Interface

UAI Plug-in #

SICS has an extension point called the User Authorization Interface (UAI). This is a Java interface which by default is deactivated. The client may create a Java implementation for the interface, add (plug in) the implementation to the installed SICS runtime and enable the UAI.

Hereafter, the client-specific implementation of the UAI is referred to as the plug-in.

By installing a UAI plug-in and enabling the UAI, SICS will offload some of the user authorization work to the plug-in.

The UAI applies to the SICS Workstation, SICS System Administration Utility and SICS API Server. Most of the description is written in the context of SICS Workstation / SysAdmin Utility. There is a separate section describing details for SICS API Server.

Authorization Basics #

Authorization is the process of controlling what an end-user is allowed to do. In SICS, authorization is linked with the SICS user object. This means that every person who wants to use SICS, must be defined as a user in SICS. The SICS user object is stored in the SICS database in the CNU_USER table.

SICS applies three authorization objects to determine the access rights of a SICS user. They are:

  • Use-case: This defines a function in SICS; for example Create Business, and the use case determines access to that function.
  • Domain restriction: The domain restriction defines values for a particular data-related aspect, for example a list of Main Classes of Business, or a list of reporting units. The domain restrictions are used to control access to data.
  • User role: The user role is a grouping of zero, one, or more use-cases, plus zero, one or more domain restrictions.

A SICS user is never linked directly to use-cases and domain restrictions. Rather, roles are used to associate users with use-cases and domain restrictions. Each SICS user is given access rights by assigning one or more roles to the user. Each role can be assigned to several users.

If more than one role is assigned to a SICS user, the following applies:

  • For use-case control, SICS uses the union of all use-cases of all assigned roles.
  • For domain restriction control, SICS blocks access to data if any domain restriction in any assigned role does not match the data.

UAI Basics #

With the UAI activated, some parts of SICS authorization are offloaded to the plug-in.

What does not change:

  • SICS user information (name, preferences, etc) is stored in the SICS database, as per standard (no UAI plug-in) functionality. However, the actual creation of a new SICS user object may optionally be controlled by the plug-in (see below).
  • User roles are defined in SICS, as per standard functionality
  • Each user role may contain a number of use cases only, a number of domain restrictions only, or a combination of both use cases and domain restrictions, as per standard functionality
  • User roles may or may not be assigned to SICS users, however, such assignments will be ignored when the UAI is activated

What is offloaded to the plug-in:

  • The linking between users and user roles. In this way, it is possible to control from the outside of SICS what user roles (and thereby, what use cases and domain restrictions) should apply to each and every user. For instance, one could maintain user authorization (user access rights) in Windows Active Directory or some other kind of LDAP.
  • Optionally, the plug-in may request a new SICS user object to be created or existing SICS user object to be disabled. In this way, it is possible to control from the outside of SICS what end-users are allowed to use SICS.

UAI Details #

A SICS session starts with the end-user logging in to the SICS Desktop (SICS Workstation) or the SICS System Administration Desktop. The first part of the login procedure is to authenticate (identify) the user and establish a connection to the database. This can be done in a number of ways as described elsewhere. This part does not change when the UAI is active.

The following description assumes the UAI is active.

After authenticating the user and establishing a connection to the SICS database, SICS will:

  • Check whether a SICS User Object exists in the SICS database (in the CNU_USER table). The user’s ID (provided during login) will be used to do this check.
  • If the user exists, check whether the user is currently active or not.
  • Call the UAI plug-in, providing following input parameters:
  • The user ID
  • A true/false flag indicating whether a SICS User Object exists or not
  • A true/false flag indicating whether the SICS User Object is active or not
  • The database environment selected during login
  • The Database Description system parameter (if set)

The plug-in must return:

  • An action field. Valid values are, ‘NO_ACCESS’, ‘DISABLE’, ‘CREATE_USER’, ‘OK’.
  • An optional message text. If present, it will be presented to the user. Typical use would be to provide a custom message to replace the default SICS message when the action is ‘NO_ACCESS’ or ‘DISABLE’.
  • A user data structure, required only when the action is ‘CREATE_USER’.
  • A list of ‘user role specification’ objects (Java objects).
  • A template user id (optional), when the action is ‘OK’.

Action Handling #

If the plug-in returns the action value ‘NO_ACCESS’, then the login will be terminated with a message.

If the plug-in returns the action value ‘DISABLE’, then user will be set as inactive in SICS and login will be terminated with a message.

If the plug-in returns the action value ‘OK’, the user roles will be assigned to the user as described below. The user will also be reactivated in the case it was inactive.

When the action is ‘OK’ and a template user id is provided in the response then the following user settings will be updated with the values from template user if they don’t match:

User Properties » Access Code Privileges » General Tab

  • Has Access to SICS P&C
  • Has Access to SICS Life
  • Allow Global Data View (all Access Codes)
  • Allow User to Switch to Any Access Code
  • Active Access Code

User Properties » Accounting Settings

  • Allow Booking Ignoring Specific Closure Terms for Technical and Claim Worksheets

User Preferences » Access codes

  • Enable Global View

If the plug-in returns the action value ‘CREATE_USER’, then a new SICS user object will be created. In this case, the user data structure mentioned above is mandatory. In this data structure the following information should be provided:

User ID (mandatory)

First name (mandatory)

Last name (mandatory)

DB User ID (optional)

DB Password (optional)

User ID of template user object (optional)

The template user object is used as a means to provide various data fields without having to provide them over the interface. One or more ’template’ user objects may be defined in SICS. For instance, one may create template users that have varying responsible roles, access codes, P&C/Life access, etc. The template users should all be flagged as ‘inactive’ (in as much as they do not represent real users), and they should not be assigned any security roles (because these will anyway be provided by the plug-in).

When the action is ‘CREATE_USER’, a new SICS user object will be created, with the given information. If there is no template provided, default values will be applied for all fields except the ones provided in the response from the plug-in. If there is a template, it will be copied to the new user object except for the fields provided in the response from the plug-in. However, should the template contain user roles, they will not be copied.

If the user already exists in the database, a warning will be issued and the login will continue without applying any change to the existing user apart from reactivating if it necessary.

The optional fields DB User ID and DB Password are related to two-level login. These fields must be provided if two-level login is desired. In such a case, SICS will reconnect to the database using the provided two-level fields, and then create the new SICS user object.

After the user is created, the system will operate exactly as after receiving an OK action from the UAI.

User Role Setup #

A ‘user role specification’ object must either name a single user role or contain a list of user role names. When it contains a list of user role names, it means this object is a ‘combination specification’ and the listed user roles contain domain restrictions which should be combined.

The plug-in can throw Java exceptions. SICS will handle them by displaying the exception’s message and terminating the login.

How SICS will process the response from the interface plug-in:

  • SICS will retrieve from the database those user role objects which correspond to the user role names returned from the plug-in. SICS will ignore names which do not have a corresponding user role object in the database.
  • The user roles which are named as single roles will be linked to the user object.
  • The user roles which are listed in ‘combination specification’ objects will be used for creating temporary user roles (one for each combination object) with domain restrictions. These temporary user roles will also be linked to the user object. The temporary user roles / domain restrictions will NOT be written to the database.
  • This linking of user roles (existing and/or temporary) to the user object is temporary (for the duration of the SICS session) and will NOT be written to the database.
  • The user roles assigned (linked) in this way, will determine which functions and data are accessible to the user, as per existing functionality.

Currently, the ‘combination specification’ feature is meant to allow flexible assignment of Business Structure domain restrictions, for example, controlling what classes of business the user should have access to.

How SICS will process each ‘combination specification’ object:

  • The user roles corresponding to the listed names will be retrieved from the database.
  • The use cases (if any) linked with these roles will be ignored.
  • The domain restrictions linked with these roles will be put into an ordered list, in the order the roles are listed in the ‘combination specification’ object, and in the order the domain restrictions have within each user role.
  • Any domain restriction which is not of the type ‘Business Structure’ will be removed from the ordered list.
  • Any ‘Business Structure’ domain restriction which has a filter of type ‘Predefined Decision’ or ‘Composite’ will be removed from the ordered list.
  • The first (remaining) domain restriction in the ordered list is called the leader.
  • The leader’s filter determines the target type of filter to set up in the temporary user role which is about to be created. Note that the target filter type is for sure one which contains a list of data values, for example a list of Type of Business codes, or a list of Base Companies, or a list of Reporting Units, etc.
  • Any domain restriction which has a filter not equal to the target filter type, will be removed from the ordered list.
  • Now all remaining domain restrictions in the ordered list are of the type ‘Business Structure’ and they all have the same kind of filter.
  • A new, temporary ‘Business Structure’ domain restriction will be created, with a filter of the target type. This filter will be set up with the combined list (union) of all filter values from all domain restrictions remaining in the ordered list. Furthermore it will be set up with an ‘Access revocation’ list copied from the leader (note 1).
  • A new, temporary user role will be created, containing the above temporary domain restriction.

Note 1: Each domain restriction needs an ‘Access Revocation’ list (consisting of use cases), otherwise the domain restriction will have no effect. Because the ‘Access Revocation’ list for the temporary, combined domain restriction is copied from the leader, it would be useful from a maintenance point of view to define the ‘Access Revocation’ list in a user role separate from the use roles containing the filter values to be combined.

For example, assuming we want control access based on Reporting Units:

Create user role R1 containing a ‘Business Structure’ domain restriction with a ‘Reporting Unit’ filter. Let the filter’s value list be empty. On the ‘Access Revocation’ tab add the wanted use cases.

Create user role R2 containing a ‘Business Structure’ domain restriction with a ‘Reporting Unit’ filter. Add one or more reporting units to the filter. Let the filter’s ‘Access Revocation’ list be empty.

Create user role R3 similar to R2, but with a different list of reporting units.

Now the two lists of reporting units can be combined by returning from the security plug-in a ‘combination specification’ object which lists the role names R1, R2, R3 (or R1, R3, R2 - the important thing is to list R1 first, because it contains the ‘Access Revocation’ list).

UAI and SICS API Server #

SICS API Server can be run in secure or non-secure mode. This is described in a separate “SICS API Server Security” document and is not described further here.

Running SICS API Server in Secure Mode #

The client must initially call the ’login’ web service. Along with the login SOAP request, the client will pass a userid. SICS API Server will call the UAI with this userid in order to get the authorization for the user logging in.

The authorization data retrieved from the UAI will be cached in SICS API Server for each user who logs in. The cache will be reset (i.e. there will be new calls to the UAI) when,

  • A user logs in again (possibly because the security token has expired)
  • The ‘fullRefresh’ web service is called
  • SICS API Server is restarted.

Running SICS API Server in Non-secure Mode #

In this case, all web service requests run under one and the same userid, namely the userid provided in the startup parameters to SICS API Server. This userid is used to connect to the database. This userid will also be used to set up authorization, through a call to the UAI.

The authorization data retrieved from the UAI will be cached in SICS API Server. The cache will be reset (i.e. there will be new calls to the UAI) when,

  • The ‘fullRefresh’ web service is called
  • SICS API Server is restarted.

Installing and Activating the UAI #

Naming the Plug-in #

The name of the plug-in must be provided in the SICS 4 installation file:
sics.global.resource.registry.properties.

For example, the line:
UserAuthorizationInterface=com.csc.sics.userauthorizationinterface.test.SicsUserAuthorizationTestInterface

will tell SICS to use an instance of com.csc.sics.userauthorizationinterface.test.SicsUserAuthorizationTestInterface.

Activating the Interface #

The system parameter for activating the interface must be set. This is done from the menu bar of the SICS Access Security Manager window.

inset_2100573.jpg

Activating/deactivating the UAI is controlled by the overall Security Administration use case:

inset_2200575.jpg

Test / Example Implementation #

The SICS installation includes an implementation of the User Authorization Interface, named com.csc.sics.userauthorizationinterface.test.SicsUserAuthorizationTestInterface. This implementation can be used to test / demonstrate how SICS behaves when the UAI is active. Please see sics.userauthorizationinterface.jar in the installation’s \lib folder for details. A client wanting to use the UAI for real, would have to program a bespoke Java implementation.

UAI Plug-in Security #

UAI ‘plug-in security’ refers to the optional ability for SICS to verify that the UAI plug-in (.class file) has not been tampered with. The UAI plug-in is secured with a 44-character Base64-encoded SHA256 hash value.

SICS provides a utility to generate the 256-bit SHA256 hash value of the customer’s UAI implementation .class file and convert it to a 44-character Base64 value. The utility sha256Hash.bat is available in the /runtime folder of the SICS installation.

In order to activate UAI plug-in security, the generated Base64 value must be inserted as a key-value pair in the global system parameter registry, at the key UAI\_HASH\_KEY.

At startup, SICS will then verify that the SHA256 hash of the current UAI implementation .class file is the same as the system parameter registry value.

The following SQL script should be used to insert the generated Base64-encoded SHA256 hash value as a key-value pair in the global system parameter registry. Replace with the generated hash value.

INSERT
INTO SYS_PARAM_VALUES (OBJECT_ID, PARAM_KEY, PARAM_VALUE, FK_OWNER)
VALUES ( sys_guid(),
  'UAI_HASH_KEY',
  '<Generated Hash Value>',
  (SELECT SP.OBJECT_ID
  FROM SYSTEM_PARAMETERS SP
      WHERE SP.FK_BASE_COMP IS NULL
      AND SP.FK_REP_UNIT    IS NULL
      AND NOT EXISTS
     (SELECT OBJECT_ID FROM SYS_PARAM_VALUES SPV WHERE SPV.FK_OWNER = SP.OBJECT_ID AND SPV.PARAM_KEY = 'QUALIFIER')));

The value should be re-generated and replaced in the system parameter registry whenever the customer modifies the UAI plug-in.