From e0cde4519ff8bae0611a07d10f46e09df87d6466 Mon Sep 17 00:00:00 2001 From: William Petit Date: Tue, 27 Feb 2024 16:24:40 +0100 Subject: [PATCH] doc: update documentation with latest changes --- doc/README.md | 15 ++++---- doc/others/fr/auth.md | 27 +++++++++++++ .../introduction.md => others/fr/overview.md} | 2 +- .../fr/resources/overview.plantuml | 0 doc/{ => others}/fr/resources/overview.svg | 0 doc/tutorials/fr/deploy-uci-configuration.md | 6 +-- doc/tutorials/fr/first-steps.md | 38 +++++++++++++++---- 7 files changed, 69 insertions(+), 19 deletions(-) create mode 100644 doc/others/fr/auth.md rename doc/{fr/introduction.md => others/fr/overview.md} (98%) rename doc/{ => others}/fr/resources/overview.plantuml (100%) rename doc/{ => others}/fr/resources/overview.svg (100%) diff --git a/doc/README.md b/doc/README.md index 7719b81..7b054fb 100644 --- a/doc/README.md +++ b/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) -- [Schéma `proxy.emissary.cadoles.com`](../internal/spec/proxy/schema.json) -- [Schéma `mdns.emissary.cadoles.com`](../internal/agent/controller/mdns/spec/schema.json) -- [Schéma `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 `app.emissary.cadoles.com`](../internal/agent/controller/app/spec/schema.json) +- [Schema `proxy.emissary.cadoles.com`](../internal/spec/proxy/schema.json) +- [Schema `mdns.emissary.cadoles.com`](../internal/agent/controller/mdns/spec/schema.json) +- [Schema `uci.emissary.cadoles.com`](../internal/spec/uci/schema.json) +- [Schema `sysupgrade.openwrt.emissary.cadoles.com`](../internal/agent/controller/openwrt/spec/sysupgrade/schema.json) ### Configuration diff --git a/doc/others/fr/auth.md b/doc/others/fr/auth.md new file mode 100644 index 0000000..b022fe5 --- /dev/null +++ b/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`. + diff --git a/doc/fr/introduction.md b/doc/others/fr/overview.md similarity index 98% rename from doc/fr/introduction.md rename to doc/others/fr/overview.md index 587dd12..0afaee5 100644 --- a/doc/fr/introduction.md +++ b/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. diff --git a/doc/fr/resources/overview.plantuml b/doc/others/fr/resources/overview.plantuml similarity index 100% rename from doc/fr/resources/overview.plantuml rename to doc/others/fr/resources/overview.plantuml diff --git a/doc/fr/resources/overview.svg b/doc/others/fr/resources/overview.svg similarity index 100% rename from doc/fr/resources/overview.svg rename to doc/others/fr/resources/overview.svg diff --git a/doc/tutorials/fr/deploy-uci-configuration.md b/doc/tutorials/fr/deploy-uci-configuration.md index a29a250..c07d096 100644 --- a/doc/tutorials/fr/deploy-uci-configuration.md +++ b/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="" # 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: diff --git a/doc/tutorials/fr/first-steps.md b/doc/tutorials/fr/first-steps.md index 4eb7de2..ff6bc18 100644 --- a/doc/tutorials/fr/first-steps.md +++ b/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 --status 1 + emissary client agent update --agent-id $AGENT_ID --status 1 ``` **Bravo, vous avez appairé votre premier agent et son serveur Emissary !**