Installation‎ > ‎

Configure Application Security

OpenI uses role based security provided by J2EE web container. Since each J2EE web container security configuration is not identical, we are covering JBoss 4.2.2 and Tomcat 6.0.x here since those were our test platforms. Application Security can be achived through various configuration such as via properties file, UserDatabase, Datasource etc. Please refer to the respective J2EE server documentation for the details about security configuration for any other J2EE server.

Define Roles

Every user must have a role "openi" to access the OpenI web application. This role is essentially to separate users who have access to OpenI application (in cases where you have multiple applications deployed on your J2EE server, and want to separate access to OpenI from the rest). The other roles are as follows:
  • app_admin :This is application administrator role that provides full administrative privileges for the entire OpenI application, i.e. app_admin users can modify any content and any configuration for any project within OpenI
  • <project_id>_admin : This is project administrator role that grants a user full administrative privileges for a project whose id is "<project_id>". For example, for the sample project "foodmart", "foodmart_admin" will be the name of the role providing project administrator privileges.
  • <project_id>_user : This is a project user role that grants a user user-level privileges to a project access privileges to a project whose id is "<project_id>". For example, for the sample project "foodmart", "foodmart_user" will be the name of the role providing project user privileges. A project user (a) doesn't have access to any of the options under "Preferences" except for managing their user profile, and (b) can't modify any of the existing analyses, but can create/modify new analyses of their own.
There are 3 built-in role definitions in the OpenI web application. Here is a table summarizing their authorization rules:

 User Type Roles Required
Project visibility 
 Application Administrator  openi, app_admin  all projects in subdomain
 Project Administrator (for project "<project_id>")  openi, <project_id>_admin  for particular project "<project_id>" only. must be declared for each project requiring admin user access
 Project User (for project "<project_id>")  openi,<project_id>_user  for particular project "<project_id>" only. must be declared for each project requiring user access

Security Configuration for Tomcat

For tomcat Security Configuration can be done via various realms such as DataSource, JDBC, JNDI, Memory, JAAS and UserDatabase realm

Configure UserDatabase Realm

If you have a Tomcat deployment using the default security database, here's how you can configure security to create an application administrator login admin/password, a project administrator login for the foodmart project foodmartadmin/password, and a project user login for the foodmart project foodmartuser/password
  • Find <tomcat-home>/conf/tomcat-users.xml
  • Configure roles and users as follows:
    <tomcat-users>
    <role rolename="openi"/>
    <role rolename="app_admin"/>
    <role rolename="foodmart_user"/><role rolename="foodmart_admin"/>
    <user username="admin" password="password" roles="openi,app_admin"/>
    <user username="foodmartadmin" password="password" roles="openi,foodmart_admin"/>
    <user username="foodmartuser" password="password" roles="openi,foodmart_user"/>
    </tomcat-users>

    Note: all user must have "openi" role. All non-app-admin user must have either "<project_id>_user" or "<project_id>_admin" role. For example, foodmart project admin role is "foodmart_admin" and foodmart project user role is "foodmart_user".

  • Find <tomcat-home>/conf/server.xml
  • Ensure you have the following definition entry for the security realm:
    <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
    debug="0" resourceName="UserDatabase"/>
  • OpenI also has a feature to manage user/roles, if roles/users are configured in a jdbc database accessible to the J2EE web container. For details, see JBoss Security Configuration with JDBC User Database for reference.

Configure DataSource Realm

On configuring tomcat with DataSource Realm, it looks up users in a relational database accessed via a JNDI named JDBC DataSource. The refered database must conformed to following structure:.

  • There must be a table, named users table, that contains one row for every valid user that this Realm should recognize.
  • The users table must contain at least two columns (it may contain more if your existing applications required it):
    • Username to be recognized by Tomcat when the user logs in.
    • Password to be recognized by Tomcat when the user logs in.
  • There must be a table, named the user roles table, that contains one row for every valid role that is assigned to a particular user. It is legal for a user to have zero, one, or more than one valid role.
  • The user roles table must contain at least two columns (it may contain more if your existing applications required it):
    •  Username to be recognized by Tomcat (same value as is specified in the users table).
    • Role name of a valid role associated with this user.
Steps for DataSource Realm configuration:
  1. Create a database on relational database, with two tables named users and user_roles.
  2. In case of MySQL run following queries:
    CREATE TABLE users {
    user_name varchar(50) NOT NULL,
    full_name varchar(50),
    passwd varchar(50) NOT NULL,
    language varchar(50),
    mail varchar(50)
    }
    CREATE TABLE user_roles {
    user_name varchar(50) NOT NULL,
    role_name varchar(50) NOT NULL
    }

  3. Configure JNDI named JDBC datasource. For configuration add following <context> in <tomcat-home>/conf/context.xml:
    <Resource name="jdbc/OpenILoginDs" auth="Container" type="javax.sql.DataSource"
    maxActive="100" maxIdle="30" maxWait="10000"
    username="root" password="" driverClassName="com.mysql.jdbc.Driver"
    url="jdbc:mysql://localhost/openiusers" />
    where jdbc/OpenILoginDs is the name of JNDI named JDBCdatasource

  4. Setup realm element in conf/server.xml file as follows:
    <Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99"
    localDataSource="true" dataSourceName="jdbc/OpenILoginDs"
    userTable="users" userNameCol="user_name" userCredCol="passwd"
    userRoleTable="user_roles" roleNameCol="role_name"/>
        Note: The contents of this context file will be loaded for each web application.
        You can specify the application specific context in separate context files.
        Also you can explicity define Context element inside a Host element in the main conf/server.xml
        ( For Tomcat 6, unlike Tomcat 4.x, it is NOT recommended to place <Context> elements directly in the server.xml file )

