version: 1
-Date: 29 mai 2016
+Date: 30 mai 2016
Author: José Bollo
Developpers of HTML5 applications (client side) can easyly create +applications for AGL framework using their prefered +HTML framework.
+ +Developpers can also create powerful server side plugins to improve +their application. This server side plugin should return the mime-type +application/json and can be accessed either by HTTP or by Websockets.
+ +In a near future, the JSON-RPC protocol will be available together +with the current x-afb-json1 protocol.
+ +Two examples of HTML5 applications are given:
+ +afb-client a simple “hello world” application
afm-client a simple “Home screen” application
Writing Qt applications is also possible because Qt offers APIs to +make HTTP queries and to connect using WebSockets.
+ +It is even possible to write a QML application. +It is demontrated by the sample application token-websock:
+ +C applications can use the binder afb-daemon through a websocket connection.
@@ -36,5 +111,235 @@ Its source code is hereThe current implementation use libsystemd and file descriptors. This may be changed in the future to also support secure sockets and being less dependant of libsystemd.
+ + +Applications must be aware of the the features session and token +when they interact with the binder afb-daemon.
+ +Applications are communicating with their binder afb-daemon using +a network connection or a kind of network connection (unix domain +socket isn’t currently implemented but could be used in near future). +Also, HTTP protocol is not a connected protocol. It means that +the socket connection can not be used to authenticate a client.
+ +For this reason, the binder should authenticate the application +by using a commonly shared secret named token and the identification +of the client named session.
+ +The examples token-websock.qml and afb-client are demonstrating +how authentication and sessions are managed.
+ + +Plugins and features of the binder need to keep track of the client +instances. This of importance for plugins running as service +because they may have to separate the data of each client.
+ +For HTML5 applications, the web runtime handles the cookie of session +that the binder afb-daemon automatically sets.
+ +In any case, the session identifier can be set using the parameters +uuid or x-afb-uuid in the request uri. That is understood +by HTTP requests and by the negociation of websockets.
+ + +At start, the framework communicates a common secret to both the binder +and its client: the application. This initial secret is the +initial token.
+ +For each of its client application, the binder manages a current active +token for the session. This authentication token can be a requirement for +accessing some methods.
+ +The token must be passed in the request uri on HTTP or at connecting +websockets using the parameter token or x-afb-token.
+ +To ensure security, tokens must be refreshed periodically.
+ + +For the following exmples, we suppose that you launched afb-daemon like that or similar:
+ +$ afb-daemon --port=1234 --token=123456 [...]
+with the expectation that the plugin AuthLogin is loaded.
+ + +First, connects with the initial token, 123456:
+ +$ curl http://localhost:1234/api/auth/connect?token=123456
+{
+ "jtype": "afb-reply",
+ "request": {
+ "status": "success",
+ "token": "0aef6841-2ddd-436d-b961-ae78da3b5c5f",
+ "uuid": "850c4594-1be1-4e9b-9fcc-38cc3e6ff015"
+ },
+ "response": {"token": "A New Token and Session Context Was Created"}
+}
+It returns an answer containing the uuid of the session, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015, +and the refreshed token, 850c4594-1be1-4e9b-9fcc-38cc3e6ff015.
+ +Let check that it is available:
+ +$ curl http://localhost:1234/api/auth/check?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
+{
+ "jtype": "afb-reply",
+ "request": {"status":"success"},
+ "response": {"isvalid":true}
+}
+It works! So try now to refresh the token:
+ +$ curl http://localhost:1234/api/auth/refresh?token=0aef6841-2ddd-436d-b961-ae78da3b5c5f&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
+{
+ "jtype": "afb-reply",
+ "request": {
+ "status":"success",
+ "token":"b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9"
+ },
+ "response": {"token":"Token was refreshed"}
+}
+Let now close the session:
+ +curl http://localhost:1234/api/auth/logout?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
+{
+ "jtype": "afb-reply",
+ "request": {"status": "success"},
+ "response": {"info":"Token and all resources are released"}
+}
+So now, checking for the uuid will be refused:
+ +curl http://localhost:1234/api/auth/check?token=b8ec3ec3-6ffe-448c-9a6c-efda69ad7bd9&uuid=850c4594-1be1-4e9b-9fcc-38cc3e6ff015
+{
+ "jtype": "afb-reply",
+ "request": {
+ "status": "failed",
+ "info": "invalid token's identity"
+ }
+}
+Here is an example of exchange using afb-client-demo:
+ +$ afb-client-demo ws://localhost:1234/api?token=123456
+auth connect
+ON-REPLY 1:auth/connect: {"jtype":"afb-reply","request":{"status":"success",
+ "token":"63f71a29-8b52-4f9b-829f-b3028ba46b68","uuid":"5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1"},
+ "response":{"token":"A New Token and Session Context Was Created"}}
+auth check
+ON-REPLY 2:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
+auth refresh
+ON-REPLY 4:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
+ "token":"8b8ba8f4-1b0c-48fa-962d-4a00a8c9157e"},"response":{"token":"Token was refreshed"}}
+auth check
+ON-REPLY 5:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
+auth refresh
+ON-REPLY 6:auth/refresh: {"jtype":"afb-reply","request":{"status":"success",
+ "token":"e83b36f8-d945-463d-b983-5d8ed73ba529"},"response":{"token":"Token was refreshed"}}
+Then you leave. And can reconnect as below:
+ +$ afb-client-demo ws://localhost:1234/api?token=e83b36f8-d945-463d-b983-5d8ed73ba529&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1 auth check
+ON-REPLY 1:auth/check: {"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
+The same can be continued using curl:
+ +$ curl http://localhost:1234/api/auth/check?token=e83b36f8-d945-463d-b983-5d8ed73ba529&uuid=5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1
+{"jtype":"afb-reply","request":{"status":"success"},"response":{"isvalid":true}}
+The replies are made of one javascript object returned using JSON serialization.
+ +This object containts at least 2 mandatory fields of name jtype and request +and an optionnal field of name response.
+ + +The field jtype must have a value of type string equel to “afb-reply”.
+ + +The field request must have a value of type object. This request object +has at least one field named status and four optionnal fields of name +info, token, uuid, reqid.
+ + +status must have a value of type string. This string is equal to “success” +only in case of success.
+ + +info is of type string and represent optionnal the information added to the reply.
+ + +token is of type string. It is sent either on the creation of the +session or when the token is refreshed.
+ + +uuid is of type string. It is sent on the creation of the session.
+ + +reqid is of type string. It is sent in response of HTTP requests +that added a parameter of name reqid or x-afb-reqid. The value +sent in the reply is the exact value received on the request.
+ + +This field response optionnaly containts the object returned with successful replies.
+ + +This is a template of replies:
+ +{
+ "jtype": "afb-reply",
+ "request": {
+ "status": "success",
+ "info": "informationnal text",
+ "token": "e83b36f8-d945-463d-b983-5d8ed73ba52",
+ "uuid": "5fcc3f3d-4b84-4fc7-ba66-2d8bd34ae7d1",
+ "reqid": "application-generated-id-23456"
+ },
+ "response": ....any response object....
+}
+