updated README

README.md

@@ -1,4 +1,131 @@
-mod-auth-mgr
-============
+# Authentication/Authorisation Manager
 
-Auth Manager Module
+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:
+
+* `address` The main address for the busmod. Optional field. Default value is `vertx.basicauthmanager`
+* `user_collection` The MongoDB collection in which to search for usernames and passwords. Optional field. Default value is `users`.
+* `persistor_address` Address of the persistor busmod to use for usernames and passwords. This field is optional. Default value is `vertx.mongopersistor`.
+* `session_timeout` Timeout of a session, in milliseconds. This field is optional. Default value is `1800000` (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.