Using Security Templates

This page describes the standard security templates that come with Instant JChem. Most of the time one of these templates can be used with little or no customisation. We recommend that you define your security configuration before you invest too much time on loading data into the database.

About Roles

Instant JChem defines 6 roles that control which operations the user can perform. A user can have any of these 6 roles. At least one role must be defined for the user to be active.

ROLE_ADMIN: Can configure security settings and manage users.

ROLE_EDIT_SCHEMA: This role is required for all Instant JChem operations that create or delete database tables and columns. This means that without this role you will not be able to add new Instant JChem Entities or Fields , nor be allowed to import data in a way that requires new Entities or Fields to be created.

ROLE_EDIT_DATA: With this role you can edit data in existing tables, add new rows or delete existing rows. You cannot add new fields or tables.

ROLE_USER: You can view all data but cannot make any changes.

ROLE_EXPORT_DATA: A new role introduced in 15.10.5.0 release to improve the IJC data security model. With this role you can use data export functionalities, cut, copy, copy to MS Office and printing. The less obvious functions controlled by this role involve several list management functions, specifically Edit List, Export list to a file and copy/cut list. The integration with JC4XCL and Spotfire is also controlled by this role. Users without this role can’t export data from IJC.

ROLE_EDIT_SCRIPT: A new role introduced in 15.10.5.0 release to improve the security model. This role is required to be able to create and edit groovy scripts. Users without this role can’t create or edit scripts in IJC.

ROLE_EXPORT_STRUCTURE_AS_IMAGE_ONLY: A new role introduced in 16.3.7.0. This role works as a supplemental restriction for ROLE_EXPORT_DATA. Any user that is assigned role ROLE_EXPORT_STRUCTURE_AS_IMAGE_ONLY will be unable to export molecules in any structural format (.sdf, .mrv, etc.) and will be limited to exporting image only. This effectively means that the only allowed export with structure as image is .xlsx. The user with this restriction will also be able to export textual formats (.csv, .tab), but in this case, the structure field will not be available in the export. The role also disables copy/pasting of the structure field, because the copy/paste action operates with structural data.

Single User Mode

As adding or, particularly, deleting tables or columns (ROLE_EDIT_SCHEMA) would have bad consequences on all other concurrent users, these changes must be made when the Schema is in single user mode. This ensures that you are the only current user of the database. When you are finished making changes you should disconnect so that other users can connect.

When you log in to a remote database with ROLE_EDIT_SCHEMA role, AND are the only current IJC user of the database then you will be asked whether you want to connect in single user mode (for a local database this step is skipped and you are always connected in single user mode so that you always have full access to local databases). Only connect in single user mode if you need to make changes to the database tables and columns as you will be preventing other users from using the database whilst you are logged in. Once they can log in they will see any changes that you have made.

Anonymous Authentication

Description

For use with local databases or single user remote databases. Whilst this security model is operating you are automatically logged in with full access rights (all 4 roles are defined) and you would not notice that any security was in place unless you read this!

Configuration

This is the default security model if none other is defined. Typically, no configuration is needed for this security mode, but a template is provided in case there is a need to customise.

Username/Password File

Description

For use where you need a very simple way to provide access control and security is not a high concern. Usernames and passwords are stored in plain text within the security configuration file which is stored inside the particular Instant JChem database.

Configuration

Typically the only configuration that is needed for this security mode is to edit the usernames, passwords and roles for your users. These are found in the configuration file. A typical entry looks like this:

<sec:user name="admin" password="admin" authorities="ROLE_USER,ROLE_EDIT_DATA,ROLE_EDIT_SCHEMA,ROLE_ADMIN,ROLE_EXPORT_DATA,ROLE_EDIT_SCRIPT" />

The attribute ‘name’ is the username and the attribute ‘password’ is the user’s password in clear text. The attribute ‘authorities’ contains a comma separated list of IJC roles that this user gets assigned.

At least one role must be defined for the user to be active.

Authentication within the Instant JChem database

Description

Usernames and passwords are stored in special Instant JChem database tables. Passwords are encoded, and a mechanism for managing users and passwords is provided. This is the recommended solution where security is a concern.

Configuration

