diff options
Diffstat (limited to 'doc/afb-application-writing.md')
| -rw-r--r-- | doc/afb-application-writing.md | 176 |
1 files changed, 173 insertions, 3 deletions
diff --git a/doc/afb-application-writing.md b/doc/afb-application-writing.md index 70dde783..a2bbf4d5 100644 --- a/doc/afb-application-writing.md +++ b/doc/afb-application-writing.md @@ -71,13 +71,21 @@ 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. + ### Handling sessions 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 common HTML5 browser running an HTML5 application. +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. ### Exchanging tokens @@ -86,8 +94,170 @@ 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. The initial token is the default active token. It is the expected -token for new clients. +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. + +### Example of session management + +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. + +#### Using curl + +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" + } + } + +#### Using afb-client-demo + +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}} + +Format of replies +----------------- + +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**. + +### Field jtype + +The field **jtype** must have a value of type string equel to **"afb-reply"**. + +### Field request + +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**. + +#### Subfield request.status + +**status** must have a value of type string. This string is equal to **"success"** +only in case of success. + +#### Subfield request.info + +**info** is of type string and represent optionnal the information added to the reply. + +#### Subfield request.token + +**token** is of type string. It is sent either on the creation of the +session or when the token is refreshed. + +#### Subfield request.uuid + +**uuid** is of type string. It is sent on the creation of the session. + +#### Subfield request.reqid + +**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. + +### Field response + +This field response optionnaly containts the object returned with successful replies. + +### Template +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.... + } |