Improve README

README.md

@@ -1,6 +1,12 @@
 # HTTP JSON REST Authenticator module for synapse
-Allows you to use any backend implementing a specific HTTP JSON REST endpoint to authenticate a user in Matrix.  
-This allows to externalize authentication in synapse without having to write a module in python but rely on possibly existing workflows.
+This synapse authentication module (password provider) allows you to query identity data in existing webapps, like:
+- Forums (phpBB, Discourse, etc.)
+- Custom Identity stores (Keycloak, ...)
+- CRMs (Wordpress, ...)
+- self-hosted clouds (Nextcloud, ownCloud, ...)
+
+It is mainly used with [mxisd](https://github.com/kamax-io/mxisd), the Federated Matrix Identity Server, to delegate all matters of 
+Identity (directory, authentication, search) to it and offer a fully integrated solution.
 
 ## Install
 Copy in whichever directory python2.x can pick it up as a module.  
@@ -14,6 +20,7 @@ sudo cp rest_auth_provider.py /usr/lib/python2.7/dist-packages/
 ```
 
 ## Configure
+Add or amend the `password_providers` entry like so:
 ```
 password_providers:
   - module: "rest_auth_provider.RestAuthProvider"
@@ -21,12 +28,18 @@ password_providers:
       endpoint: "http://change.me.example.com:12345"
 ```
 
+Replace the `endpoint` value with the appropriate value.
+
 ## Use
 1. Install, configure, restart synapse
 2. Try to login with a valid username and password for the endpoint configured
 
-## Extend
-The following endpoint path is called with HTTP POST request: `/_matrix-internal/identity/v1/check_credentials` with the following JSON body:
+## Integrate
+To use this module with your backend, you will need to implement a single REST endpoint:
+
+Path: `/_matrix-internal/identity/v1/check_credentials`  
+Method: POST  
+Body as JSON UTF-8:
 ```
 {
   "user": {
@@ -36,13 +49,13 @@ The following endpoint path is called with HTTP POST request: `/_matrix-internal
 }
 ```
 
-The following JSON answer is expected:
+The following JSON answer will be provided:
 ```
 {
   "authentication": {
     "success": <boolean>
     "mxid": "@matrix.id.of.the.user:example.com"
-    "display_name": <String of the display name to set, optional>
+    "display_name": "String of the display name to set, optional"
   }
 }
 ```