This is slightly more complex to configure, but usually only takes a few minutes. The configuration provides the ability to define usernames, passwords and roles within database tables of a particular IJC database. Initially these database tables are not present, so you would not be able to log in until you had created one account which had at least ROLE_ADMIN and ROLE_EDIT_SCHEMA roles. To get around this problem the template also includes a special user with the username and password both set to "admin". This allows you to specify this configuration, log off and then log back in with this "admin" account so that you can edit your users. Once you have added at least one user with ROLE_ADMIN and ROLE_EDIT_SCHEMA roles you should then confirm that you can connect as this user and then delete the part of the configuration that defines this special user so as to remove this potential security hole.

Step 1: Select the template and apply it. The template will work as is, but there is some configuration that can be done if you wish to change things like the way passwords are encoded.

Step 2: Log off and log back in as user "admin".

Step 3: Re-open the security configuration editor and go to the User Management tab. Add the users you need. It is important that you define at least one user who has both ROLE_ADMIN and ROLE_EDIT_SCHEMA roles. You can add additional users at a later stage.

Step 4: Log off and log back in as the user who has ROLE_ADMIN and ROLE_EDIT_SCHEMA roles that you created in the previous step. Confirm that you can log in and edit the database. If not then log back in as "admin" and edit that user. Repeat until you confirm that this user can configure the security configuration.

Step 5: Once you are sure that you have defined a user that has the ability to configure the security settings, you can then remove the special "admin" user. Do this by searching for

<!-- temporary authentication provider -->

and then remove line bellow the comment which should look like this:

<sec:user name="admin" password="password" authorities="ROLE_USER,ROLE_EDIT_DATA,ROLE_EDIT_SCHEMA,ROLE_ADMIN,ROLE_EXPORT_DATA,ROLE_EDIT_SCRIPT" />

This is found within the bean with the <sec:authentication-manager … /> section. . Remove the line above and update configuration. Then log off and log back in. The "admin" credentials will no longer be working.

At least one role must be defined for the user to be active.

Database authentication

Description

Since IJC 5.4 for Oracle and MySQL databases you can use database authentication for IJC. Using database-based authentication differs from the other mechanisms described here in that each user has their own database username and password. This is used in the first step, and then the same username is used automatically by IJC and there is no second stage of authentication.

Configuration

Each user needs to have their own database username and password, and appropriate privileges need to be set up for each user. To use this in IJC you need to use the 'Username/password using database accounts' template, but other steps need to have already been completed, and process is fairly complex and needs the involvement of your DBA. A guide for setting this up can be found here. Please consult that guide before trying to use this mechanism.

Authentication using an external server and LDAP

Description

Lightweight Directory Access Protocol is a protocol for accessing information across a network. It is commonly used to retrieve user information from a central location in an organisation. There are specific implementations of LDAP, such as the Open Source OpenLDAP software, and several vendors provide LDAP access to their directory information (e.g. Microsoft's Active Directory and Oracle's Oracle Internet Directory).

IJC usernames and passwords are located in this external server and accessed through LDAP. This is most appropriate for large organisations who already have a large number of users configured into their systems, and do not want to duplicate information inside the IJC database. It can also provide a common mechanism to control access across multiple IJC databases. Role information can also optionally be retrieved using LDAP.

Configuration

This is the most complex to configure as the content of the external LDAP server depends on your particular installation, and so IJC needs to be configured to read the appropriate values from it. IJC comes with a sample configuration that can be used as a starting point, and this includes various options and comments that illustrate how to configure it against your particular LDAP server. Before using LDAP based security it is essential that you have a good understanding of LDAP and of Spring Security .

The configuration options are too varied to be able to describe in full here. The LDAP security template contains further information about how to configure LDAP security. Please consult this, as well as the following sources of information from the Acegi security web site:

If you need more information or assistance we suggest that you ask on the Instant JChem forum .

The following things (and much more) are possible to configure for LDAP authentication and authorisation:

Authentication

In the provided template the user authenticates against the LDAP server using the username and password they provide. The Distinguished Name (DN) that is used for this authentication can be generated by:

  1. Substituting the provided username into one or more templates for the DN. One of these DNs must exist in the directory for the user to be able to authenticate.

  2. Performing a search of the directory using a configurable search that includes the username that the user specified.

Once the DN is found by one of these mechanisms the user is authenticated against the server using the supplied password.

Authorisation (allocation of roles)

