== Mongo Auth Provider implementation

We provide an implementation of `link:../../groovydoc/io/vertx/groovy/ext/auth/AuthProvider.html[AuthProvider]` which uses the Vert.x `link:../../groovydoc/io/vertx/groovy/ext/mongo/MongoClient.html[MongoClient]`
to perform authentication and authorisation against a MongoDb.

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-mongo</artifactId>
  <version>3.3.2</version>
</dependency>
----

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

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

To create an instance you first need an instance of `link:../../groovydoc/io/vertx/groovy/ext/mongo/MongoClient.html[MongoClient]`. To learn how to create one
of those please consult the documentation for the MongoClient.

Once you've got one of those you can create a `link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html[MongoAuth]` instance as follows:

[source,groovy]
----
import io.vertx.groovy.ext.mongo.MongoClient
import io.vertx.groovy.ext.auth.mongo.MongoAuth
def client = MongoClient.createShared(vertx, mongoClientConfig)
def authProperties = [:]
def authProvider = MongoAuth.create(client, authProperties)

----

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

The out of the box config assumes the usage of the collection with name "user", the username stored and read by field "username"
some others.

In order to avoid duplicates of user names your "user" collection should have a unique index on "username". In order
to do this you should run the following snippet on your mongo server:

----
db.user.createIndex( { username: 1 }, { unique: true } )
----

The reason you should add the index is that due to the nature of mongo doing a query first to verify if a username is
already taken and then insert a document cannot be run as an atomic action. Using the index the code will try to
insert the row and fail if duplicate.

You can also change all the defaults for the mongo collection and column names using any of the methods:

`link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#setCollectionName(java.lang.String)[setCollectionName]`
`link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#setUsernameField(java.lang.String)[setUsernameField]`
`link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#setPasswordField(java.lang.String)[setPasswordField]`
`link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#setPermissionField(java.lang.String)[setPermissionField]`
`link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#setRoleField(java.lang.String)[setRoleField]`
if you want to adapt that to your needs.

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 field, where the salt is
stored can be set by `link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#setSaltField(java.lang.String)[setSaltField]`, the default is "salt".
You are able to change this behaviour by using `link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/HashStrategy.html#setSaltStyle(io.vertx.ext.auth.mongo.HashSaltStyle)[setSaltStyle]`.
The HashStrategy you can retrieve by  `link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#getHashStrategy()[getHashStrategy]`.
By using this, you are able to set:
`link:todo[NO_SALT]` by which passwords are not crypted and stored
in cleartext. ( see the warning below! )
`link:todo[COLUMN]`, which will create a salt per user and store this
inside the defined column of the user. ( see the warning below! )
`link:todo[EXTERNAL]`, which will store only the crypted password in the
database and will use a salt from external, which you will have to set by `link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/HashStrategy.html#setExternalSalt(java.lang.String)[setExternalSalt]`

If you want to override this behaviour you can do so by providing an alternative hash strategy and setting it with
 `link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#setHashStrategy(io.vertx.ext.auth.mongo.HashStrategy)[setHashStrategy]`

WARNING: It is strongly advised to use the `link:todo[EXTERNAL]` option.
The NO_SALT option is existing for development phase only and even the COLUMN option is not recommended, cause
salt and password are stored inside the same place!

== Authentication

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

[source,groovy]
----
def authInfo = [
  username:"tim",
  password:"sausages"
]
authProvider.authenticate(authInfo, { res ->
  if (res.succeeded()) {
    def user = res.result()
  } else {
    // Failed!
  }
})

----
Instead of the `username` and `password` field names used in the previous snippet, you should use:
`link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#setUsernameCredentialField(java.lang.String)[setUsernameCredentialField]` and
`link:../../groovydoc/io/vertx/groovy/ext/auth/mongo/MongoAuth.html#setPasswordCredentialField(java.lang.String)[setPasswordCredentialField]`

== 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:../../groovydoc/io/vertx/groovy/ext/auth/User.html#isAuthorised(java.lang.String,%20io.vertx.core.Handler)[isAuthorised]` as follows:

[source,groovy]
----

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.

[source,groovy]
----
import io.vertx.groovy.ext.auth.mongo.MongoAuth

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


----