== JDBC Auth Provider implementation

We provide an implementation of `link:../../apidocs/io/vertx/ext/auth/AuthProvider.html[AuthProvider]` which uses the Vert.x `link:../../apidocs/io/vertx/ext/jdbc/JDBCClient.html[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`):

[source,xml,subs="+attributes"]
----
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-auth-jdbc</artifactId>
  <version>3.3.1</version>
</dependency>
----

* Gradle (in your `build.gradle` file):

[source,groovy,subs="+attributes"]
----
compile 'io.vertx:vertx-auth-jdbc:3.3.1'
----

To create an instance you first need an instance of `link:../../apidocs/io/vertx/ext/jdbc/JDBCClient.html[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 `link:../../apidocs/io/vertx/ext/auth/jdbc/JDBCAuth.html[JDBCAuth]` instance as follows:

[source,java]
----
JDBCClient jdbcClient = JDBCClient.createShared(vertx, jdbcClientConfig);

JDBCAuth authProvider = JDBCAuth.create(jdbcClient);
----

Once you've got your instance you can authenticate and authorise with it just like any `link:../../apidocs/io/vertx/ext/auth/AuthProvider.html[AuthProvider]`.

The out of the box config assumes certain queries for authentication and authorisation, these can easily be changed
with the operations `link:../../apidocs/io/vertx/ext/auth/jdbc/JDBCAuth.html#setAuthenticationQuery-java.lang.String-[setAuthenticationQuery]`,
`link:../../apidocs/io/vertx/ext/auth/jdbc/JDBCAuth.html#setPermissionsQuery-java.lang.String-[setPermissionsQuery]` and
`link:../../apidocs/io/vertx/ext/auth/jdbc/JDBCAuth.html#setRolesQuery-java.lang.String-[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.

If you want to override this behaviour you can do so by providing an alternative hash strategy and setting it with
`link:../../apidocs/io/vertx/ext/auth/jdbc/JDBCAuth.html#setHashStrategy-io.vertx.ext.auth.jdbc.JDBCHashStrategy-[setHashStrategy]`.

WARNING: 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.

== Authentication

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

[source,java]
----
JsonObject authInfo = new JsonObject().put("username", "tim").put("password", "sausages");

authProvider.authenticate(authInfo, res -> {
  if (res.succeeded()) {
    User 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.
`link:../../apidocs/io/vertx/ext/auth/User.html#isAuthorised-java.lang.String-io.vertx.core.Handler-[isAuthorised]` as follows:

[source,java]
----
user.isAuthorised("commit_code", res -> {
  if (res.succeeded()) {
    boolean 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.

[source,java]
----
user.isAuthorised("role:manager", res -> {
  if (res.succeeded()) {
    boolean hasRole = res.result();
  } else {
    // Failed to
  }
});
----

The default role prefix is `role:`. You can change this with `link:../../apidocs/io/vertx/ext/auth/jdbc/JDBCAuth.html#setRolePrefix-java.lang.String-[setRolePrefix]`.
<a href="mailto:julien@julienviet.com">Julien Viet</a><a href="http://tfox.org">Tim Fox</a>