Once the user is authenticated they must be assigned appropriate roles to be able to use IJC. These are one or more of ROLE_USER, ROLE_EDIT_DATA, ROLE_EDIT_SCHEMA, ROLE_ADMIN , ROLE_EXPORT_DATA and ROLE_EDIT_SCRIPT . The template provides two alternative approaches to doing this:

  1. All authenticated users are given a fixed set of predefined roles. This is most useful if you do not want to manage the role information in the LDAP server and want all your users to access the IJC database with the same access level (e.g. ROLE_USER). Note that you can also specify additional user accounts that are not provided via LDAP to add special users who have administrator or power user needs.

  2. Role information is retrieved from the LDAP server. The users must be assigned to a group in the LDAP server and membership of that group is used to assign the user to a particular role. This is the most flexible option, but probably needs this group information being added to the LDAP server. Again, all authenticated users can be assigned default groups (so that only users needing additional roles need to be configured into groups) and special additional users can be created with extra access rights without the need to add them to the LDAP server.

Authentication using an external Active Directory server

Description

Active Directory is Microsoft's way of doing LDAP. Your users login details are stored in the Active Directory and can be accessed using LDAP. This allows you to use the same login details that you use to login to Windows for your IJC login.

Configuration is very similar to the LDAP example, but you should start from the Active Directory template instead of the LDAP one. This Active Directory template is preconfigured for a "typical" Active Directory setup and you should just need to configure things like the URL of your Active Directory server. See the LDAP section for more details.

One the hardest things to work out with Active Directory is what is the syntax of the distinguished names of your users. A useful trick here is to use the dsquery command line tool that dumps out the DN's of your directory. Use it like this:

dsquery user

Alternatively, you can use tools like cvsde which ia windows commandline applications which outputs CSV list of all users matching certain filter with full DN names and groups:

cvsde -f output.csv -m -d “cn=users,dc=example,dc=com”

Additionally, starting Microsoft Windows Server 2012, Get-ADDomain, Get-ADGroup and Get-ADUser which can be installed from PowerShell Get-Module, output contains very useful information about directory structure which is needed for the security policy settings.

Mapping LDAP or Active Directory groups to IJC roles

The LDAP and Active directory support benefits from flexible LDAP group to IJC role mapping using two extended AuthoritiesPopulator which are explained below.

Trimming LDAP group names to IJC roles

The TrimerLdapAuthoritiesPopulator which provides the flexibility to make some trimming changes on LDAP group names after before using them for IJC access control in order to make the group names represent the IJC roles.

An example use case for these template is as follow:

Assume that LDAP groups specified for IJC users has a prefix like science_ before the standard IJC role names and you cannot change the role names in LDAP storage, what you can do is using this template to trim the group name before using it for access control from the prefix to make it represent the IJC role assigned to it.

Example of using this AuthoritiesPopulator are included in both ldap security template, accessible in the schema security configuration panel, and in the active directory security template accessible in the same panel as mentioned earlier.

Mapping between LDAP group names to IJC roles

The next AuthoritiesPopulator is the MappingLdapAuthoritiesPopulator which is the most flexible AuthoritiesPopulator provided with IJC for ldap and active directory support. This AuthoritiesPopulator provides the possibility of mapping a LDAP group to one or more IJC roles. The mapping support nested groups as well as flat group membership.

When using this AuthoritiesPopulator 3 more LDAP attributes are required to be specifies which are as follow:

  1. The memberOfAttributeName is the virtual attribute name containing the group membership. It is isMemberOf for OpenDS and memberof for Activedirectory

  2. The useridAttributeName is the attribute containing the userid like uid or sn. It is usually uid for LDAPs

  3. The baseDN attribute refers to the LDAP base dn like dc=ijc,dc=org

  4. The syntax for specifying the mapping for each group is as follows:

<entry key="cn=nested_group_2,cn=parent">
<list>
<value>ROLE_EDIT_SCHEMA</value>
<value>ROLE_EDIT_DATA</value>
<value>ROLE_ADMIN</value>
</list>
</entry>

Authentication using Oracle IAM and authorisation using Oracle procedure

This is custom security implementation that was done for a particular customer. It using Oracle IAM for the authentication using Kerberos (falling back to NTLM if Kerberos is not present), and then uses an Oracle stored procedure in the IJC database to perform authorisation.

This implementation is probably too specific to that particular customers environment to be generally useful, but we include it as an example of how a custom policy can be used if you have a proprietary setup that is not supported out of the box. Please contact ChemAxon if you are interest in having a custom implementation written as a consultancy project.