Technitium DNS : configurer le widget Homepage en toute sécurité

Technitium DNS Server affiche un avertissement lorsque vous générez un token depuis votre compte administrateur : ce token hérite de tous vos privilèges. Pour une intégration Homepage, c’est inutile et risqué.

Dans cet article, vous allez créer un groupe dédié en lecture seule, un utilisateur spécifique, puis générer un token API minimal — exactement ce dont le widget a besoin, rien de plus.

Table des matières

#

• 🔭 Ce que fait le widget Homepage
• 🔐 Principe de moindre privilège
• 👥 Créer le groupe DNS-ReadOnly-Dashboard
• 👤 Créer l’utilisateur dédié
• 🔑 Générer le token API
• ⚙️ Configurer le widget dans Homepage
• ✅ Vérification
• 🎯 Conclusion

🔭 Ce que fait le widget Homepage

#

Il appelle /api/dashboard/stats avec votre token, et affiche jusqu’à 4 métriques parmi :

La configuration du widget dans services.yaml ressemble à ceci :

widget:
  type: technitium
  url: http://<adresse-dns>:5380
  key: <token>
  node: cluster   # optionnel : cluster, ou nom de domaine du nœud
  range: LastDay  # LastHour | LastDay | LastWeek | LastMonth | LastYear
  fields: ["totalQueries", "totalBlocked", "totalCached", "totalClients"]

🔐 Principe de moindre privilège

#

Technitium organise ses permissions en 11 sections :

graph LR
    subgraph "✅ Nécessaire"
        A[Dashboard - View]
    end
    subgraph "❌ Inutile pour Homepage"
        B[Zones]
        C[Cache]
        D[Settings]
        E[Administration]
        F[Logs]
        G[Apps]
        H[Allowed / Blocked]
        I[DhcpServer]
        J[DnsClient]
    end
    style A fill:#14532d,stroke:#4ade80,stroke-width:2px,color:#fff
    style B fill:#7f1d1d,stroke:#f87171,stroke-width:1px,color:#fff
    style C fill:#7f1d1d,stroke:#f87171,stroke-width:1px,color:#fff
    style D fill:#7f1d1d,stroke:#f87171,stroke-width:1px,color:#fff
    style E fill:#7f1d1d,stroke:#f87171,stroke-width:1px,color:#fff
    style F fill:#7f1d1d,stroke:#f87171,stroke-width:1px,color:#fff
    style G fill:#7f1d1d,stroke:#f87171,stroke-width:1px,color:#fff
    style H fill:#7f1d1d,stroke:#f87171,stroke-width:1px,color:#fff
    style I fill:#7f1d1d,stroke:#f87171,stroke-width:1px,color:#fff
    style J fill:#7f1d1d,stroke:#f87171,stroke-width:1px,color:#fff

👥 Créer le groupe DNS-ReadOnly-Dashboard

#

Dans l’interface Technitium, naviguez vers Administration → Groups → Add Group.

Remplissez les champs :

Dans la section Group Permissions, activez uniquement :

• Dashboard → View ✅

Laissez toutes les autres sections (Zones, Cache, Settings, Administration, Logs…) sans aucune permission.

👤 Créer l’utilisateur dédié

#

Naviguez vers Administration → Users → Add User :

Le flux de création est le suivant :

sequenceDiagram
    participant Admin
    participant Technitium
    Admin->>Technitium: Créer groupe DNS-ReadOnly-Dashboard
    Note over Technitium: Permission : Dashboard View uniquement
    Admin->>Technitium: Créer utilisateur homepage
    Note over Technitium: Assigné au groupe DNS-ReadOnly-Dashboard
    Admin->>Technitium: Générer token homepage-dashboard-ro
    Technitium-->>Admin: Token API
    Admin->>Homepage: Coller le token dans services.yaml

🔑 Générer le token API

#

Via l’interface web

#

1. Connectez-vous avec le compte homepage
2. Naviguez vers Administration → Sessions
3. Cliquez sur Create Token
4. Donnez-lui le nom : homepage-dashboard-ro
5. Copiez le token généré

Via l’API (depuis votre terminal)

#

curl "http://<adresse-dns>:5380/api/user/createToken?user=homepage&pass=<mot-de-passe>&tokenName=homepage-dashboard-ro"

La réponse JSON ressemble à :

{
  "status": "ok",
  "token": "a1b2c3d4e5f6..."
}

C’est la valeur du champ token qui vous intéresse.

⚙️ Configurer le widget dans Homepage

#

Dans votre fichier services.yaml :

- DNS:
    icon: technitium.png
    href: http://<adresse-dns>:5380
    description: Technitium DNS Server
    widget:
      type: technitium
      url: http://<adresse-dns>:5380
      key: <votre-token>
      node: cluster        # ou nom de domaine d'un nœud spécifique
      range: LastDay       # LastHour | LastDay | LastWeek | LastMonth | LastYear
      fields:
        - totalQueries
        - totalBlocked
        - totalCached
        - totalClients

Si vous stockez vos secrets dans un fichier séparé (bonne pratique), utilisez la syntaxe de référence Homepage :

# Dans .env
HOMEPAGE_VAR_TECHNITIUM_TOKEN="a1b2c3d4e5f6..."

# Dans services.yaml
key: "{{HOMEPAGE_VAR_TECHNITIUM_TOKEN}}"

✅ Vérification

#

Tester le token manuellement :

curl "http://<adresse-dns>:5380/api/dashboard/stats?token=<votre-token>&type=LastDay"

Vous devez obtenir une réponse JSON avec les statistiques. Si vous obtenez {"status":"error","errorMessage":"Permission denied"}, vérifiez que le groupe DNS-ReadOnly-Dashboard a bien Dashboard → View coché.

Vérifier que le token ne peut pas faire plus :

# Ceci doit retourner une erreur de permission
curl "http://<adresse-dns>:5380/api/zones/list?token=<votre-token>"

Résultat attendu dans Homepage :

graph LR
    A([Homepage]) -->|"GET /api/dashboard/stats?token=xxx"| B[Technitium DNS]
    B -->|"JSON: totalQueries, totalBlocked..."| A
    style A fill:#1e3a8a,stroke:#60a5fa,stroke-width:2px,color:#fff
    style B fill:#065f46,stroke:#4ade80,stroke-width:2px,color:#fff

🎯 Conclusion

#

Ce que vous avez accompli :

• Créé le groupe DNS-ReadOnly-Dashboard avec Dashboard View uniquement
• Créé l’utilisateur homepage rattaché à ce groupe
• Généré le token homepage-dashboard-ro avec des permissions minimales
• Configuré le widget Homepage avec les 4 métriques DNS essentielles
• Vérifié que le token ne peut pas accéder aux zones ni à la configuration

Ressources utiles :

• Documentation widget Technitium - Homepage
• API Docs Technitium DNS Server
• Technitium DNS Server