Configuring Security with Pentaho Administration Console

Introduction

This guide will help you configure security in your pentaho administration console.  The information provided here is based on Jetty 6.12 and JettyPlus 6.12 release, as pentaho administration  console uses an embedded jetty server. Out of the box pentaho administration console using a properties based login module but you can plugin any of the login module from below or write your own.

Sample Login Modules

* org.mortbay.jetty.plus.jaas.spi.JDBCLoginModule
* org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule
* org.mortbay.jetty.plus.jaas.spi.DataSourceLoginModule

We'll take a look at all of these, but first, a word about password handling in pentaho administration console, as it applies to all LoginModules.

Passwords/Credentials

Passwords can be stored in clear text, obfuscated or checksummed. The class org.mortbay.util.Password should be used to generate all varieties of passwords,the output from which can be cut and pasted into property files or entered into database tables.

> java \-cp lib/jetty-6.1.2.jar org.mortbay.jetty.security.Password
Usage - java org.mortbay.util.Password \[<user>\] <password>
> java \-cp lib/jetty-6.1.2.jar;lib/jetty-util-6.1.9.jar org.mortbay.jetty.security.Password me you
you
OBF:20771x1b206z
MD5:639bae9ac6b3e1a84cebb7b403297b79
CRYPT:me/ks90E221EY

JDBCLoginModule

The JDBCLoginModule stores user passwords and roles in a database that are accessed via JDBC calls. You can configure the JDBC connection information, as well as the names of the table and columns storing the username and credential, and the name of the table and columns storing the roles.

Here is an example login module configuration file entry for it using an HSQLDB driver:

JDBCLoginModule {
    org.mortbay.jetty.plus.jaas.spi.JDBCLoginModule required
    debug="true"
    dbUrl="jdbc:hsqldb:."
    dbUserName="sa"
    dbPassword="password"
    dbDriver="org.hsqldb.jdbcDriver"
    userTable="myusers"
    userField="myuser"
    credentialField="mypassword"
    userRoleTable="myuserroles"
    userRoleUserField="myuser"
    userRoleRoleField="myrole";
};

There is no particular schema required for the database tables storing the authentication and role information. The properties userTable, userField, credentialField, userRoleTable, userRoleUserField, userRoleRoleField configure the names of the tables and the columns within them that are used to format the following queries:

select <credentialField> from <userTable> where <userField> =?
select <userRoleRoleField> from <userRoleTable> where <userRoleUserField> =?

Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication. Note that this information is only cached for the length of the authenticated session. When the user logs out or the session expires, the information is flushed from memory.

# Security Authentication Section for Enterprise Console
console.security.enabled=true
console.security.roles.allowed=Admin,server-administrator,content-administrator
console.security.roles.delimiter=,
console.security.realm.name=Pentaho
console.security.login.module.name=JDBCLoginModule
console.security.auth.config.path=resource/config/login.conf
console.security.callback.handler=org.mortbay.jetty.plus.jaas.callback.DefaultCallbackHandler

Note that passwords can be stored in the database in plain text or encoded formats, using the org.mortbay.jetty.security.Password class.

DataSourceLoginModule

Similar to the JDBCLoginModule, but this LoginModule uses a DataSource to connect to the database instead of a jdbc driver. The DataSource is obtained by doing a jndi lookup on java:comp/env/$dnJNDIName

Here is a sample login module configuration for it:

ds {
   org.mortbay.jetty.plus.jaas.spi.DataSourceLoginModule required
   debug="true"
   dbJNDIName="ds"
   userTable="myusers"
   userField="myuser"
   credentialField="mypassword"
   userRoleTable="myuserroles"
   userRoleUserField="myuser"
   userRoleRoleField="myrole";
 };

PropertyFileLoginModule

With this login module implementation, the authentication and role information is read from a property file.

props {
   org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule required
   debug="true"
   file="/somewhere/somefile.props";
 };

The file parameter is the location of a properties file of the same format as the etc/realm.properties example file. The format is:

<username>: <password>\[,<rolename> ...\]

Here's an example:

admin: OBF:1xmk1w261u9r1w1c1xmq,user,admin
superadmin: changeme,user,developer
master: MD5:164c88b302622e17050af52c89945d44,user
: CRYPT:adpexzg3FUZAk,admin

The contents of the file are fully read in and cached in memory the first time a user requests authentication.

Changing the admin password

Since Pentaho Administration Console is based on Jetty, the password can be changed according to Jetty's Securing Passwords instructions. The only caveat is that the jetty*.jar files mentioned in the instructions are found in the enterprise-console/lib folder.

Changing the default security settings

The configuration for the security setting is stored in the security section of console.properties

\# Pentaho Administration Console's Jetty Server Settings
console.start.port.number=8088
console.stop.port.number=8033

\# SSL Section for Pentaho Administration Console
console.ssl.enabled=false
console.ssl.port.number=8143
keyAlias=jetty
keyPassword=changeit
keyStore=resource/config/keystore
keyStorePassword=changeit
trustStore=resource/config/keystore
trustStorePassword=changeit
wantClientAuth=false
needClientAuth=false

\# Security Authentication Section for Pentaho Administration Console
console.security.enabled=true
console.security.roles.allowed=admin
console.security.roles.delimiter=,
console.security.realm.name=Pentaho
console.security.login.module.name=PropertiesFileLoginModule
console.security.auth.config.path=resource/config/login.conf

By default the security is enabled. To change the roles you want to allow the application to access provide your list of roles in the console.security.roles.allowed property. By default the roles are comma separated but you can change that configuration also by providing your delimiter in the console.security.roles.delimiter property. The login module name needs to be provided for the property name console.security.login.module.name. This is the name you have given to your login module in the login.conf file. Finally you have to provide the location of your login.conf file in the console.security.auth.config.path property.

Writing Your Own

If you want to implement your own custom LoginModule, there are two classes to be familiar with:

package org.mortbay.jetty.plus.jaas.spi;

public abstract class AbstractLoginModule implements LoginModule
{
  ...
  public abstract UserInfo getUserInfo (String username) throws Exception;
}

package org.mortbay.jetty.plus.jaas.spi;

public class UserInfo
{

  public UserInfo (String userName, Credential credential, List roleNames)
  {
  ...
  }

  public String getUserName()
  {
  ...
  }

  public List getRoleNames ()
  {
  ...
  }

  public boolean checkCredential (Object suppliedCredential)
  {
  ...
  }
}

The org.mortbay.jetty.plus.jaas.spi.AbstractLoginModule implements all of the javax.security.auth.spi.LoginModule methods. All you need to do is to implement the getUserInfo method to return a org.mortbay.jetty.plus.jaas.UserInfo instance which encapsulates the username, password and role names (note: as {{java.lang.String}}s) for a user.

The AbstractLoginModule does not support any caching, so if you want to cache UserInfo (eg as does the org.mortbay.jetty.plus.jaas.spi.PropertyFileLoginModule) then you must provide this yourself.