Mongo Auth Provider implementation
We provide an implementation of AuthProvider which uses the Vert.x 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):
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-auth-mongo</artifactId>
<version>3.1.0</version>
</dependency>
-
Gradle (in your
build.gradlefile):
compile io.vertx:vertx-auth-mongo:3.1.0
To create an instance you first need an instance of 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 MongoAuth instance as follows:
MongoClient client = MongoClient.createShared(vertx, mongoClientConfig);
JsonObject authProperties = new JsonObject();
MongoAuth authProvider = MongoAuth.create(client, authProperties);
Once you’ve got your instance you can authenticate and authorise with it just like any 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. You can easily change those defaults with the operations
setCollectionName
setUsernameField
setPasswordField
setPermissionField
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 setSaltField, the default is "salt".
You are able to change this behaviour by using setSaltStyle.
The HashStrategy you can retrieve by getHashStrategy.
By using this, you are able to set:
NO_SALT by which passwords are not crypted and stored
in cleartext. ( see the warning below! )
COLUMN, which will create a salt per user and store this
inside the defined column of the user. ( see the warning below! )
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 setExternalSalt
If you want to override this behaviour you can do so by providing an alternative hash strategy and setting it with
setHashStrategy
|
Warning
|
It is strongly advised to use the 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:
JsonObject authInfo = new JsonObject().put(authProvider.getUsernameCredentialField(), "tim").put(
authProvider.getPasswordCredentialField(), "sausages");
authProvider.authenticate(authInfo, res -> {
if (res.succeeded()) {
User user = res.result();
} else {
// Failed!
}
});
You are able to modify the credential fields by using the methods
setUsernameCredentialField
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.
isAuthorised as follows:
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.
user.isAuthorised(MongoAuth.ROLE_PREFIX + "manager", res -> {
if (res.succeeded()) {
boolean hasRole = res.result();
} else {
// Failed to
}
});