While the next section will cover JWT, this one focuses on using JDBC-based authentication, reusing the wiki database.

    The goal is to require users to authenticate for using the wiki, and have role-based permissions:

    • having no role only allows reading pages,

    • having a writer role allows editing pages,

    • having an editor role allows creating, editing and deleting pages,

    • having an admin role is equivalent to having all possible roles.

    Refactoring the JDBC configuration

    In the previous steps, only the database verticle and service where aware of the JDBC configuration. Now the HTTP service vertice also needs to share the same JDBC access.

    To do that we extract configuration parameters and default values to an interface:

    Now in WikiDatabaseVerticle we use these constants as follows:

    1. JDBCClient dbClient = JDBCClient.createShared(vertx, new JsonObject()
    2.   .put("url", config().getString(CONFIG_WIKIDB_JDBC_URL, DEFAULT_WIKIDB_JDBC_URL))
    3.   .put("driver_class", config().getString(CONFIG_WIKIDB_JDBC_DRIVER_CLASS, DEFAULT_WIKIDB_JDBC_DRIVER_CLASS))
    4.   .put("max_pool_size", config().getInteger(CONFIG_WIKIDB_JDBC_MAX_POOL_SIZE, DEFAULT_JDBC_MAX_POOL_SIZE)));

    Adding JDBC authentication to routes

    The first step is to add the vertx-auth-jdbc module to the Maven dependencies list:

    1. <dependency>
    2.   <groupId>io.vertx</groupId>
    3.   <artifactId>vertx-auth-jdbc</artifactId>
    4. </dependency>

    Back to the HttpServerVerticle class code, we create an authentication provider:

    1. JDBCClient dbClient = JDBCClient.createShared(vertx, new JsonObject()
    2.   .put("url", config().getString(CONFIG_WIKIDB_JDBC_URL, DEFAULT_WIKIDB_JDBC_URL))
    3.   .put("driver_class", config().getString(CONFIG_WIKIDB_JDBC_DRIVER_CLASS, DEFAULT_WIKIDB_JDBC_DRIVER_CLASS))
    4.   .put("max_pool_size", config().getInteger(CONFIG_WIKIDB_JDBC_MAX_POOL_SIZE, DEFAULT_JDBC_MAX_POOL_SIZE)));
    6. JDBCAuth auth = JDBCAuth.create(vertx, dbClient);

    The JDBCAuth object instance is then used to deal with server-side user sessions:

    1. We install a user session handler for all routes.

    2. This automatically redirects requests to /login when there is no user session for the request.

    3. We install authHandler for all routes where authentication is required.

    Finally, we need to create 3 routes for displaying a login form, handling login form submissions and logging out users:

    1. router.get("/login").handler(this::loginHandler);
    2. router.post("/login-auth").handler(FormLoginHandler.create(auth));  (1)
    4. router.get("/logout").handler(context -> {
    5.   context.clearUser();  (2)
    6.   context.response()
    7.     .setStatusCode(302)
    8.     .putHeader("Location", "/")
    9.     .end();
    10. });

    2. Logging out a user is a simple as clearing it from the current RoutingContext.

    The code for the loginHandler method is:

    1. private void loginHandler(RoutingContext context) {
    2.   context.put("title", "Login");
    3.   templateEngine.render(context.data(), "templates/login.ftl", ar -> {
    4.     if (ar.succeeded()) {
    5.       context.response().putHeader("Content-Type", "text/html");
    6.       context.response().end(ar.result());
    7.     } else {
    8.       context.fail(ar.cause());
    9.     }
    10.   });
    11. }

    The HTML template is placed in src/main/resources/templates/login.ftl:

    1. <#include "header.ftl">
    3. <div class="row">
    5.   <div class="col-md-12 mt-1">
    6.     <form action="/login-auth" method="POST">
    7.       <div class="form-group">
    8.         <input type="text" name="username" placeholder="login">
    9.         <input type="password" name="password" placeholder="password">
    10.         <input type="hidden" name="return_url" value="/">
    11.         <button type="submit" class="btn btn-primary">Login</button>
    12.       </div>
    13.     </form>
    14.   </div>
    16. </div>
    18. <#include "footer.ftl">

    The login page looks as follows:

    Supporting features based on roles

    Features need to be activated only if the user has sufficient permissions. In the following screenshot an administrator can create a page and perform a backup:

    as root

    By contrast a user with no role cannot perform these actions:

    To do that, we can access the RoutingContext user reference, and query for permissions. Here is how this is implemented for the indexHandler handler method:

    1. This is how a permission query is made. Note that this is an asynchronous operation.

    2. We use the result to…​

    3. …​leverage it in the HTML template.

    4. We also have access to the user login.

    The template code has been modified to only render certain fragments based on the value of canCreatePage:

    1. <#include "header.ftl">
    3. <div class="row">
    5.   <div class="col-md-12 mt-1">
    6.   <#if canCreatePage>
    7.     <div class="float-right">
    8.       <form class="form-inline" action="/action/create" method="post">
    9.         <div class="form-group">
    10.           <input type="text" class="form-control" id="name" name="name" placeholder="New page name">
    11.         </div>
    12.         <button type="submit" class="btn btn-primary">Create</button>
    13.       </form>
    14.     </div>
    15.   </#if>
    16.     <div class="float-right">
    17.       <a class="btn btn-outline-danger" href="/logout" role="button" aria-pressed="true">Logout (${username})</a>
    19.   </div>
    21.   <div class="col-md-12 mt-1">
    22.   <#list pages>
    23.     <h2>Pages:</h2>
    24.     <ul>
    25.       <#items as page>
    26.         <li><a href="/wiki/${page}">${page}</a></li>
    27.       </#items>
    28.     </ul>
    29.   <#else>
    30.     <p>The wiki is currently empty!</p>
    31.   </#list>
    33.   <#if canCreatePage>
    34.     <#if backup_gist_url?has_content>
    35.       <div class="alert alert-success" role="alert">
    36.         Successfully created a backup:
    37.         <a href="${backup_gist_url}" class="alert-link">${backup_gist_url}</a>
    38.       </div>
    39.     <#else>
    40.       <p>
    41.         <a class="btn btn-outline-secondary btn-sm" href="/action/backup" role="button" aria-pressed="true">Backup</a>
    42.       </p>
    43.     </#if>
    44.   </#if>
    45.   </div>
    47. </div>
    49. <#include "footer.ftl">

    The code is similar for ensuring that updating or deleting a page is restricted to certain roles and is available from the guide Git repository.

    1. private void pageDeletionHandler(RoutingContext context) {
    2.   context.user().isAuthorized("delete", res -> {
    3.     if (res.succeeded() && res.result()) {
    5.       // Original code:
    6.       dbService.deletePage(Integer.valueOf(context.request().getParam("id")), reply -> {
    7.         if (reply.succeeded()) {
    8.           context.response().setStatusCode(303);
    9.           context.response().putHeader("Location", "/");
    10.           context.response().end();
    11.         } else {
    12.           context.fail(reply.cause());
    13.         }
    14.       });
    16.     } else {
    17.       context.response().setStatusCode(403).end();
    18.     }
    19.   });
    20. }

    Populating the database with user and role data

    A last step is required for assembling all pieces of our authentication puzzle. We leave adding user registration and management as an exercice left to the reader, and instead we add some code to ensure that the database is being populated with some roles and accounts:

    The vertx-auth-jdbc prescribes a default database schema with 3 tables: 1 for users (with salted passwords), 1 for role permissions, and 1 to map users to roles. That schema can be changed and configured, but in many cases sticking to the default is a very good option.

    To do that, we are going to deploy a verticle whose sole role is performing the initialisation work:

    1. package io.vertx.guides.wiki.http;
    3. import io.vertx.core.AbstractVerticle;
    4. import io.vertx.core.AsyncResult;
    5. import io.vertx.core.Handler;
    6. import io.vertx.core.json.JsonObject;
    7. import io.vertx.ext.jdbc.JDBCClient;
    8. import io.vertx.ext.sql.ResultSet;
    9. import io.vertx.ext.sql.SQLConnection;
    10. import org.slf4j.Logger;
    11. import org.slf4j.LoggerFactory;
    13. import java.util.Arrays;
    14. import java.util.List;
    16. import static io.vertx.guides.wiki.DatabaseConstants.*;
    18. public class AuthInitializerVerticle extends AbstractVerticle {
    20.   private final Logger logger = LoggerFactory.getLogger(AuthInitializerVerticle.class);
    22.   @Override
    23.   public void start() throws Exception {
    25.     List<String> schemaCreation = Arrays.asList(
    26.       "create table if not exists user (username varchar(255), password varchar(255), password_salt varchar(255));",
    27.       "create table if not exists user_roles (username varchar(255), role varchar(255));",
    28.       "create table if not exists roles_perms (role varchar(255), perm varchar(255));"
    29.     );
    31.     /*
    32.      *    root / admin
    33.      *    foo / bar
    35.      *    baz / baz
    36.      */
    37.     List<String> dataInit = Arrays.asList( (1)
    38.       "insert into user values ('root', 'C705F9EAD3406D0C17DDA3668A365D8991E6D1050C9A41329D9C67FC39E53437A39E83A9586E18C49AD10E41CBB71F0C06626741758E16F9B6C2BA4BEE74017E', '017DC3D7F89CD5E873B16E6CCE9A2307C8E3D9C5758741EEE49A899FFBC379D8');",
    39.       "insert into user values ('foo', 'C3F0D72C1C3C8A11525B4563BAFF0E0F169114DE36796A595B78A373C522C0FF81BC2A683E2CB882A077847E8FD4DA09F1993072A4E9D7671313E4E5DB898F4E', '017DC3D7F89CD5E873B16E6CCE9A2307C8E3D9C5758741EEE49A899FFBC379D8');",
    40.       "insert into user values ('bar', 'AEDD3E9FFCB847596A0596306A4303CC61C43D9904A0184951057D07D2FE2F36FA855C58EBCA9F3AEC9C65C46656F393E3D0F8711881F250D0D860F143A7A281', '017DC3D7F89CD5E873B16E6CCE9A2307C8E3D9C5758741EEE49A899FFBC379D8');",
    41.       "insert into user values ('baz', 'AEDD3E9FFCB847596A0596306A4303CC61C43D9904A0184951057D07D2FE2F36FA855C58EBCA9F3AEC9C65C46656F393E3D0F8711881F250D0D860F143A7A281', '017DC3D7F89CD5E873B16E6CCE9A2307C8E3D9C5758741EEE49A899FFBC379D8');",
    42.       "insert into roles_perms values ('editor', 'create');",
    43.       "insert into roles_perms values ('editor', 'delete');",
    44.       "insert into roles_perms values ('editor', 'update');",
    45.       "insert into roles_perms values ('writer', 'update');",
    46.       "insert into roles_perms values ('admin', 'create');",
    47.       "insert into roles_perms values ('admin', 'delete');",
    48.       "insert into roles_perms values ('admin', 'update');",
    49.       "insert into user_roles values ('root', 'admin');",
    50.       "insert into user_roles values ('foo', 'editor');",
    51.       "insert into user_roles values ('foo', 'writer');",
    52.       "insert into user_roles values ('bar', 'writer');"
    53.     );
    55.     JDBCClient dbClient = JDBCClient.createShared(vertx, new JsonObject()
    56.       .put("url", config().getString(CONFIG_WIKIDB_JDBC_URL, DEFAULT_WIKIDB_JDBC_URL))
    57.       .put("driver_class", config().getString(CONFIG_WIKIDB_JDBC_DRIVER_CLASS, DEFAULT_WIKIDB_JDBC_DRIVER_CLASS))
    58.       .put("max_pool_size", config().getInteger(CONFIG_WIKIDB_JDBC_MAX_POOL_SIZE, DEFAULT_JDBC_MAX_POOL_SIZE)));
    61.     dbClient.getConnection(car -> {
    62.       if (car.succeeded()) {
    63.         SQLConnection connection = car.result();
    64.         connection.batch(schemaCreation, ar -> schemaCreationHandler(dataInit, connection, ar));
    65.       } else {
    66.         logger.error("Cannot obtain a database connection", car.cause());
    67.       }
    68.     });
    69.   }
    71.   private void schemaCreationHandler(List<String> dataInit, SQLConnection connection, AsyncResult<List<Integer>> ar) {
    72.     if (ar.succeeded()) {
    73.       connection.query("select count(*) from user;", testQueryHandler(dataInit, connection));
    74.     } else {
    75.       connection.close();
    76.       logger.error("Schema creation failed", ar.cause());
    77.     }
    78.   }
    80.   private Handler<AsyncResult<ResultSet>> testQueryHandler(List<String> dataInit, SQLConnection connection) {
    81.     return ar -> {
    82.       if (ar.succeeded()) {
    83.         if (ar.result().getResults().get(0).getInteger(0) == 0) {
    84.           logger.info("Need to insert data");
    85.           connection.batch(dataInit, batchInsertHandler(connection));
    86.         } else {
    87.           logger.info("No need to insert data");
    88.           connection.close();
    89.         }
    90.       } else {
    91.         connection.close();
    92.         logger.error("Could not check the number of users in the database", ar.cause());
    93.       }
    94.     };
    95.   }
    97.   private Handler<AsyncResult<List<Integer>>> batchInsertHandler(SQLConnection connection) {
    98.     return ar -> {
    99.       if (ar.succeeded()) {
    100.         logger.info("Successfully inserted data");
    101.       } else {
    102.         logger.error("Could not insert data", ar.cause());
    103.       }
    104.       connection.close();
    105.     };
    106.   }
    107. }
    1. The hashed values can be generated using auth.computeHash(password, salt) where auth is a JDBCAuth instance. Salt values can also be generated using auth.generateSalt().

    This impacts the MainVerticle class, as we now deploy it first:

    1. JsonObject dbConf = new JsonObject()
    2.   .put(WikiDatabaseVerticle.CONFIG_WIKIDB_JDBC_URL, "jdbc:hsqldb:mem:testdb;shutdown=true")
    3.   .put(WikiDatabaseVerticle.CONFIG_WIKIDB_JDBC_MAX_POOL_SIZE, 4);
    5. vertx.deployVerticle(new AuthInitializerVerticle(),
    6.   new DeploymentOptions().setConfig(dbConf), context.asyncAssertSuccess());
    8. vertx.deployVerticle(new WikiDatabaseVerticle(),