Security :: Authentication with a Database

This document explains how Roboconf distributions can be configured to authenticate users from a database.
You need a relational database with existing tables.

Creating the Data Source

Install the JDBC driver for the database.

feature:repo-add mvn:org.ops4j.pax.jdbc/pax-jdbc-features/0.9.0/xml/features
feature:install pax-jdbc-config
feature:install pax-jdbc-mysql

You can refer to PAX’s documentation for help about PAX-JDBC.

Then, prepare a configuration file to declare a data source.
In Roboconf’s etc directory, create a file named org.ops4j.datasource-auth.cfg.
What is important is that its name begins with org.ops4j.datasource-. = mysql
databaseName = users
serverName = localhost
portNumber = 3306
user = roboconf
password = roboconf
dataSourceName = jdbc/roboconf-auth-db

Properties names can be found in the driver’s documentation.
Generic ones are also listed here.

Once saved, you can find your configuration in Karaf’s web console, under the OSGi > Configuration menu.
You should also find it as a javax.sql.DataSource under the OSGi > Services menu.

Working with a Test (SQL) Database

Create the tables as follows.

  username varchar(255) NOT NULL,
  password varchar(255) NOT NULL,
  PRIMARY KEY (username)

  username varchar(255) NOT NULL,
  role varchar(255) NOT NULL,
  PRIMARY KEY (username,role)

INSERT INTO users VALUES ("toto","toto");
INSERT INTO roles VALUES ("toto","admin");
INSERT INTO roles VALUES ("toto","viewer");

Creating the REALM

Prepare a (blueprint) file with the connection properties.

<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns=""

	<jaas:config name="karaf" rank="1">
		<jaas:module className="org.apache.karaf.jaas.modules.jdbc.JDBCLoginModule" flags="required">
			datasource = osgi:javax.sql.DataSource/(
			query.password = SELECT password FROM USERS WHERE username=?
			query.role = SELECT role FROM ROLES WHERE username=?

This login module creates a JAAS realm called karaf. It overrides the default JAAS realm (used by Karaf) by using a rank attribute value greater than 0 (the default karaf realm has a rank of 0). Notice that the database and the tables must exist first.

Get the Karaf shell and deploy the blueprint in Karaf.

# Log into the Karaf shell
./client -u user -p password

# Install the deployer feature
feature:install deployer

# Install it using the blueprint deployer
bundle:install --start blueprint:file:/path/to/blueprint.xml

# Verify it is installed

You could also copy the XML file under Karaf’s deploy directory.
Or create a Karaf feature that reference the blueprint.

Then, you can verify your users are found…

# Provided you have a user called "toto" in the "users" table
./client -u toto

The client should prompt for the user password.
The password will be verified against the database.

Notice that you can configure this module to manage users and roles from the DM.
You need to configure the JDBC back-end. Please, refer to Karaf’s web site for more details.