Fichiers d'identité

Conservez les identifiants de client Thalovant, les points de terminaison par défaut, les protocoles et les identifiants du courtier pour les SDK.

View as Markdown Open in Claude Open in ChatGPT

Un fichier d’identité est un élément de configuration privé propre à un client. Il indique au SDK comment s’authentifier, quels protocoles sont activés et où se connecter.

Créez les identités dans Thalovant, puis donnez à chaque client déployé uniquement l’identité dont il a besoin.

Configuration locale recommandée

Pour le développement local, placez les identifiants du SDK dans un fichier YAML protégé :

install -d -m 700 ~/.config/thalovant
$EDITOR ~/.config/thalovant/config.yaml
chmod 600 ~/.config/thalovant/config.yaml

Par défaut, les SDK lisent ~/.config/thalovant/config.yaml. Si XDG_CONFIG_HOME est défini, ils lisent $XDG_CONFIG_HOME/thalovant/config.yaml. Sous Windows, ils utilisent %APPDATA%\Thalovant\config.yaml.

version: 1
profile: prod
profiles:
  prod:
    identity:
      access_key: client-access-key
      password: client-password
      site_id: demo-agent
      default_master: https://jokes.thalovant.io
      default_port: 443
      default_path: /public
      data_plane_endpoints:
        wss: wss://jokes.thalovant.io/public
        https: https://jokes.thalovant.io/public
        mqtt: mqtts://mqtt.thalovant.com:8883
      protocols:
        wss: { enabled: true }
        http: { enabled: true }
        mqtt: { enabled: true }
      mqtt:
        endpoint: mqtts://mqtt.thalovant.com:8883
        username: client-access-key
        password: client-broker-password
        topic_prefix: <namespace>/<hub-id>/<client-id>
        tls: true

Vous pouvez ajouter d’autres profils sous profiles, puis en choisir un dans votre code.

SDK	Charger le profil par défaut	Charger un profil nommé
Python	`ThalovantClient.from_config()`	`ThalovantClient.from_config(profile="prod")`
Node.js	`await ThalovantClient.fromConfig()`	`await ThalovantClient.fromConfig({ profile: "prod" })`
Go	`thalovant.NewClientFromConfig("", "")`	`thalovant.NewClientFromConfig("", "prod")`
Rust	`Client::from_config(None)`	`Client::from_config(Some("prod"))`

En un coup d’œil

Champ	Obligatoire	Rôle
`access_key`	Oui	Identifiant public du client.
`password`	Oui	Secret utilisé par le client pendant l’authentification.
`site_id`	Recommandé	Étiquette stable du site, de l’appareil, du service ou du runtime du client.
`data_plane_endpoints`	Recommandé	Adresses WSS, HTTPS et MQTT explicites.
`protocols`	Recommandé	Protocoles offerts pour ce hub.
`mqtt`	MQTT seulement	Point de terminaison du courtier (broker), nom d’utilisateur, mot de passe et portée des sujets propres au client.

Les hubs n’émettent plus de crypto_key. Le chiffrement provient de la session authentifiée du SDK lui-même, dont la clé est dérivée du password de l’identité. Les SDK actuels acceptent et ignorent crypto_key dans les anciens fichiers d’identité. L’identité a toujours besoin d’un mot de passe valide et d’un point de terminaison activé.

Fichier d’identité brut

{
  "access_key": "client-access-key",
  "password": "client-password",
  "site_id": "demo-agent",
  "default_master": "https://jokes.thalovant.io",
  "default_port": 443,
  "default_path": "/public",
  "data_plane_endpoints": {
    "wss": "wss://jokes.thalovant.io/public",
    "https": "https://jokes.thalovant.io/public",
    "mqtt": "mqtts://mqtt.thalovant.com:8883"
  },
  "protocols": {
    "wss": { "enabled": true },
    "http": { "enabled": true },
    "mqtt": { "enabled": true }
  },
  "mqtt": {
    "endpoint": "mqtts://mqtt.thalovant.com:8883",
    "username": "client-access-key",
    "password": "client-broker-password",
    "topic_prefix": "<namespace>/<hub-id>/<client-id>",
    "tls": true
  }
}

Les fichiers d’identité JSON bruts restent pris en charge. Utilisez-les pour les identités d’un seul client que vous avez téléchargées ou pour des fichiers d’identifiants montés de façon sécurisée. Utilisez la configuration YAML quand vous voulez des profils locaux nommés.

Si vous gardez _identity.json sur un portable, un poste de travail ou une machine virtuelle, restreignez-en l’accès avant que le SDK le lise :

chmod 600 _identity.json

Sous Linux et macOS, les SDK Python, Node.js, Go et Rust rejettent les fichiers d’identité locaux dont les règles d’accès ouvrent l’accès au groupe ou à tout le monde. Dans les conteneurs, montez le fichier depuis un magasin de secrets avec des permissions réservées au propriétaire.

Les SDK prennent aussi en charge des variables d’environnement pour les conteneurs et l’intégration continue. En production, privilégiez les magasins de secrets.

Clés enregistrées

