summaryrefslogtreecommitdiffstats
path: root/agent.md
diff options
context:
space:
mode:
authorJose Bollo <jose.bollo@iot.bzh>2019-11-04 12:02:03 +0100
committerJose Bollo <jose.bollo@iot.bzh>2019-11-04 12:03:31 +0100
commit3ab6b486ca043d237b89fe530cb10ca89b489344 (patch)
treeff6f4869febd31ea3944469d4b0888352e3a15bc /agent.md
parent283c69816157ef11aa93d54ab454a3368f35919e (diff)
Improvement of documentation
Signed-off-by: Jose Bollo <jose.bollo@iot.bzh>
Diffstat (limited to 'agent.md')
-rw-r--r--agent.md77
1 files changed, 77 insertions, 0 deletions
diff --git a/agent.md b/agent.md
new file mode 100644
index 0000000..4e19d45
--- /dev/null
+++ b/agent.md
@@ -0,0 +1,77 @@
+Agent of cynagora
+=================
+
+Cynagora provide a mechanism called agent that allows to add logic of
+autorization to cynagora. It can be used for example to query a user
+to autorize or not a permission ponctually.
+
+Cynagora server implements a predefined agent named the `at` agent that
+implements a simple redirection of a query.
+
+General principle
+-----------------
+
+Rules of the database have a RESULT. That result is either `yes`, `no` or
+an agent query. An agent query is of the form:
+
+ NAME:VALUE
+
+where NAME is the name of the agent, VALUE is a value attached to the rule
+and passed to the agent when querying it.
+
+The colon between the NAME and the VALUE is mandatory.
+
+The agent is queried to give a result with the following values:
+
+ VALUE CLIENT SESSION USER PERMISSION
+
+Example of the agent AT
+-----------------------
+
+The file `cynagora.initial` that provides a default initialisation file
+has the following lines:
+
+ * * @ADMIN * yes forever
+ * * 0 * @:%c:%s:@ADMIN:%p forever
+
+The first line defines a special user `@ADMIN` that always has the permission.
+The special user can be seen as a group: the admin group. Remember that strings
+of the database are conventionnal, that is that the meaning of the USER part
+is conventionnal. A common convention is to use the decimal representation of
+the UID of the unix account to check. That convention is used on the second
+line. That second line defines that the user root (UID 0) is in the group
+admin. To achieve that it uses the agent-AT mecanism.
+
+So if no other rule was selected for the user `0` then cynagora find at least
+the rule that requires to query the predefined agent `@` (AT) with the value
+`%c:%s:@ADMIN:%p`.
+
+The agent is asked with the following values:
+
+ - `%c:%s:@ADMIN:%p` the value
+ - `CLIENT`, `SESSION`, `USER` and `PERMISSION`, the values of original request
+
+The AT-agent use the value `%c:%s:@ADMIN:%p` to compose a check query.
+it interpret the value as a colon separated rule query of cynagora, in the
+order: client, session, user, permission. Then it replaces any occurency of:
+
+ - `%c` with value of `CLIENT` of original request
+ - `%s` with value of `SESSION` of original request
+ - `%u` with value of `USER` of original request
+ - `%p` with value of `PERMISSION` of original request
+ - `%%` with `%`
+ - `%:` with `:`
+
+So for the given value, the result at the end is the result of querying
+cynagora for the result of:
+
+ - client: %c that is substituted by CLIENT
+ - session: %s that is substituted by SESSION
+ - user: @ADMIN
+ - permission: %p that is substituted by PERMISSION
+
+The query to cynagora with CLIENT SESSION @ADMIN PERMMISSION must be done using
+sub-query of agents.
+
+
+