Architecture de référence¶

Vue d'ensemble¶

L'architecture cible repose sur quatre builds MkDocs paralleles, chacun produisant un site statique correspondant a un niveau de classification. Un reverse proxy authentifie les utilisateurs via Keycloak (OIDC) et les route vers le build adequat en fonction d'une claim extraite du token.

graph TD
    subgraph Sources["Sources (Gitea)"]
        MD["Fichiers Markdown<br/>+ front matter classification"]
    end

    subgraph CI["CI/CD (Gitea Actions)"]
        BP["build-public<br/>MKDOCS_CLASSIFICATION=public"]
        BI["build-interne<br/>MKDOCS_CLASSIFICATION=interne"]
        BC["build-confidentiel<br/>MKDOCS_CLASSIFICATION=confidentiel"]
        BR["build-restreint<br/>MKDOCS_CLASSIFICATION=restreint"]
    end

    subgraph Server["Serveur de documentation"]
        DP["/var/www/docs/public/"]
        DI["/var/www/docs/interne/"]
        DC["/var/www/docs/confidentiel/"]
        DR["/var/www/docs/restreint/"]
    end

    subgraph Proxy["Reverse Proxy (Caddy)"]
        OIDC["Auth OIDC<br/>(Keycloak)"]
        Route["Routage par claim<br/>doc_classification"]
    end

    MD --> BP & BI & BC & BR
    BP --> DP
    BI --> DI
    BC --> DC
    BR --> DR
    DP & DI & DC & DR --> Route
    OIDC --> Route

Le principe est simple : les fichiers sources sont uniques et communs a tous les builds. C'est le plugin de filtrage qui, au moment du build, ecarte les pages dont la classification depasse le niveau cible. L'utilisateur final voit un seul domaine ; le proxy s'occupe de lui servir la version correspondant a ses droits.

Front matter et marquage¶

Convention de classification¶

Chaque fichier Markdown peut déclarer son niveau de classification dans son front matter YAML via la cle classification :

---
title: Procedure de deploiement production
description: Etapes de deploiement sur l'environnement de production
classification: confidentiel
---

Les valeurs acceptees sont au nombre de quatre :

Regles de validation¶

Deux regles sont appliquees a la compilation :

• Valeur absente : la page est traitee comme public. Cette convention garantit la compatibilité ascendante avec les fichiers existants non encore marques.
• Valeur inconnue : le build échoue immédiatement (stratégie fail-fast). Une faute de frappe sur la classification est une erreur de sécurité potentielle et ne doit pas etre ignoree silencieusement.

Hiérarchie inclusive¶

Le système de classification est cumulatif vers le bas : chaque niveau inclut tous les niveaux inférieurs. Un utilisateur ayant accès au niveau confidentiel voit egalement toutes les pages interne et public.

Cette hiérarchie est implementee via un mapping numerique interne au plugin :

Le filtre inclut une page si et seulement si rang(classification_page) <= rang(niveau_cible).

Plugin MkDocs classification-filter¶

Rôle du plugin¶

Le plugin classification-filter est un hook MkDocs écrit en Python. Il s'intercale dans le pipeline de build MkDocs et opère en trois phases successives :

Configuration¶

Le niveau cible est fourni via la variable d'environnement MKDOCS_CLASSIFICATION au moment du build. Le plugin lit cette variable au demarrage et valide sa valeur avant d'entreprendre quoi que ce soit :

# mkdocs.yml
plugins:
  - classification-filter:
      env_var: MKDOCS_CLASSIFICATION   # nom de la variable d'environnement
      default_classification: public   # valeur appliquee si front matter absent
      fail_on_unknown: true            # echec immediat si valeur non reconnue

# Exemple d'invocation pour le build "interne"
MKDOCS_CLASSIFICATION=interne mkdocs build --site-dir /var/www/docs/interne

Validation stricte¶

Au demarrage du plugin, la valeur de MKDOCS_CLASSIFICATION est confrontee a la liste des valeurs autorisees. Si la valeur est absente ou inconnue, le plugin leve une exception et interrompt le build avant de traiter le moindre fichier. Ce comportement garantit qu'aucun build ne se produit dans un état ambigu.

Pipeline CI multi-build¶

Les quatre jobs paralleles¶

Le pipeline Gitea Actions declenche quatre jobs indépendants à chaque push sur la branche principale. Ils s'exécutent en parallele et deployent chacun leur build dans le répertoire correspondant.

