Customising the Access Control Unit

 

Note: All references to files and directories in this manual are relative to the Nesstar Server installation directory. For example, if you install your server in c:\nesstar-server then the reference config\policy.acu corresponds to the file c:\nesstar-server\config\policy.acu.

Modifying challenge forms

The authentication page in a Nesstar 4 server installation is really just another Webview page. That means it can be customized in the same way as all other webview resources are customized:

  • If all you want to do is cosmetic changes, you will have to edit the ./jboss/server/default/deploy/webview.war/skins/default/css/custom.css file. There is a div around all login elements with the id "login", inside this div is a form with the id "loginform" and a new div with id "unregistered" containing the instructions for unregistered users.
  • If you want to change the text displayed, the displayed text is fetched from the language files. These can be found in jboss/server/default/deploy/${CLIENT_WAR}/WEB-INF/classes/nesstar/webclient/translation/messages_${LANGUAGE_CODE}.properties. Make sure you edit the file for all used translations. The relevant keys in these property files are login_access_control, login_access_control_verbose, login_username, login_password, login_button, login_unregistered, login_unregistered_verbose, and login_authentication_failed
  • Finally, if you want to change the whole page radically, you will need to edit the template file. this file can be found in jboss/server/default/deploy/${CLIENT_WAR}/WEB-INF/classes/nesstar/webclient/templates/default/login/loginform.vm. It is basically an HTML document with some added serverside logic.

Understanding the default access control policy

A default access control policy comes pre-installed with the Nesstar Server. The policy provides a basic access control which constitutes a significant level of security. In most cases the default policy will be enough to meet your requirements.

The policy file is written in a rule-based formal programming language. The elements in the policy file are organized in various sections and structured as hierarchies.

The text of the default policy can be found here.

Policy Hierarchies

Hierarchies are defined for the following subjects:

  • the users.
  • the actions that the user can perform.
  • the objects on which the user performs the action.
  • the purpose or the project for which the user performs the action.

All the subjects [Users, Actions, Objects, Purposes] need to be declared in the corresponding hierarchy before they are used in a rule.

The following is an example of an object hierarchy:

hierarchy objects

    common.Server.
    common.Statement.
    faster.Catalog.
    faster.Study.

end

Object hierarchies in the default policy need to define just the basic type of objects, operations and users. More complex hierarchies can be defined for more specific policies.
More information about hierarchies is available in the appendix

Once the hierarchies are defined, you can create the rules.

Policy Rules

There are two types of access control policy rules - permissions and restrictions:

Users [of aProject project] CAN use anObject [for aPurpose purpose] [IF condition].

Users [of aProject project] CAN use anObject [for aPurpose purpose] ONLY IF condition.

A set of rules on an object is interpreted by the access control unit in the following way:

  1. All the permissions are connected by OR
  2. All the restrictions are connected by AND
  3. Restrictions and permissions are combined by AND

An example of a permission (from the default policy file):

authorisedUser can access objects.
This permission states that all authorized users can access any objects in the server. The action 'access' is defined in the action hierarchy and, in the default policy, browsing, searching and analysing will fall into this category.
fullauthorisedUser can download objects.
This one states that full authorized users can download objects (or part of them).

Restrictions are used in particular cases when an extra degree of security is needed on a particular set of data. The default policy does not use restrictions.

The default policy defines a set of rules that applies to a small set of users.

Example of hierarchy: 
hierarchy users

    authorisedUser.
    fullauthorisedUser extends authorisedUser.
    publisher extends fullauthorisedUser.
    administrator extends publisher.

    guestuser.

end
The following is a list of the users and permissions in the default policy:
  • anonymous users: users that are not logged in can browse and search metadata on the server.
  • authorised users: users can perform statistical operations on studies and cubes; also authorised users can create, use and delete cubes and derived variables.
  • Fully authorised users: such users can download data or a subset of data.
  • Publisher users: users can publish metadata and data.
  • Administrator: can perform any operation on the server.
  • Guest users: users have the same rights as anonymous users.
All the users defined in this description, by default, inherit the rights from the category they extend.

Modifying the access policy

You can modify the default policy to meet your requirements if necessary.

Restore the Server

Before you make any modifications, it is worth noting that the Nesstar Server can be restored to the default settings. To restore the server you need to do the following:

  • Open the 'Configuration Tool'.
  • Open the 'Customisation' menu.
  • Select 'Access Control Policy Editor'.
  • Open the 'Update' menu
  • Select 'Restore Server'.
You can also run 'compile_ext default' at command line in the bin directory.

Modifications

The access control policy file is located in the config directory. The file may be edited with Notepad, or any other text-based editor. The Nesstar Server provides the Access Control Policy Editor for the ACU. Further information will be provided later on.

