doc: update documentation with latest changes

doc/README.md

@@ -1,6 +1,7 @@
 # Documentation
 
-- (FR) - [Introduction](./fr/introduction.md)
+- (FR) - [Vue d'ensemble](./others/fr/overview.md)
+- (FR) - [Authentification et autorisation](./others/fr/auth.md)
 
 ## Tutorials
 
@@ -9,15 +10,13 @@
 - (FR) - [Déployer une configuration UCI personnalisée sur un agent](./tutorials/fr/deploy-uci-configuration.md)
 - (FR) - [Démarrer un agent avec Docker](./tutorials/fr/docker-agent.md)
 
-## References
-
 ### Specifications
 
-- [Schéma `app.emissary.cadoles.com`](../internal/agent/controller/app/spec/schema.json)
+- [Schema `app.emissary.cadoles.com`](../internal/agent/controller/app/spec/schema.json)
-- [Schéma `proxy.emissary.cadoles.com`](../internal/spec/proxy/schema.json)
+- [Schema `proxy.emissary.cadoles.com`](../internal/spec/proxy/schema.json)
-- [Schéma `mdns.emissary.cadoles.com`](../internal/agent/controller/mdns/spec/schema.json)
+- [Schema `mdns.emissary.cadoles.com`](../internal/agent/controller/mdns/spec/schema.json)
-- [Schéma `uci.emissary.cadoles.com`](../internal/spec/uci/schema.json)
+- [Schema `uci.emissary.cadoles.com`](../internal/spec/uci/schema.json)
-- [Schéma `sysupgrade.openwrt.emissary.cadoles.com`](../internal/agent/controller/openwrt/spec/sysupgrade/schema.json)
+- [Schema `sysupgrade.openwrt.emissary.cadoles.com`](../internal/agent/controller/openwrt/spec/sysupgrade/schema.json)
 
 ### Configuration
 

doc/others/fr/auth.md

@@ -0,0 +1,27 @@
+# Authentification et autorisation
+
+## Authentification
+
+Emissary utilise des [**JSON Web Token**](https://fr.wikipedia.org/wiki/JSON_Web_Token) (JWT) afin d'authentifier les appels à son API REST. 
+
+L'implémentation est compatible avec tout serveur d'authentification exposant une URL proposant un [**JSON Web Key Set**](https://www.ory.sh/docs/hydra/jwks#the-role-of-well-knownjwksjson). 
+
+La plupart des serveurs OpenID Connect exposent un point d'entrée du type [`/.well-known/jwks.json`](https://www.ory.sh/docs/hydra/jwks#the-role-of-well-knownjwksjson) remplissant ce rôle.
+
+Emissary est également en capacité à fonctionner en mode autonome en générant des JWTs signés par une clé privée locale.
+
+## Ségrégation des ressources
+
+Emissary suit une stratégie ["multitenant"](https://fr.wikipedia.org/wiki/Multitenant) de séparer les ressources par organisation.
+
+Un utilisateur est obligatoirement associé à un `tenant`` et ne peut opérer que sur les ressources associées à celui ci.
+
+## Autorisation
+
+Au sein d'un `tenant`, un utilisateur peut avoir un des rôles suivants:
+
+- `writer` - Autorisé à visualiser et modifier les ressources;
+- `reader` - Autorisé à visualiser les ressources.
+
+Un rôle spécial `admin` permet la création et la suppression de `tenants`.
+

doc/others/fr/overview.md

@@ -1,4 +1,4 @@
-# Introduction
+# Vue d'ensemble
 
 "Emissary" est un programme entrant dans la catégorie des outils de gestion et déploiement de configuration.
 

doc/tutorials/fr/deploy-uci-configuration.md

@@ -80,13 +80,13 @@ Via la spécification [`uci.emissary.cadoles.com`](../../../internal/spec/uci/sc
     AGENT_THUMBPRINT="<empreinte agent>"
 
     # Récupérer l'identifiant de l'agent
-    AGENT_ID=$(emissary api agent query -f json | jq -r --arg thumbprint "$AGENT_THUMBPRINT" '.[] | select(.thumbprint == $thumbprint) | .id')
+    AGENT_ID=$(emissary client agent query -f json | jq -r --arg thumbprint "$AGENT_THUMBPRINT" '.[] | select(.thumbprint == $thumbprint) | .id')
     ```
 
 2. Assigner la spécification à l'agent UCI:
 
     ```bash
-    cat my-uci-spec.json | emissary api agent spec update -a ${AGENT_ID} --no-patch --spec-data - --spec-name uci.emissary.cadoles.com
+    cat my-uci-spec.json | emissary client agent spec update -a ${AGENT_ID} --no-patch --spec-data - --spec-name uci.emissary.cadoles.com
     ```
 
     **Bravo, vous avez déployé des spécifications UCI sur votre agent !**
@@ -112,7 +112,7 @@ En intervenant directement sur notre spécification, il est possible de modifier
 2. Mettre à jour la configuration de l'agent:
 
     ```bash
-    cat my-uci-spec.json | emissary api agent spec update -a ${AGENT_ID} --no-patch --spec-data - --spec-name uci.emissary.cadoles.com
+    cat my-uci-spec.json | emissary client agent spec update -a ${AGENT_ID} --no-patch --spec-data - --spec-name uci.emissary.cadoles.com
     ```
 
 3. Sur l'agent, après quelques secondes (par défaut, la fréquence de mise à jour est de 1 fois par minute) l'agent devrait avoir son `hostname` mis à jour:

doc/tutorials/fr/first-steps.md

@@ -80,15 +80,31 @@
 5. Créer un jeton d'administration:
 
     ```shell
-    sudo emissary --workdir /usr/share/emissary --config /etc/emissary/server.yml server auth create-token --role writer --subject $(whoami)
+    sudo emissary --workdir /usr/share/emissary --config /etc/emissary/server.yml server auth create-token --role admin -o "$HOME/.config/emissary/admin-token"
     ```
 
     > **Note** Le jeton sera stocké dans le répertoire `$HOME/.config/emissary`.
 
-6. Vérifier l'authentification sur l'API:
+6. Créer un nouveau `tenant`:
 
     ```shell
-    emissary api agent query
+    sudo emissary --workdir /usr/share/emissary --config /etc/emissary/server.yml client tenant create --tenant-label "My Tenant" -o wide --token-file "$HOME/.config/emissary/admin-token"
+    ```
+
+    Noter la valeur de l'UUID (de la forme `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) affiché dans la colonne `ID`. Il sera identifié comme `$EMISSARY_TENANT` dans les étapes suivantes.
+
+7. Créer un jeton d'authentification pour ce nouveau tenant:
+
+    ```shell
+    sudo emissary --workdir /usr/share/emissary --config /etc/emissary/server.yml server auth create-token --role writer --tenant $EMISSARY_TENANT
+    ```
+
+    > **Note** Le jeton sera stocké dans le fichier `$HOME/.config/emissary/auth-token`. Il sera le jeton utilisé par défaut par le CLI Emissary.
+
+8. Vérifier l'authentification sur l'API:
+
+    ```shell
+    emissary client agent query
     ```
 
     Une réponse équivalente à la suivante devrait s'afficher:
@@ -128,10 +144,18 @@
     Thu May 25 18:48:51 2023 daemon.info emissary[2202]: 2023-05-25 18:48:51.680 [INFO]	<./internal/agent/controller/openwrt/sysupgrade_controller.go:36>	(*SysUpgradeController).Reconcile	could not find sysupgrade spec, doing nothing	{"controller": "sysupgrade-controller"}
     ```
 
-3. Sur le serveur, vérifier que l'agent a pu s'enregistrer:
+2. Récupérer le `thumbprint` de votre agent:
+
+    ```
+    emissary agent show-thumbprint
+    ```
+
+    Noter la valeur de la chaîne de caractères affichée. Elle sera identifiée comme `$AGENT_THUMBPRINT` dans les étapes suivantes.
+
+3. Sur le serveur, "réclamer" votre agent:
 
     ```shell
-    emissary api agent query
+    emissary client agent claim --agent-thumbprint $AGENT_THUMBPRINT
     ```
 
     Un message de ce type devrait s'afficher:
@@ -144,12 +168,12 @@
     +----+-------+-----------------------------------+--------+-----------------------------------+-----------------------------------+
     ```
 
-    Noter l'identifiant associé à l'agent.
+    Noter la valeur de l'identifiant affiché dans la colonne `ID`. Il sera identifié comme `$AGENT_ID` dans les étapes suivantes.
 
 4. Mettre à jour le statut de l'agent afin qu'il soit en capacité à récupérer ses spécifications:
 
     ```
-    emissary api agent update --agent-id <agent_id> --status 1
+    emissary client agent update --agent-id $AGENT_ID --status 1
     ```
 
 **Bravo, vous avez appairé votre premier agent et son serveur Emissary !**