Créer des diagrammes avec Mermaid

Publié le 28 avril 2022 par Andrew Owen (4 minutes)

Je me suis converti à la rédaction de documents en Markdown. La majeure partie de ce site web est écrite en [Markdown](affiché avec Hugo). Mais il arrive parfois que vous ayez besoin d’inclure un graphique ou un diagramme dans vos documents.

Historiquement, cela se faisait sous la forme d’un fichier image, exporté depuis Microsoft Visio. Ce qui est parfait jusqu’à ce que vous ayez besoin de mettre à jour le graphique. Vous devez alors trouver le fichier source, l’ouvrir, le modifier, exporter une image mise à jour et la télécharger sur votre site web.

Il existe une meilleure solution, qui s’appelle Mermaid. Il s’agit d’un outil JavaScript permettant de créer des graphiques et des diagrammes à l’aide d’une [syntaxe] inspirée de Markdown (https://mermaid-js.github.io/mermaid/#/./n00b-syntaxReference “Mermaid syntax”). À la fin de cet article, j’ai inclus un exemple en contexte: un aperçu de la clé de preuve pour l’échange de code (PKCE). Voici le code qui génère l’image:

    sequenceDiagram
    participant User
    participant Mobile App
    participant STS
    participant API
    User->>Mobile App: 1. Click login link.
    
    loop challenge
    Mobile App->Mobile App: 2. Generate code verifier and code challenge.
    end
    
    Mobile App->>STS: 3. Authorization code request and code challenge to authorize.
    STS->>User: 4. Redirect to login/authorization prompt.
    User->>STS: 5. Authenticate and consent
    STS->>Mobile App: 6. Authorize code.
    Mobile App->>STS: 7. Authorization code and code verified to OAuth token.
    
    loop validate
    STS->STS: 8. Validate code verifier and challenge.
    end
    
    STS->>User: 9. ID token and access token.
    User->>API: 10. Request user data with access token.
    API->>User: 11. Response.

Mais avant de pouvoir utiliser Mermaid, vous devez l’ajouter à votre site web. Il existe un guide du débutant, mais comme j’utilise le générateur de site statique Hugo pour ce site, je vais expliquer comment j’ai ajouté Mermaid à Hugo. C’est très simple.

Tout d’abord, récupérez la dernière version et mettez les fichiers dans votre dépôt Git dans le chemin /static/mermaid/.

Deuxièmement, créez un fichier dans votre dépôt Git avec le chemin /layouts/shortcodes/mermaid.html contenant:

    <link href="{{    "mermaid/mermaid.css" | relURL    }}" type="text/css" rel="stylesheet"/>
    <script defer src="{{    "mermaid/mermaid.js" | relURL    }}">mermaid.initialize({startOnLoad:true});</script>
    <div class="mermaid" align="{{     if .Get "align"     }}{{     .Get "align"     }}{{     else     }}center{{     end     }}" >{{     safeHTML .Inner      }}</div>

Cela crée un shortcode Hugo qui vous permet d’utiliser Mermaid sur n’importe quelle page. Et c’est tout. Vous pouvez maintenant inclure Mermaid dans votre markdown. Il existe des plugins pour VSCode pour afficher Mermaid, mais si vous utilisez un CMS sans tête, la façon la plus simple de créer vos tableaux est dans l’éditeur en direct.

Clé de preuve pour l’échange de code

Les clients publics OAuth 2.0 utilisant le flux de code d’autorisation sont sont susceptibles d’être victimes d’une attaque par interception du code d’autorisation. Vous pouvez atténuer ce risque en utilisant une Clé de preuve pour l’échange de code (PKCE telle que définie dans OAuth 2.0 RFC 7636).

La PKCE vous permet d’empêcher l’utilisation malveillante d’un schéma d’URL personnalisé pour capturer des redirections (par exemple MyApp://) qui pourraient potentiellement permettre aux applications de recevoir un code d’autorisation de votre serveur d’autorisation.

Le flux du code d’autorisation PKCE ajoute un secret (un code_verifier généré en utilisant SHA-256) créé par l’application cliente qui est vérifié par le serveur d’autorisation. L’application client crée une valeur de transformation (chaîne de hachage) du code_verifier appelée code_challenge qui est envoyée via HTTPS pour récupérer un code d’autorisation. Un attaquant malveillant peut intercepter ce code, mais ne peut pas l’échanger contre un jeton sans le code_verifier.

Flux du code d’autorisation PKCE

Le flux du code d’autorisation PKCE est similaire au flux du code d’autorisation standard. Il utilise un service de jeton sécurisé (STS).

1. Connexion de l’utilisateur dans l’application client.
2. Le client crée un “code_verifier” cryptographiquement aléatoire et l’utilise pour générer un “code_challenge”.
3. Le client redirige l’utilisateur vers le STS avec le code_challenge.
4. Le STS redirige l’utilisateur vers l’invite de connexion.
5. L’utilisateur s’authentifie.
6. STS stocke code_challenge et redirige l’utilisateur vers le client avec l’autorisation code.
7. Le client envoie code et code_verifier au STS.
8. STS vérifie code_challenge et code_verifier.
9. Le STS répond avec un jeton d’identification, un jeton d’accès et, éventuellement, un jeton de rafraîchissement.
10. Cleint utilise le jeton d’accès pour appeler l’API et accéder aux informations de l’utilisateur.
11. L’API répond avec les données demandées.