Advanced Customisation

Using an External User Database

• Configuring the Server to Use the External Database
• Configuring the Login Module
• Modifying the UserBean java class

Stating the Access Control Type of Objects

Defining Custom Access Control Checks

Adding Support for the Athens Login

Adding Support for the LDAP Login

 

Using an External User Database

The Nesstar Server stores data about its users in a user database, which by default is part of the Nesstar database.

Nesstar provides a simple interface, the User Management Tool, to modify the content of the user database. This can be opened from the Nesstar Server Configuration Tool. (From the Customisation menu, select Security -> User Management Tool. This tool is also available directly from a running Nesstar Server, at the url http://<your server url here>/admin. Please note this tool works best in Internet Explorer web browsers. It is only available to users with Administrator privileges.)

Alternatively you can use an external database. The steps involved in using an external user database depend on the existing configuration of the Nesstar Server, and the required functionality of the ACU. To simply instruct the Nesstar Server to look for its user database in a different location to its own default database, you must configure it to do so in the Nesstar Server Configuration Tool. If the new database has a different structure to Nesstar's own database, this must be reflected in the login-conf.xml file, and/or the UserBean java class.

If you need to use an external security database and it is already set up in the Nesstar Server Configuration Tool, you need to set the Nesstar Access Control Policy Editor to use the external database. On the Database menu, you will need to set the user and project table names. You can now use the 'Test Connection' to check the database connection. If the connections fail, first check the user and project table names again, then check your configuration in the Nesstar Server Configuration Tool.

Configuring the Server to Use the External Database

From the Nesstar Server Configuration Tool (advanced mode)

1. Select the security database type from the 'Security database' property.
2. Set the name of the external database in the property 'jdbc security database'.
3. Set the username and password for the external database in the 'jdbc security user' and 'jdbc security password' properties.
4. Set the security database URL appropriately.

Configuring the Login Module

The Login Module configuration file (login-conf.xml) is located in the \jboss\server\default\conf directory of the Nesstar Server root directory. It defines the type of login and user database we are using, as well as the SQL queries used to extract the relevant information from the user database.

The section to be modified is called "other" (under the tag <application-policy name="other">). You need to modify the principalsQuery and the rolesQuery sections.

The first query takes the user name as an argument and returns the password of that user, unencrypted. It needs to take the following structure:

<module-option name="principalsQuery">SELECT password FROM userEJB where ID=?</module-option>

The second query also takes the user name as an argument and returns roles (the types of the user) and roleGroups of that user.

<module-option name="rolesQuery">SELECT roleID, rolegroup FROM userRole WHERE id=?</module-option>

For obscure technical reasons roleGroup must always return NULL.

Modifying the UserBean java class

The configuration described up to here allows for very simple use of the external database, extracting the basic information relating to a user (password and possibly roles/purpose).

More complex policies require more information to be available. Unfortunately the Nesstar Server is not able to retrieve this information from the standard database automatically, so we need to implement additional functionality to meet this requirement. The reasons for this lie in the fact that the Nesstar Server will need to create the User object from which additional information can be extracted, such as the users project ownership. More simple policies, which do not require checking of properties such as the users project ownership, do not require a User object to be created. To enable this behaviour, a number of empty method bodies will need to be filled in the UserBean java class.

The UserBean.java file is located in the \config\ext\example\nesstar\ejbean\acu directory of the root Nesstar Server directory.

The following methods will need to be implemented:

• getExternalPassword() : return the user's password as set in the external database, if necessary; value returned can be null;
• getExternalComment() : return any comment associated to the user; value returned can be null;
• getExternalLabel() : return the user's label; value returned can be null;
• getExternalProjects() : return a Collection of String describing the titles or the id of the projects associated to the user, if any;
• getExternalPurposes() : return a Collection of String describing the id of the purposes associated to the user, if any; ids must be the same as described in the policy.acu file in the purposes hierarchy.

This file will need to be copied to the \config\ext\nesstarbeans\nesstar\ejbean\acu directory. One drawback of this solution is that user and project details copied from the external database into the internal database will not be kept in sync.

Stating the Access Control Type of Objects

The default policy does offer a flat representation for the objects' type: all the objects are handled in the same way.
For a more complex policy and to provide a more detailed access control, it always possible to organise the objects in a structure and give them different levels of access. Each level could have a set of rules that applies to it and to any level that "inherits" from it. The root level is "objects" and rules defined for this level will be applied to all the sub-levels present in the hierarchy. An example of a policy that uses different categories could be found here
Here is an example of it:

hierarchy objects

    common.Server.
    common.Statement.
    faster.Catalog.
    faster.Cube.
    faster.Study.
    faster.Variable.

    freeobjects.
    restrictedobjects.

    freestudy extends faster.Study,freeobjects.
    restrictedstudy extends faster.Study, restrictedobjects.

    freevariable extends faster.Variable,freeobjects.
    restrictedvariable extends faster.Variable, restrictedobjects.

    "com.nesstar.ddi.MergeTest" is freestudy.

    "uk.ac.data-archive.ddi.2568" is restrictedstudy.

    "com.nesstar.ddi.MergeTest_V10" is restrictedvariable.
    "uk.ac.data-archive.ddi.2568_V10" is freevariable.

end

The structure defined above is very simple as it defines just two categories for the objects and then two further categories for studies and variables.
The last declarations define instances of study and variable under the given categories.

In the server, the object hierarchy is rendered as a catalogue tree: objects are contained in the catalogue(s) that define their category. When the server loads the policy, categories are created as catalogues, and, if instances of objects are declared in the object hierarchies, they are added to the appropriate catalogue. As multiple inheritance is permitted, instances or categories could extend more than one parent category.

The ACU catalogue tree is similar to the main catalogue tree which organises the objects in the server, but it is not visible through a normal client. Access is possible using the Object Browser: the root catalogue is accessible through the server's property acuCatalog. As the main catalogue tree the structure can be modified by using the methods in the Object Browser or loading the structure through an RDF file.

Modifying the structure and defining categories for the instances is possible by:

1. writing the structure in the policy files and loading it onto the server. The main structure should be created and modified only in this way as it is the structure on which the rules are dependent.If the structure changes and becomes inconsistent with the rules, the Access Control Unit cannot work or cannot work in the desired way.
2. writing the structure in an RDF file and then importing it into the server. As above, the main structure in the file should reflect the structure defined in the policy file so as not to create inconsistencies with the rules. This solution could be a good one for very static structures that are unlikely to change frequently.
3. using the object browser to create, add and organise catalogues and objects using the methods provided.

Defining Custom Access Control Checks

Even if the Access Control Unit provides a very high level for customisation, it is still possible to add a greater degree of checks, defining custom checks and using them instead of, or with, the checks already defined in the default access control unit.

The definition of new checks is the most flexible way of customising the ACU. This method can be used when more controls on the process of authentication and authorization of the user are needed, for example when the Nesstar Server has to be integrated into an existing context with its own access control.

Defining new checks mostly involves the creation of new code in the server, so the procedure to create and use them in the policy file is more complex.

Creating the code

Code can be created for each object in the server any time this is needed for altering or improving the behaviour of the object being modified. For the Access Control Unit to work, the check should be created as a method that satisfies the following requirements:

• it returns a boolean value
• it is declared public in both the JBoss local interface and main bean

As the Nesstar Server is based on a JBoss container, the code should reflect the structure used by JBoss for being used. For further information on this subject, we recommend you read the JBoss documentation. For ACU purposes, we just need to know that for each object two classes are needed. If, for example, the object being modified is Study, the two are:

1. interface StudyLocal.java: it contains the declaration of the method.
2. class StudyBean.java: it contains the implementation of the method.

Once the code has been created and copied into the appropriate directory in config/ext/nesstarbeans/, it can be compiled using the same tools used for loading the policy:

1. from console “bin\compile_ext uf”
2. using the Policy Editor from the Update menu the command “Update”(a warning will appear indicating that the policy has not been parsed; just continue)

Do not use the new method in the policy yet, as the system will not recognise it.

Defining the policy

Once the method has been created, it can be used in the policy. If, for example, the method called isAccessible() has been defined on the object Study, the call to the method will be faster.Study/isAccessible().
A rule created with the new method could be: users CAN access faster.Study IF faster.Study/isAccessible().

The new method will be subject, as any other method, to the Access Control checks, so a rule to handle it must be created in the policy. The simplest way is to define a simple rule that gives full access to the method for any user .
Add the method name in the use hierarchy and then write the rule users CAN your-method objects..

Once the policy has been modified with the new method, it is possible to load it onto the server, using the tools provided and already described previously.

An Example

Suppose a special policy is needed to read the access rights of a user from an external source that can not be accessed directly by the default Nesstar System. In order to state if a user can or cannot access a resource we need to authenticate the source and pass the result to the Nesstar Access Control Unit.

The first step in the process is to create the files containing the code performing the check; we will create a method called hasPermission(). The check will be implemented in the class that defines the user. So the code will be created in the two classes:

• config\ext\nesstar\ejbean\acu\UserLocal.java

     package nesstar.ejbean.acu;
  
      /**
       * the interface for the User Bean created for custom extension
       */
  
      public interface UserLocal extends UserMainLocal {
  
          public boolean hasPermission();
  
      }
     

• config\ext\nesstar\ejbean\acu\UserBean.java

     package nesstar.ejbean.acu;
  
      import nesstar.ejbean.security.EJBSession;
      import nesstar.ejbean.security.EJBOp;
  
      /**
       * the bean for the User Bean created for custom extension
       */
  
      public abstract class UserBean extends UserMainBean{
  
          public boolean hasPermission(){
              EJBOp op = EJBOp.getCurrentAction();
              EJBSession session = EJBOp.getCurrentSession();
              NEOOMLocal object = EJBOp.getCurrentObject();
              String user = session.getUser();
              //check user, action and object using the custom code
              return result;
          }
      }
     

  The class EJBOp is a very useful one as we can retrieve any information about the status of the current transaction from this class. More from the Nesstar API documentation.

Once the classes are created they can be compiled. Using the console, give the command bin\compile_ext u. If no errors have been made, the new code will be integrated in the server and be ready for use.

Now the policy can be modified to use the new method. Starting with the default policy, two new rules are added:

   authorisedUser CAN access faster.Study only if user/hasPermission() or user=publisher.

    fullauthorisedUser can download objects only if user/hasPermission() or user=publisher.

The policy can be found here. The two new rules state that the authorised users can access objects if and only if they have permission or if they are publisher and that full authorised users can download objects if and only if they have permission or if they are publisher. The condition “they are publisher” has been added to allow the administrator to perform all kinds of operations.

Now the policy can be loaded into the server and tested. Again using the console, give the command bin\compile_ext u. If no errors have been made, the new policy will be loaded onto the server.

Adding Support for the Athens Login

The Nesstar Server provides functionality for supporting the Athens login system. Presently, the server does not support the single point of login functionality, so users will need to login to the Nesstar Server, even if previously logged in to Athens using another service.

Login in JBoss is handled by a LoginModule that is in charge of retrieving the users information and authenticating them, before sending them to the security system. In the default configuration, the module used is org.jboss.security.auth.spi.DatabaseServerLoginModule and it retrieves the user information from a database. For more information, please see the JBoss documentation.

To use authentication with the Athens system, the LoginModule has to be replaced with nesstar.ejbean.security.login.NewAthensServerLoginModule. This module will authenticate a user on the Athens system. For special purpose-based users, as admin, deployer and nobody, the authentication will be performed on the default database. Athens does not store such specific user information. The configuration for the Login Module to be used is set in the section "other" in the file jboss/server/default/conf/login-config.xml. It should be modified as below:

<application-policy name="other">
    <authentication>

    <login-module code="nesstar.ejbean.security.login.NewAthensServerLoginModule" flag="required">
        <module-option name="dsJndiName">java:/securityDS</module-option>
        <module-option name="principalsQuery">select password from userejb where id=?</module-option>
        <module-option name="rolesQuery">SELECT roleid, rolegroup FROM userrole WHERE id=?</module-option>

        <module-option name="unauthenticatedIdentity">nobody</module-option>

     <module-option name="password-stacking">useFirstPass</module-option>
        <module-option name = "DSPId">your_dspid_here</module-option>

        <module-option name = "resources">your_resources_here</module-option>

        </login-module>
    </authentication>
</application-policy>

The first part of the configuration module option is the same as in the default Database Login Module and it provides the information for the login module to authenticate the users against the Nesstar security database. This option is present because special users such as administrators cannot be defined in Athens. The meaning of the remaining option is:

• <module-option name="password-stacking">useFirstPass</module-option> : this parameter allows reuse of user information stored in the login context after the first login in the session. As the connection to Athens server can be very slow, this will allow a reduction of the number of connections.
• <module-option name="DSPId">your_dspid_here</module-option> : the DSP id of the service as provided by Athens.
• <module-option name="resources">your_resources_here</module-option> : the list of comma-spaced resources registered on Athens for the service.

The Nesstar Server expects to find the configuration file in jboss\server\default\conf\athens_agent_conf.txt.

The security policy set for use with the Athens authentication server is very simple as it delegates access control to the Athens server.
Users will be authenticated and given/denied access on the basis of the Athens answer to the authentication call from the server.
Users authenticated by Athens will be given the role of full authorised users, allowing them to perform analysis as well as downloading data.

Adding Support for the LDAP Login

The Nesstar Server provides functionality for supporting the Ldap login system. The system uses a modified JBoss login module, nesstar.ejbean.security.login.LdapLoginModule.

The "other" section in the file jboss/server/default/conf/login-config.xml has to be modified as follows:

<application-policy name="other">
    <authentication>
    <login-module code="nesstar.ejbean.security.login.NesstarLdapLoginModule" flag="required">

     <module-option name="java.naming.provider.url">your_ldap_server</module-option>
        <module-option name="rolesCtxDN">your_roles_context</module-option>
        <module-option name="principalDNPrefix">prefix</module-option>
        <module-option name="principalDNSuffix">suffix</module-option>

        <module-option name="matchOnUserDN">true</module-option>
        <module-option name="roleAttributeIsDN">false</module-option>

         <module-option name = "defaultRole">DEFAULT_ROLE</module-option>

        <module-option name="dsJndiName">java:/securityDS</module-option>
        <module-option name="principalsQuery">select password from userejb where id=?</module-option>
        <module-option name="rolesQuery">SELECT roleid, rolegroup FROM userrole WHERE id=?</module-option>
        <module-option name="unauthenticatedIdentity">nobody</module-option>

    </login-module>
    </authentication>
</application-policy>

The first part of the module configuration option is the same as the default Ldap JBoss Login Module. For more about this, we recommend you consult the JBoss documentation.
The second part of the configuration is Nesstar specific and is basically the same as the default Database Login Module. The defaultRole option states the role assigned to users when no roles are defined in the Ldap server.

When the user is authenticated, the following cases can occurs:

1. Users are registered as Nesstar users in the Nesstar database: they are authenticated against the Nesstar Database. Users' roles are the ones assigned to them in the database.
2. Users are registered as Ldap users: they are authenticated against the Ldap database; a basic user will be created in the Nesstar Database with no details. Users' roles are:
   • the default role as defined in the configuration option if the Ldap server does not return roles for the users.
   • any roles defined for the user in the Ldap server and returned to the login module; there roles should be defined in the policy file with the appropriate rules.

The policy used with the Ldap authentication can be the default one or be modified according to the needs of the specific server. If the Ldap server has roles defined for the users, those roles should be defined in the policy as well and given appropriate rights. If no roles are defined in the Ldap server for the rules, they will be assigned by default the role defined as default role in the configuration.