Secrets et DPAPI

Les secrets du webhook vivent dans un seul fichier, connectors.secrets.json, que l'application chiffre avec DPAPI, le mécanisme de protection de données de Windows.

Structure du fichier

Partez de connectors.secrets.template.json, fourni avec le projet :

{
  "WebHookEncryptionKey": "<clé du webhook, en Base64>",
  "WebHookEncryptionIV": "<IV du webhook, en Base64>",
  "Connectors": {
    "zoho-crm": { "Secrets": { "ClientId": "", "ClientSecret": "", "RefreshToken": "" } },
    "sharepoint": { "Secrets": { "TenantId": "", "ClientId": "", "ClientSecret": "" } },
    "dynamics": { "Secrets": { "TenantId": "", "ClientId": "", "ClientSecret": "" } }
  },
  "Handlers": {
    "mon-gestionnaire": { "Secrets": { "ApiKey": "" } }
  }
}

Entrée	Rôle
`WebHookEncryptionKey`, `WebHookEncryptionIV`	La clé et l'IV du webhook, recopiés exactement depuis la configuration de SESAR (`WebHookKey` et `WebHookIv`). Le `HashKey` est calculé sur la chaîne Base64 elle-même : un espace de trop suffit à faire échouer l'authentification.
`Connectors.{id}.Secrets`	Les secrets d'un connecteur intégré : voir sa page.
`Handlers.{id}.Secrets`	Les secrets d'un gestionnaire, reçus dans ses `Settings`.
`PrivateAESKey`	Clé des fichiers chiffrés par SESAR, au format `<clé>_<IV>`. Aucun connecteur fourni ne la lit à cet endroit : le connecteur SharePoint lit la sienne sous `Connectors.sharepoint.Secrets`.

Les noms d'entrées respectent la casse. Enregistrez le fichier en UTF-8.

Emplacement

Le fichier est lu à l'emplacement donné par ConnectorsSecretsPath, sinon dans le dossier de l'application.

Placez-le hors du dossier du projet et de tout dépôt Git : les fichiers .json du projet sont copiés en clair dans la sortie de publication.
Déposez-le directement sur le serveur. Ne le transportez pas dans un artefact de déploiement.
Donnez au compte de l'application le droit de le lire et de le modifier, et à personne d'autre.

Chiffrement au démarrage

Au démarrage, l'application lit le fichier.
S'il commence par {, après une éventuelle marque d'ordre d'octets UTF-8, elle le considère en clair : elle le lit, le chiffre avec DPAPI (ProtectedData.Protect) et le réécrit au même endroit.
Aux démarrages suivants, elle le déchiffre (ProtectedData.Unprotect).

Attention

Si le chiffrement ou la réécriture échoue, par exemple faute de droit d'écriture, l'application continue avec les valeurs lues et le fichier reste en clair, sans erreur bloquante. Après le premier démarrage, vérifiez que le fichier ne commence plus par {.

Si le déchiffrement échoue (autre compte, autre machine, autre entropie), l'application démarre, mais ne traite aucun webhook : chaque requête reçoit une erreur 500. La raison est donnée par Configuration.InitializationError dans GET /api/health/status.

Un fichier vide, ou enregistré en UTF-16, est pris pour un fichier chiffré, et son déchiffrement échoue.

Portée et entropie

Réglage	Effet
`DataProtectionScope` à `CurrentUser` (défaut)	Seul le compte Windows qui exécute l'application peut déchiffrer le fichier, et seulement sur cette machine. Sous IIS, activez le chargement du profil utilisateur sur le pool d'applications.
`DataProtectionScope` à `LocalMachine`	Tout processus de la machine peut déchiffrer le fichier. Évitez cette portée.
`FileEntropy`	Valeur Base64 ajoutée au chiffrement. La même valeur est requise pour déchiffrer. Une valeur invalide est ignorée. Elle est stockée en clair dans `appsettings.json` : c'est une protection d'appoint, pas un secret.

Note

Le premier démarrage chiffre le fichier pour le compte qui lance l'application. Un essai avec dotnet run sous votre propre compte rend donc le fichier illisible pour le compte du service. Déposez une nouvelle version en clair avant de démarrer le service.

Modifier un secret

Aucune route ne recharge les secrets, et le fichier chiffré n'est lisible que par le compte du service. Pour modifier un secret :

Reprenez toutes les valeurs depuis votre coffre de secrets.
Remplacez le fichier chiffré par une version complète, en clair.
Redémarrez l'application, puis vérifiez que le fichier a été chiffré.

Qui peut lire les secrets

Tout gestionnaire chargé par l'application peut lire l'ensemble des secrets, y compris ceux des autres connecteurs et la clé du webhook. Ne déposez dans le dossier des gestionnaires que des DLL dont vous connaissez le code.

Table of Contents