Security Configuration for JBoss

Similar to tomcat Application Security for JBoss can be achived via varius means.

JBoss Security with propertises file

For default security configuration in JBoss using text files to define users and roles, add following files under [JBOSS_HOME]/server/default/conf:
  • users.properties : contains user entries as user_name=user_password
  • roles.properties : contains role entries as user_name=role_1,role_2,role_n (OpenI requires roles "openi" and "app_admin" for admin user)

JBoss Security with JDBC User Database

JBoss authentication can be customised using JDBC database (i.e. user logins and role definitions stored in relational database tables). One key advantage of this approach is that with this, you can leverage OpenI's "Manage Users" feature that can do basic user profile and password management.

Steps:
  • Database Setup
    Download and install your favorite database engine. Make sure that there is JDBC driver available to connect with the database engine. JBoss, by default, provides driver for HSQL DB only. JDBC drivers are available for almost all popular databases. Once you download the driver, copy the driver jar file into <JBOSS_HOME>/server/default/lib folder.

    Start your database, and run the queries below from your SQL prompt to create tables that store user login and role information:
    CREATE TABLE users {
    user_name varchar(50) NOT NULL,
    full_name varchar(50),
    passwd varchar(50) NOT NULL,
    language varchar(50),
    mail varchar(50)
    }
    CREATE TABLE user_roles {
    user_name varchar(50) NOT NULL,
    role_name varchar(50) NOT NULL
    }

    Also, add a sample user login "openiadmin/passwd" and assign the required roles of openi and app_admin by running the following queries:
    INSERT INTO users ('openiadmin', 'OpenI Admin', 'dqIXO+Y5MlTnL/pNbfEDCg==', 'English', 'admin@openi.org')
    INSERT INTO user_roles ('openiadmin', 'openi')
    INSERT INTO user_roles ('openiadmin', 'app_admin')

    NOTE: Since password is in digested form, you can not put plain password text. Running the abovementioned SQL script will create sample admin user "'openiadmin" with default password "passwd". Once OpenI is up and running, you can change password or create new user from OpenI menu by selecting Preferences | Manage Users.

  • JBoss Setup
    Configuration of JBoss security and data source for JDBC authentication is must, hence JBoss security policy for application name "openi" should be configured. For configuration add following elements to existing <JBOSS_HOME>/server/default/conf/login-config.xml as follows:
            <application-policy name ="openi">
            <authentication>
            <login-module code = "org.jboss.security.auth.spi.DatabaseServerLoginModule" flag = "required">
            <module-option name = "unauthenticatedIdentity">guest</module-option>
            <module-option name="password-stacking">useFirstPass</module-option>
            <module-option name = "dsJndiName">java:/jdbc/OpenILoginDs</module-option>
            <module-option name="principalsQuery">select passwd as PASSWORD from users where user_name=?</module-option>
            <module-option name="rolesQuery">select role_name as Role, 'Roles' from user_roles where user_name=?</module-option>
            <module-option name="hashAlgorithm">MD5</module-option>
            <module-option name="hashEncoding">base64</module-option>
            </login-module>
            </authentication>
            </application-policy>

        Please note that we are using DatabaseServerLoginModule which needs the specified JNDI data source to connect with database engine. Create one JNDI data source java:/jdbc            /OpenILoginDs descriptor file openi-users-ds.xml as follows and deploy it into <JBOSS_HOME>/server/default/deploy folder :

        <datasources>
            <local-tx-datasource>
            <jndi-name>jdbc/OpenILoginDs</jndi-name>
            <driver-class>DATABASE_DRIVER_CLASS</driver-class>
            <connection-url>JDBC_URL</connection-url>
            <user-name>database_user_name</user-name>
            <password>database_password</password>
            <min-pool-size>5</min-pool-size>
            <max-pool-size>20</max-pool-size>
            <idle-timeout-minutes>0</idle-timeout-minutes>
            <track-statements />
            </local-tx-datasource>
            </datasources>

            Example driver class and url for some popular databases:

            MySql :
            Driver class : com.mysql.jdbc.Driver
            URL format : jdbc:mysql://[host]:[port]/[database]

            SQL Server (JTDS) :
            Driver class : net.sourceforge.jtds.jdbc.Driver
            URL format : jdbc:jtds:<server_type>://<server>[:<port>][/<database>]

            Oracle :
            Driver class : oracle.jdbc.driver.OracleDriver
            URL format : jdbc:oracle:thin:@[host]:[port]:[database]

            Postgres :
            Driver class : org.postgresql.Driver
            URL format : jdbc:postgresql://[host]:[port]/[database]

            ODBC :
            Driver class : sun.jdbc.odbc.JdbcOdbcDriver
            URL format : jdbc:odbc:[datasource]

            NOTE : Don't forget to change the "Cache Timeout" value to "0" in your JBoss application server - go to the <JBOSS_HOME>/server/default/conf directory, open jboss-                        service.xml in text editor and under the section security there is an element <attribute name="DefaultCacheTimeout">1800</attribute>. Change this value to "0" and save                 the file. If the value is not set to "0" then the the changes about users/roles data on the database will not get reflected until JBoss server is restarted.

NOTE:
  1. OpenI binary distribution openi-2.0-RC2-jboss.zip does not include pre-built war for JBoss with JDBC authentication enabled. If you need JDBC authentication, you need to build a JBoss specific WAR with JDBC authentication enabled.
  2. UserManagement feature of Openi works/enables only when Datasource authentication is done as per the above instructions.
 
Comments