Le fichier d’identité et les clés enregistrées par le SDK fonctionnent ensemble. Conservez les deux d’un redémarrage de l’application ou du conteneur à l’autre :

Élément	Pourquoi il doit être conservé
Clé du client	Après la première connexion, le hub reconnaît ce client grâce à elle. La remplacer à chaque démarrage fait du client un inconnu chaque fois.
Identités de hub enregistrées	Le SDK s’en sert pour reconnaître le hub à la reconnexion et pour rejeter un hub inattendu.
Identifiants en cache, s’ils sont utilisés	Ils évitent de refaire la dérivation à partir du mot de passe à chaque connexion. Protégez-les comme le mot de passe.

Utilisez un répertoire privé, accessible en écriture et persistant, ou le fournisseur de stockage de la plateforme du SDK. Un fichier d’identité monté en lecture seule convient aux identifiants, mais le SDK a aussi besoin d’un stockage accessible en écriture pour ses propres clés enregistrées. Un chemin personnalisé pour le fichier d’identité ne déplace pas à lui seul cet état. Les options de répertoire propres à chaque langage et les exigences de chaque plateforme figurent sur les pages des SDK.

Pour Node côté serveur et MCP, les clés enregistrées se trouvent à côté du fichier de configuration : ~/.config/thalovant par défaut, $XDG_CONFIG_HOME/thalovant quand cette variable est définie, ou %APPDATA%\Thalovant sous Windows. Conservez le répertoire comme un tout. MCP n’offre aucune option par outil pour le modifier.

Node écrit ses clés enregistrées de façon atomique entre les processus. Des clés enregistrées endommagées arrêtent l’opération sans réinitialiser ce qui était enregistré. Si un processus qui a planté laisse .noise-state.lock derrière lui, confirmez que le processus est arrêté avant de supprimer uniquement le fichier de verrou, et gardez les fichiers de clés. Ce verrou ne coordonne ni les sessions de hub actives ni les onglets du navigateur.

Des identités de hub enregistrées endommagées arrêtent l’authentification sans écraser l’état d’origine. Pour les SDK qui les stockent en hexadécimal, les encodages en majuscules et en minuscules d’une même clé désignent le même hub.

Un échec de connexion n’est pas une raison de supprimer les clés enregistrées ni d’en générer de nouvelles. Vérifiez le mot de passe de l’identité, le point de terminaison et la disponibilité de la clé d’origine du client. Confirmez avec la personne propriétaire du hub tout changement d’identité du hub avant de l’accepter.

Manipulation sécuritaire

Créez une identité par processus client actif. Donnez des identités distinctes aux services parallèles, aux processus MCP et aux appareils. Les sessions HTTP et MQTT utilisent un état propre à l’identité : partager des identifiants peut amener des clients à consommer ou à fermer la session les uns des autres.
Stockez-la comme un secret. Utilisez un magasin de secrets, un environnement protégé ou un volume privé du runtime.
Limitez l’accès. Accordez uniquement les règles d’accès dont ce client a besoin.
Faites une rotation en cas d’exposition. Recréez l’identité du client si un fichier ou un secret a été copié au mauvais endroit.
Révisez les clients inactifs. La page Connections peut afficher une révision d’identité quand un client n’a pas signalé sa présence depuis longtemps.
Rafraîchissez après un changement de protocole. Créez ou téléchargez une nouvelle identité après avoir activé HTTPS ou MQTT.

Révision des identités inactives

Le tableau de bord signale une connexion pour une révision d’identité quand aucune présence n’a été observée pendant une période prolongée. Réviser signifie « confirmer que l’appareil ou le runtime est toujours attendu » avant de faire de nouveau confiance à l’identité.

Quand le tableau de bord recommande une mise en quarantaine, utilisez Quarantine identity pour désactiver l’accès de ce client. Faites une rotation de l’identité ou recréez-la avant de rétablir l’accès.

Métadonnées du client

Utilisez site_id et le contexte de requête ensemble :

Métadonnée	Meilleur usage
`site_id`	Étiquette stable de runtime, d’appareil, de pièce, de service ou de déploiement.
`session_id`	Conversation, flux de travail, parcours d’utilisateur ou groupe de traces.
`request_id`	Trace d’une seule requête dans les journaux et les dossiers de soutien.
Contexte	Détails sur l’utilisateur, la plateforme, la version de l’application, les paramètres régionaux ou le flux.

À ne pas stocker

Dépôts publics

Ne validez pas dans un dépôt les fichiers d’identité, les commandes de configuration copiées ni les fichiers d’environnement bruts.

Paquets pour navigateur

Ne livrez pas de secrets de client à longue durée de vie dans le JavaScript servi aux utilisateurs. Utilisez les origines SDK pour les domaines de navigateur approuvés, et gardez les secrets sur un serveur.

Journaux

Masquez les mots de passe, les clés d’accès, les clés de chiffrement, les mots de passe du courtier et le matériel de configuration avant de journaliser.

Demandes de soutien

Communiquez les identifiants de requête, les noms de hub et les erreurs visibles plutôt que le matériel de configuration.