graph LR
    Push["git push"] --> P["build-public"]
    Push --> I["build-interne"]
    Push --> C["build-confidentiel"]
    Push --> R["build-restreint"]
    P --> Deploy["Deploy /var/www/docs/"]
    I --> Deploy
    C --> Deploy
    R --> Deploy

Structure du workflow¶

# .gitea/workflows/docs.yml
name: Build documentation

on:
  push:
    branches: [main]

jobs:
  build-public:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install mkdocs-material mkdocs-classification-filter
      - run: mkdocs build --site-dir dist/public
        env:
          MKDOCS_CLASSIFICATION: public
      - run: rsync -a dist/public/ docs@server:/var/www/docs/public/

  # build-interne, build-confidentiel, build-restreint suivent la meme structure
  # avec MKDOCS_CLASSIFICATION et le repertoire de destination adaptes.

Reverse proxy et authentification¶

Flux de la requête¶

À chaque requête entrante, le proxy execute la sequence suivante avant de servir la moindre ressource statique :

sequenceDiagram
    participant U as Utilisateur
    participant P as Proxy (Caddy)
    participant K as Keycloak
    participant S as Site statique

    U->>P: GET /docs/procedure-deploiement

    alt Pas de token
        P->>U: 200 OK (build public, sans redirect SSO)
    else Token present
        P->>K: Validation du token (introspection OIDC)
        K-->>P: Claims : { doc_classification: "interne" }
        P->>P: Extraire claim doc_classification
        P->>P: Mapper claim → repertoire de build
        P->>S: Servir depuis /var/www/docs/interne/
        S-->>U: Page HTML (build interne)
    end

Mappage claim vers build¶

La claim OIDC doc_classification est positionnee par Keycloak en fonction des groupes d'appartenance de l'utilisateur :

La hiérarchie inclusive s'applique ici aussi : un utilisateur membre de doc-confidentiel reçoit le build confidentiel, qui contient déjà toutes les pages interne et public.

Cas du contenu public¶

Le contenu public est servi directement, sans redirect vers le SSO. Un utilisateur anonyme qui accede a docs.company.io reçoit le build public sans avoir a s'authentifier. Ce choix est delibere : imposer une authentification pour du contenu public degraderait l'expérience et bloquerait les accès depuis des outils automatises (robots d'indexation interne, scripts de vérification).

URL transparente¶

L'utilisateur voit un unique domaine (docs.company.io). Le routage vers le bon répertoire de build est entierement interne au proxy. Les URLs des pages sont identiques quel que soit le niveau d'accès : la page /procedure-deploiement/ existe dans les quatre builds, mais son contenu peut differ selon les sections filtrees.

Configuration Caddy avec forward_auth¶

# Caddyfile
docs.company.io {
    @authenticated {
        header Authorization *
    }

    handle @authenticated {
        forward_auth keycloak:8080 {
            uri /realms/company/protocol/openid-connect/userinfo
            copy_headers X-Doc-Classification
        }

        # Routage selon le header extrait par forward_auth
        @restreint     header X-Doc-Classification doc-restreint
        @confidentiel  header X-Doc-Classification doc-confidentiel
        @interne       header X-Doc-Classification doc-interne

        handle @restreint    { root * /var/www/docs/restreint    ; file_server }
        handle @confidentiel { root * /var/www/docs/confidentiel ; file_server }
        handle @interne      { root * /var/www/docs/interne      ; file_server }
        handle              { root * /var/www/docs/public        ; file_server }
    }

    # Pas de token : build public sans authentification
    handle {
        root * /var/www/docs/public
        file_server
    }
}

Dimensionnement¶

Ressources du serveur de documentation¶

La documentation statique est extremement légère en termes de ressources. Le goulot d'étranglement typique est le débit réseau lors des déploiements, pas la charge CPU ou mémoire.

Estimation de la taille des builds¶

La taille d'un build MkDocs Material depend principalement du nombre de pages et des assets (images, schemas). Pour une documentation de taille moyenne :

Synthese¶

L'architecture de la plateforme documentaire repose sur une separation nette des responsabilites : les sources Markdown restent uniques et non dupliquees, le plugin de filtrage opère a la compilation, et le contrôle d'accès est entierement delegue au proxy et a Keycloak. La documentation statique ne contient aucune logique d'autorisation a l'execution : si un fichier se trouve dans le répertoire servi, il est accessible. La sécurité repose donc entierement sur la rigueur du pipeline de build et sur la configuration du proxy. Le chapitre suivant detaille l'installation et la configuration pas a pas de chacun de ces composants.