The server provides some simple policies that can be loaded with a minimum amount of modification. To modify the policies and update the server ACU, you need to use the access control policy tools.

Nesstar provides the following tools for changing the security settings of the Nesstar Server:

  • A command-line tool for compiling and installing a custom policy file.
  • A graphical tool for editing, checking and validating the policy, as well as installing it on the Nesstar Server.

Command-Line Tool

The Command-Line Tool is named 'compile_ext.bat' and is in the bin directory of the Nesstar-Server. Simply typing 'compile_ext h' will show the options available when using this tool.
The most common option is “bin\compile_ext u”, which will parse and install the policy.acu file, and restart the Nesstar Server if any change is detected.

Graphical Tool

Start the Nesstar Access Control Policy Editor either from the Nesstar Configuration Tool (Access Control Policy Editor) or by executing 'security.bat' in the bin directory. This tool will allow you to edit, check and parse your policy file and update the server.

  1. Open the policy file from the 'File' menu.
  2. Edit and modify the policy file to your needs.
  3. Save it.
  4. From the menu 'Parser' check the validity of the modified policy by clicking on 'Check Validity'; any error in the policy will appear in the panel under the editor window.
  5. From the menu 'Parser' click on 'Parse'. This will not only test the policy, but also generate the code in the appropriate directory.
  6. From the menu 'Update' click on 'Update'. The server will be updated with the new policy.
  7. Close the Access Control Policy Editor
  8. Click on 'Apply Setting' on the main window of the config tool or restart the server using the Server menu option. **

** Please note that this is very important for the changes to be applied and server to behaveas per the new ACU policy.

If something goes wrong in the generation of the policy, the server will use a basic policy that gives access only to administrators or publishers.

Preloaded policies

Free Server

A simple modification available to the server is to remove any kind of protection. This situation can be obtained by loading the preloaded policy 1.
To do that using the command-line tool just type in the console the command “bin\compile_ext u1” will load the policy.
If using the Policy Editor, load the Preloaded Policy 1 in the editor from the Update menu.

The policy can be found in the file config\1_policy.acu.

A copy of the policy can be opened here.
The policy contains empty hierarchies and only one rule is defined:

   users can use objects

This is the most simple and basic policy that is possible to load in the server.

An empty policy file causes the server to use the basic policy granting access only to administrators.

Protecting Objects Metadata

Datasets in the server are a combination of metadata and data files.

Metadata refers to the description, on various levels, of the dataset. Data files are the actual statistical data used in the analysis process.

The default policy provides access control only on statistical operations. This allows users to be able to freely browse the metadata.

In the following example, we will see a policy that provides access control not just on the statistical content of your data, but also on their metadata.

This kind of policy can be loaded giving the commands:

  • “bin\compile_ext u2” from console
  • Preloaded Policy 2 from the Update menu using the Policy Editor.

The policy is defined in the file config\2_policy.acu.

A copy of the policy can be opened here.
This policy provides just a basic protection on metadata: it denies unauthorised users the browsing of full metadata description of the objects. In order to do that, it slightly modifies the default policy, using the action hierarchy reported below.

hierarchy use
    modify.
    access.

    analize extends access.
    browse extends access.
    search extends access.

    publish extends modify.

    retrieve extends browse.
    toRDF extends retrieve.
    see extends retrieve.
    basicObjRDF extends see.
   
    ...

end
The action “see” returns only the basic description for metadata. The action “browse” returns the full metadata description, plus some more basic operations on the server.

In order to restrict access to the full metadata description and allow only a reduced set of metadata to be accessible, the rule

/** every body can browse metadata */
users can browse objects.

becomes
/* users can only see objects */
users CAN see objects.
This rule achieves the undesired result of restricting basic operations that are defined on the server itself (for example, the login will be restricted). The policy needs to be further modified to allow users full access to the server; a new rule is added to the policy: 
users can browse common.Server.

Providing protection on catalog

Studies are organised in the Nesstar server using catalogues (in a similar way to how files are organised using folders).

A simple policy is provided to restrict particular catalogues and their contents from being accessed by unauthorised users.

This policy can be loaded with the following commands:

  • “bin\compile_ext u3” from console
  • Preloaded Policy 3 from the Update menu using the Policy Editor.

The policy is defined in the file config\3_policy.acu.

A copy of the policy can be opened here.

As before, in the object hierarchy the restricted category of objects is declared as follows:

hierarchy objects

    common.Server.
    common.Statement.
    faster.Catalog.
    faster.Study.

    restrictedObjects.

    catalog1 is faster.Catalog,restrictedObjects.

end
The “catalog1” declared in the hierarchy is the actual id of the catalogue that contains the objects we want to protect. In this example just one catalogue is defined, but you can declare as many catalogues as you need.

The hierarchy for the users is then modified to have a new category that has access to the restricted objects defined in the object hierarchy.

