Skip to main content

JDBC Auth Provider implementation

We provide an implementation of AuthProvider which uses the Vert.x JDBCClient to perform authentication and authorisation against any JDBC compliant database.

To use this project, add the following dependency to the dependencies section of your build descriptor:

  • Maven (in your pom.xml):

  • Gradle (in your build.gradle file):

compile 'io.vertx:vertx-auth-jdbc:3.4.1'

To create an instance you first need an instance of JDBCClient. To learn how to create one of those please consult the documentation for the JDBC client.

Once you’ve got one of those you can create a JDBCAuth instance as follows:

def jdbcClient = JDBCClient.createShared(vertx, jdbcClientConfig)

def authProvider = JDBCAuth.create(vertx, jdbcClient)

Once you’ve got your instance you can authenticate and authorise with it just like any AuthProvider.

The out of the box config assumes certain queries for authentication and authorisation, these can easily be changed with the operations setAuthenticationQuery, setPermissionsQuery and setRolesQuery, if you want to use them with a different database schema.

The default implementation assumes that the password is stored in the database as a SHA-512 hash after being concatenated with a salt. It also assumes the salt is stored in the table too.

The basic data definition for the storage should look like this:

-- Take this script with a grain of salt and adapt it to your RDBMS
  `username` VARCHAR(255) NOT NULL,
  `password` VARCHAR(255) NOT NULL,
  `password_salt` VARCHAR(255) NOT NULL

CREATE TABLE `user_roles` (
  `username` VARCHAR(255) NOT NULL,
  `role` VARCHAR(255) NOT NULL

CREATE TABLE `roles_perms` (
  `role` VARCHAR(255) NOT NULL,
  `perm` VARCHAR(255) NOT NULL

ALTER TABLE user ADD CONSTRAINT `pk_username` PRIMARY KEY (username);
ALTER TABLE user_roles ADD CONSTRAINT `pk_user_roles` PRIMARY KEY (username, role);
ALTER TABLE roles_perms ADD CONSTRAINT `pk_roles_perms` PRIMARY KEY (role);

ALTER TABLE user_roles ADD CONSTRAINT fk_username FOREIGN KEY (username) REFERENCES user(username);
ALTER TABLE user_roles ADD CONSTRAINT fk_roles FOREIGN KEY (role) REFERENCES roles_perms(role);

If you want to override this behaviour you can do so by providing an alternative hash strategy and setting it with setHashStrategy.

It is advised to always store your passwords as hashes in your database tables which have been created with a salt which should be stored in the row too. A strong hashing algorithm should be used. It is strongly advised never to store your passwords as plain text.

Hashing passwords

Like any application there will be a time where you need to store new users into the database. Has you have learn passwords are not stored in plain text but hashed according to the hashing strategy. The same strategy is required to hash new password before storing it to the database. Doing it is a 3 step task.

  1. Generate a salt string

  2. Hash the password given the salt string

  3. Store it to the database

def salt = auth.generateSalt()
def hash = auth.computeHash("sausages", salt)
// save to the database
conn.updateWithParams("INSERT INTO user VALUES (?, ?, ?)", [
], { res ->
  if (res.succeeded()) {
    // success!


When authenticating using this implementation, it assumes username and password fields are present in the authentication info:

def authInfo = [

authProvider.authenticate(authInfo, { res ->
  if (res.succeeded()) {
    def user = res.result()
  } else {
    // Failed!

Authorisation - Permission-Role Model

Although Vert.x auth itself does not mandate any specific model of permissions (they are just opaque strings), this implementation assumes a familiar user/role/permission model, where a user can have zero or more roles and a role can have zero or more permissions.

If validating if a user has a particular permission simply pass the permission into. isAuthorised as follows:

user.isAuthorised("commit_code", { res ->
  if (res.succeeded()) {
    def hasPermission = res.result()
  } else {
    // Failed to

If validating that a user has a particular role then you should prefix the argument with the role prefix.

user.isAuthorised("role:manager", { res ->
  if (res.succeeded()) {
    def hasRole = res.result()
  } else {
    // Failed to

The default role prefix is role:. You can change this with setRolePrefix. <a href="">Julien Viet</a><a href="">Tim Fox</a>