JarCastingVert.x 2.x is deprecated - use instead http://vertx.io/docs/#authentication_and_authorisation
Authentication/Authorisation Manager
This is a basic auth manager that verifies usernames and passwords in a MongoDB database and generates time-limited session ids. These session ids can be passed around the event bus.
The auth manager can also authorise a session id. This allows session ids to be passed around the event bus and validated if particular busmods want to find out if the user is authorised.
Sessions time out after a certain amount of time. After that time, they will not verify as ok.
This busmod, is used in the web application tutorial to handle simple user/password authorisation for the application.
Dependencies
This busmod requires a MongoDB persistor busmod to be running to allow searching for usernames and passwords.
Name
The module name is auth-mgr.
Configuration
This busmod takes the following configuration:
{
"address": <address>,
"user_collection": <user_collection>,
"persistor_address": <persistor_address>,
"session_timeout": <session_timeout>
}
For example:
{
"address": "test.my_authmgr",
"user_collection": "users",
"persistor_address": "test.my_persistor",
"session_timeout": 900000
}
Let's take a look at each field in turn:
addressThe main address for the busmod. Optional field. Default value isvertx.basicauthmanageruser_collectionThe MongoDB collection in which to search for usernames and passwords. Optional field. Default value isusers.persistor_addressAddress of the persistor busmod to use for usernames and passwords. This field is optional. Default value isvertx.mongopersistor.session_timeoutTimeout of a session, in milliseconds. This field is optional. Default value is1800000(30 minutes).
Operations
Login
Login with a username and password and obtain a session id if successful.
To login, send a JSON message to the address given by the main address of the busmod + .login. For example if the main address is test.authManager, you send the message to test.authManager.login.
The JSON message should have the following structure:
{
"username": <username>,
"password": <password>
}
If login is successful a reply will be returned:
{
"status": "ok",
"sessionID": <sesson_id>
}
Where session_id is a unique session id.
If login is unsuccessful the following reply will be returned:
{
"status": "denied"
}
Logout
Logout and close a session. Any subsequent attempts to validate the session id will fail.
To login, send a JSON message to the address given by the main address of the busmod + .logout. For example if the main address is test.authManager, you send the message to test.authManager.logout.
The JSON message should have the following structure:
{
"sessionID": <session_id>
}
Where session_id is a unique session id.
If logout is successful the following reply will be returned:
{
"status": "ok"
}
Otherwise, if the session id is not known about:
{
"status": "error"
}
Authorise
Authorise a session id.
To authorise, send a JSON message to the address given by the main address of the busmod + .authorise. For example if the main address is test.authManager, you send the message to test.authManager.authorise.
The JSON message should have the following structure:
{
"sessionID": <session_id>
}
Where session_id is a unique session id.
If the session is valid the following reply will be returned:
{
"status": "ok",
"username": <username>
}
Where username is the username of the user.
Otherwise, if the session is not valid. I.e. it has expired or never existed in the first place.
{
"status": "denied"
}
With this basic auth manager, the user is always authorised if they are logged in, i.e. there is no fine grained authorisation of resources.