hierarchy users

    authorisedUser.

    specialUser are authorisedUser.

    fullauthorisedUser extends authorisedUser.

    publisher extends fullauthorisedUser,specialUser.
    administrator extends publisher.

    guestuser.

end


In the hierarchy above, the category “publisher” extends the new category. This is because users with publisher rights needs to have access to any object in the server.

The policy is completed adding a new simple rule:

users CAN use restrictedObjects ONLY IF user=specialUser.
This rule states that restricted objects can be accessed in any operation by, and only by, users that are declared as special users. The use of the declaration ONLY IF guarantees that the rules are always fired and not overridden by other more permissive ones. For a better explanation of this, please refer to the appendix.

Using this policy, it is possible to hide catalogues from users. When users try to access a list containing the restricted catalogue, a challenge will be issued. If users can access the catalog, this will appear in the list, if not, only the accessible catalogue(s) will be in the list.
If the catalogue is listed at the root level (top level of the tree view), a challenge will be issued as soon as server is accessed.
If the catalogue is listed as a child of an unrestricted catalogue, the users will receive a challenge as soon as they try to access this catalogue. In this way, the users are free to browse the normal catalogues as in the default policy.

Some simple examples

Protecting Objects' Properties

We said that objects are composed of metadata and data. Metadata can be protected at different levels. We already provided a policy to protect metadata as a whole. The following text provides an example of a policy that provides protection on metadata at a more detailed level.

To provide this protection, you need to declare the properties you are going to protect.
In the following example we will provide different levels of protection to the following objects' properties:

  • Study.AbstractText
  • Study.CollectionEnd
  • Study.CollectionStart
  • Study.AccessPlace
  • Study.Universe
  • Study.Variables
  • Variable.QuestionText

When dealing with collections (such as variables in the example above) unauthorised users will be shown an empty collection.

These properties will be declared in the object hierarchy using a special declaration:

hierarchy objects

    common.Server.
    faster.Cube.
    faster.Catalog.

    faster.Study.
    faster.Variable.
    common.Statement.

 property restrictedProperty.
    property fullrestrictedProperty.

    property AbstractText extends restrictedProperty.
    property AccessPlace extends restrictedProperty.
    property Universe extends restrictedProperty.
    property Variables extends restrictedProperty.

    property QuestionText extends fullrestrictedProperty.
    property CollectionEnd extends fullrestrictedProperty.
    property CollectionStart extends fullrestrictedProperty.

end
Two levels of protection are defined: restricted properties (restrictedProperty) and full restricted properties (fullrestrictedProperty).

As the metadata could be accessed also by retrieving the DDI description of the objects using the provided methods (GetDDISkeleton GetDDI GetDDIVariable FindDDIVariables), these methods should be protected as well. The same is valid for the method GetWeightVariables as the policy should protect all the variables belonging to a given study.
So the action hierarchy is modified as follows:

hierarchy use
    modify.
    access.

    ...

 browseMetadata extends access.
    GetDDISkeleton extends browseMetadata.
    GetDDI extends browseMetadata.
    GetDDIVariable extends browseMetadata.
    FindDDIVariables extends browseMetadata.

    GetWeightVariables extends browseMetadata.

    ...
end

Using the default users' categories, the rules that state type of access to the properties are:

   users CAN use objects/restrictedProperty ONLY IF user=authorisedUser.
    users CAN use objects/fullrestrictedProperty ONLY IF user=fullauthorisedUser.

With this policy, users , even if not authorised, can browse the basic structure of the objects in the server. They will be challenged as soon as they try to access metadata or the variable level.

The policy can be found here.

Proposing agreements to users

As described above, one of the actions available to the users when challenged by the server is to accept an agreement.

To use agreements in the policy, they should be declared before the rules section that uses them. Agreements declared in the policy are created from the system in the database.

Agreements can be created using the the following declaration:

   agreement( agreement_id , agreement_text).

for example: 
   agreement( “agreement1”,“I accept to respect all the limitations set on these data by the publisher.”).

To use the agreements in the rules, a method exists for user HasAgreement(agreement_id,scope).
agreement_id is the id used in the agreement declaration, scope is the validity of the agreement and three values are available for it:

  • TRANSACTION: the agreement will be valid for the current transaction only; users will be asked to accept the agreement with every new transaction;
  • SESSION: the agreement will be valid for the current session only; users will be asked to accept the agreement with every new session;
  • ONCE: the agreement will be valid for all sessions; users will be asked to accept the agreement once and for all;

For example the rule

   authorisedUser CAN analize faster.Study IF user/HasAgreement("agreement1",SESSION).
is translated as : all the authorised users can perform analysis on a study if users have accepted agreement agreement1 for the current session.

A policy using agreements can be found here.

 

Copyright © 2012 Norwegian Social Science Data Services