Démarrage rapide¶

Dernière mise à jour : 8 octobre 2026

Ce guide vous accompagne pas à pas pour mettre en service Tolk for Cisco UC — des prérequis jusqu'à votre première connexion réussie d'agent IA.

Avant de commencer¶

Le parcours complet se déroule en six étapes :

 ① Prérequis  →  ② Licence  →  ③ Installation  →  ④ Premier démarrage  →  ⑤ Configuration (Web UI)  →  ⑥ Connexion

Sur l'hôte Docker, l'installation elle-même ne nécessite que quelques commandes shell (étapes 3 et 4).

Toute la configuration se fait ensuite depuis l'interface Web d'administration (étape 5).

Durée estimée : ~deux heures pour un déploiement standard sur un hôte Docker préparé.

Étape 1 — Prérequis¶

Docker¶

Tolk for Cisco UC est déployé sous forme de conteneur Docker.

Prérequis :

Docker Engine ≥ 27.0
Docker Compose ≥ 2.32

Pour les instructions d'installation, consultez la documentation officielle de Docker.

docker --version
docker compose version

Compte de service : créez un utilisateur non-root dédié (ex. docker) et ajoutez-le au groupe docker pour qu'il puisse gérer les conteneurs sans sudo :

sudo useradd -m -s /bin/bash docker
sudo usermod -aG docker docker

Toutes les commandes suivantes de ce guide supposent que vous êtes connecté avec cet utilisateur.

Système d'exploitation hôte : tout OS capable d'exécuter Docker.

Linux — recommandé pour la production (Docker Engine)
macOS — pris en charge via Docker Desktop
Windows — pris en charge via Docker Desktop avec WSL 2

Recommandation production

Pour les déploiements en production, utilisez un hôte Linux avec Docker Engine pour de meilleures performances, stabilité et sécurité. Docker Desktop (macOS / Windows) convient pour l'évaluation, le développement et les environnements de lab.

Ressources hôte minimales :

CPU : 2 vCPUs
RAM : 2 Go
Disque : 10 Go (variable selon la rétention des sauvegardes et le volume de rapports)

Prérequis Cisco UC¶

CUCMIMPCUC

Le module CUCM utilise trois protocoles : AXL, RIS et SSH — plus HTTPS vers les terminaux pour les sous-modules optionnels téléphones IP et RoomOS.

Protocole	Prérequis
AXL	Activer Cisco AXL Web Service sur le noeud publisher (Serviceability → Tools → Service Activation). Créer un compte utilisateur (End User ou Application User) avec les rôles "Standard AXL API Users", "Standard SERVICEABILITY" et "Standard CCM Admin Users"
RIS	Cisco RisPort70 fonctionne par défaut — aucune activation nécessaire. Même compte utilisateur que pour la connexion AXL.
SSH	Accès SSH activé sur les noeuds CUCM. Un compte administrateur de plateforme (OS admin) avec un privilège de niveau 4 ("Advanced") est requis.
Téléphones IP (HTTPS)	Captures d'écran, pages d'information web et messages texte sur les téléphones IP Cisco 88xx / 98xx, via le serveur web du téléphone. Activer le Web Access sur les téléphones. Créer un utilisateur CUCM (End User ou Application User) dédié à l'accès web des téléphones, avec les téléphones ciblés dans ses Controlled Devices.
RoomOS (xAPI / HTTPS)	Terminaux Cisco RoomOS pilotés via leur xAPI en HTTPS. Laisser le serveur web HTTPS activé sur les terminaux (`NetworkServices HTTP Mode` : `HTTPS` ou `HTTP+HTTPS`). Créer un compte local sur les terminaux avec les rôles correspondant aux opérations prévues : Admin (toute la configuration et les commandes), User (annuaire, appels, la plupart des lectures), Integrator / RoomControl (extensions d'interface, messages à l'écran), Audit (journaux).

Le module IMP utilise deux protocoles : AXL et SSH.

Protocole	Prérequis
AXL	Activer Cisco AXL Web Service sur le noeud publisher (Serviceability → Tools → Service Activation). Même compte utilisateur que pour la connexion AXL du CUCM.
SSH	Accès SSH activé sur les noeuds IMP. Un compte administrateur de plateforme (OS admin) avec un privilège de niveau 4 ("Advanced") est requis.

Le module CUC utilise deux protocoles : CUPI (REST) et SSH. Il n'y a pas d'AXL/SOAP ni de notion de cluster — les opérations sont effectuées par hôte.

Protocole	Prérequis
CUPI	REST est activé par défaut sur tcp/8443 (`/vmrest/`). Créer un compte administrateur Unity Connection. Pour un usage en lecture seule, le rôle "System Administrator" suffit. Pour les opérations d'écriture (provisioning d'utilisateurs, call handlers, schedules, etc.), assigner le modèle de rôles couvrant les endpoints CUPI ciblés.
SSH	Accès SSH activé sur les noeuds CUC. Un compte administrateur de plateforme (OS admin) avec un privilège de niveau 4 ("Advanced") est requis.

Comptes nominatifs — bonne pratique

Créez un compte dédié par utilisateur Tolk sur les serveurs Cisco UC, plutôt que de partager un compte de service unique. Cela permet le contrôle d'accès par utilisateur, la corrélation bout-en-bout de la piste d'audit et l'isolation des identifiants.

Prérequis réseau¶

Assurez-vous que les ports suivants sont ouverts sur vos pare-feux :

Source	Destination	Port	Protocole	Objet
Agent IA	Serveur Tolk	tcp/8443*	HTTPS	(sans proxy) Connectivité client MCP
Reverse-proxy web	Serveur Tolk	tcp/8443*	HTTPS	(avec proxy) Connectivité client MCP via reverse-proxy
Réseau Admin	Serveur Tolk	tcp/9443*	HTTPS	(sans proxy) Connectivité à l'interface Web d'administration
Reverse-proxy web	Serveur Tolk	tcp/9443*	HTTPS	(avec proxy) Interface Web d'admin via reverse-proxy
Serveur Tolk	CUCM	tcp/8443	HTTPS	AXL/SOAP, RIS/SOAP
Serveur Tolk	CUCM	tcp/22	SSH	Commandes VOS CLI
Serveur Tolk	Terminaux (phones & roomOS)	tcp/443	HTTPS	Gestion des terminaux, messages, screenshots, ...
Serveur Tolk	IMP	tcp/8443	HTTPS	AXL/SOAP
Serveur Tolk	IMP	tcp/22	SSH	Commandes VOS CLI
Serveur Tolk	CUC	tcp/8443	HTTPS	CUPI/REST
Serveur Tolk	CUC	tcp/22	SSH	Commandes VOS CLI
Serveur Tolk	Serveur SFTP	tcp/22	SSH	(optionnel) Export de sauvegarde
Serveur Tolk	Serveur DNS	udp/53	DNS	Résolution des noms de domaines internes

* MCP_SERVER_PORT & ADMIN_UI_PORT par défaut — configurables (voir étape 3.5).

Aucun accès internet requis

Le serveur n'initie jamais de connexions sortantes vers internet. Les licences, mises à jour et télémétries sont entièrement hors ligne.

Étape 2 — Obtenir votre licence¶

Tolk for Cisco UC nécessite une licence valide pour fonctionner. Chaque licence est liée au nom d'hôte du serveur.

Récupérer le nom d'hôte de votre serveur :

hostname -f

Liaison au nom d'hôte

La licence est verrouillée sur le FQDN retourné par hostname -f sur l'hôte Docker. Assurez-vous que ce nom d'hôte est stable avant de commander — tout changement (Hostname ou nom de domaine) invalidera la licence.

Pour commander une licence :

Contactez tolk@sourdeau.com avec le nom de votre organisation, le périmètre de déploiement prévu et le nom d'hôte du serveur (hostname -f).
Vous recevrez un fichier license.jwt par transfert sécurisé.
La licence est téléversée après le premier démarrage via l'interface Web d'administration (étape 5.1).

Licence de démonstration disponible

Une licence de démonstration à durée limitée est disponible sur demande pour évaluer le produit dans votre environnement.

La licence est indépendante de la version

Une licence valide continue de fonctionner à travers les mises à jour — aucune réémission n'est nécessaire après une mise à jour.

Étape 3 — Installation¶

3.1 Obtenir le paquet¶

Tolk est distribué sous forme d'une archive unique :

tolk-for-cisco-uc-<version>.tar.gz          # Archive de release (config, docker-compose, scripts, image Docker pré-construite)

Le paquet est livré par l'éditeur via transfert de fichiers sécurisé. Aucun accès internet n'est requis sur le serveur cible. Contactez tolk@sourdeau.com pour obtenir une version.

Sur l'hôte Docker, créez le répertoire d'installation :

mkdir ~/tolk && cd ~/tolk

Puis transférez l'archive dans ~/tolk (par ex. en SFTP) :

sftp> put tolk-for-cisco-uc-<version>.tar.gz tolk/

3.2 Vérifier l'intégrité du paquet¶

Avant l'installation, vérifiez l'intégrité de l'archive en la comparant au checksum SHA-512 publié via DNS :

Depuis LinuxDepuis Windows

# 1. Interroger l'enregistrement TXT DNS publié par l'éditeur (depuis un ordinateur avec résolution DNS publique)
dig tolk-for-cisco-uc-<version>.sha512.check.consulting.sourdeau.com txt +short

# 2. Calculer le hachage SHA-512 de l'archive reçue
sha512sum tolk-for-cisco-uc-<version>.tar.gz

# 3. Comparer les deux valeurs — elles doivent correspondre exactement

# 1. Interroger l'enregistrement TXT DNS publié par l'éditeur (depuis un ordinateur avec résolution DNS publique)
nslookup -q=txt tolk-for-cisco-uc-<version>.sha512.check.consulting.sourdeau.com

# 2. Calculer le hachage SHA-512 de l'archive reçue
Get-FileHash -Algorithm SHA512 tolk-for-cisco-uc-<version>.tar.gz

# 3. Comparer les deux valeurs — elles doivent correspondre (Get-FileHash affiche le hachage en majuscules)

Ne pas ignorer cette étape

Si les valeurs ne correspondent pas, n'allez pas plus loin. Contactez tolk@sourdeau.com immédiatement.

3.3 Extraire le paquet¶

Depuis le répertoire d'installation, extrayez l'archive puis supprimez-la :

cd ~/tolk
tar -xzf tolk-for-cisco-uc-<version>.tar.gz
rm -f tolk-for-cisco-uc-<version>.tar.gz

Extraire depuis l'intérieur du répertoire d'installation

L'archive est « à plat » — elle n'a aucun dossier racine, son contenu est donc écrit dans le répertoire de travail courant. Placez toujours le .tar.gz dans ~/tolk et lancez tar -xzf depuis ~/tolk, sinon les fichiers se disperseront à l'endroit où vous vous trouvez.

Après extraction, le répertoire contient le docker-compose.yml, le fichier .env.example, le script d'installation tolk-setup.sh, l'image Docker pré-construite et tous les fichiers associés. Le paquet ne contient aucun .env : il est créé par le script d'installation (étape suivante), de sorte que l'extraction d'une version ultérieure ne peut jamais écraser votre configuration.

3.4 Installer — lancer le script d'installation¶

./tolk-setup.sh

Lors d'une première installation, le script :

charge l'image Docker (docker load) puis supprime l'archive de l'image ;
crée .env en copiant .env.example (uniquement si .env n'existe pas encore) ;
s'arrête, pour que vous renseigniez les quelques valeurs Docker du .env avant le premier démarrage (étape 3.5).

--dry-run est réservé aux mises à jour

./tolk-setup.sh --dry-run prévisualise les modifications du .env lors d'une mise à jour (voir Operations). Lors d'une première installation, il n'y a pas encore de .env à comparer : lancez simplement ./tolk-setup.sh.

Vérifiez que l'image est bien chargée :

docker images | grep tolk

Vous devriez voir tolk-for-cisco-uc avec le tag latest.

Docker Compose utilisera l'image pré-chargée et montera les données d'exécution depuis ce répertoire.

3.5 Configurer les valeurs de démarrage Docker dans `.env`¶

Toute la configuration se fait depuis l'interface Web d'administration

Les paramètres applicatifs (identité du serveur, authentification, certificats TLS, produits, sauvegardes, journalisation, limitation de débit, clients, licence…) se gèrent tous depuis l'interface Web d'administration après le premier démarrage — aucune édition du .env n'est nécessaire pour eux.

Seules quelques valeurs sont lues par Docker Compose lui-même à la création du conteneur (nom d'hôte du conteneur, utilisateur, ports publiés), ainsi que la liste des réseaux autorisés à joindre l'interface Web d'administration, sans laquelle vous ne pourriez pas y accéder. Elles doivent être correctes avant le premier docker compose up -d.

Récupérez les valeurs de votre hôte, UID & GID :

hostname -f && id -u && id -g

Puis éditez .env :

vim ./.env

Clé	Valeur à définir	Pourquoi
`HOST_FQDN`	Le FQDN de votre serveur — résultat de `hostname -f` (ex. `tolk.domain.com`)	Obligatoire — utilisé comme nom d'hôte du conteneur ; doit correspondre à la liaison hostname de la licence
`UID` / `GID`	Résultats de `id -u` / `id -g` (défaut `1000` ; `0` = root est refusé)	Obligatoire si votre compte de service n'est pas UID/GID `1000` — permet au conteneur d'écrire dans les volumes
`MCP_SERVER_PORT`	Port du transport MCP pour les agents IA (défaut `8443`)	Optionnel — à changer seulement si `8443` est déjà utilisé sur l'hôte ; adaptez votre pare-feu en conséquence
`ADMIN_UI_PORT`	Port de l'interface Web d'administration / console de récupération (défaut `9443`)	Optionnel — à changer seulement si `9443` est déjà utilisé ; doit différer de `MCP_SERVER_PORT`
`ADMIN_UI_TRUSTED_IPS`	Réseaux autorisés à joindre l'interface Web d'administration (défaut : plages privées RFC 1918)	Optionnel — à ajuster seulement si vos postes d'administration sont hors de `10.0.0.0/8`, `172.16.0.0/12` et `192.168.0.0/16`

Les paramètres Docker nécessitent une re-création du conteneur

HOST_FQDN, UID / GID, MCP_SERVER_PORT et ADMIN_UI_PORT sont appliqués par Docker Compose. Si vous les modifiez ultérieurement (depuis l'interface Web d'administration ou dans .env), le Appliquer & redémarrer applicatif ne suffit pas : exécutez docker compose up -d sur l'hôte pour re-créer le conteneur.

Étape 4 — Premier démarrage¶

4.1 Démarrer le conteneur¶

docker compose up -d

Vérifiez que le conteneur est en cours d'exécution et en bonne santé :

docker compose ps
docker compose logs -f

Au premier démarrage, le serveur effectue automatiquement :

Génération d'une paire de clés RSA-4096 — utilisée pour la signature JWT, le chiffrement des sauvegardes et la vérification des licences
Génération d'un certificat TLS auto-signé — à partir des valeurs d'identité par défaut ; il est régénéré automatiquement dès que vous définissez l'identité de votre serveur (étapes 5.2 – 5.3)
Exécution de la vérification d'intégrité logicielle — par rapport à manifest.json et manifest.sig
Vérification de la licence — aucune licence n'étant encore installée, le serveur démarre en mode récupération : le point de terminaison MCP reste fermé et seule l'interface Web d'administration est servie

Le premier démarrage s'effectue en mode récupération

Tant qu'aucune licence valide n'est installée, le point de terminaison MCP (MCP_SERVER_PORT) reste fermé et le serveur n'expose que l'interface Web d'administration (ADMIN_UI_PORT, la console de récupération). C'est le comportement attendu — vous allez créer un compte admin (4.2), puis configurer le serveur et téléverser la licence depuis l'interface Web (étape 5).

4.2 Créer le compte administrateur¶

L'interface Web d'administration est livrée sans compte administrateur par défaut. Créez votre premier compte administrateur (profil superadmin) directement dans le conteneur en cours d'exécution :

docker compose exec tolk python scripts/admin_set_password.py admin --profile superadmin

Le mot de passe est demandé deux fois (New password: / Confirm password:) ; la saisie n'est pas affichée, et le mot de passe n'est jamais conservé dans l'historique du shell ni visible dans la liste des processus.

Politique de mot de passe

Le mot de passe doit respecter la politique en vigueur (par défaut : au moins 12 caractères, avec complexité).

Les comptes administrateurs suivants se créent ensuite depuis la page Administrateurs de l'interface Web.

Ouvrez l'interface Web d'administration dans votre navigateur — elle écoute sur ADMIN_UI_PORT (défaut 9443) :

https://<fqdn-de-votre-serveur>:9443

Acceptez l'avertissement de certificat TLS (le certificat est auto-signé au premier démarrage), puis connectez-vous avec le compte admin créé à l'étape 4.2.

Interface Web d'administration — page de connexion

Le Tableau de bord s'ouvre. Aucune licence n'étant encore installée, la tuile Licence est signalée comme non valide — c'est le mode récupération décrit ci-dessus.

Interface Web d'administration — tableau de bord en mode récupération

Étape 5 — Configurer depuis l'interface Web d'administration¶

Désormais, toute la configuration se fait dans l'interface Web d'administration. Chaque modification est d'abord mise en attente, puis activée par Appliquer & redémarrer — vous pouvez mettre en attente plusieurs modifications (licence, identité…) et les appliquer toutes en un seul redémarrage.

Référence complète de configuration

Tous les paramètres disponibles sont documentés dans le guide Setup, et chaque paramètre dispose d'une aide contextuelle dans l'interface Web.

5.1 Importer votre licence¶

Ouvrez la page Licence. Le Nom d'hôte serveur affiché doit correspondre au nom d'hôte lié à votre licence.
Dans la carte Importer une licence, sélectionnez votre fichier license.jwt (ou collez le token) puis cliquez sur Importer la licence. La signature est validée et la licence détectée est prévisualisée avant d'être importée.

Page Licence — import de la licence

La licence est mise en attente : elle devient active au prochain Appliquer & redémarrer (étape 5.3).

5.2 Définir l'identité du serveur¶

Ouvrez Paramètres globaux et définissez les valeurs qui identifient votre serveur : cliquez sur Modifier sur un paramètre, saisissez la nouvelle valeur puis cliquez sur Enregistrer (une aide contextuelle décrit chaque paramètre). Les valeurs par défaut (tolk.domain.com) doivent être remplacées par le FQDN de votre serveur :

Onglet → Section	Paramètre	Valeur à définir	Pourquoi
Server → Reverse proxy	`MCP_SERVER_PUBLIC_URL`, `TRUSTED_PROXY_IPS`	(optionnel) URL publique et IP des proxys, uniquement derrière un reverse proxy / VIP	URL annoncée et IP réelle du client derrière le proxy
Server → Transport	`MCP_SERVER_SECURITY_ALLOWED_HOSTS`	Le FQDN du serveur (ex. `tolk.domain.com:*` ; boucle locale implicite)	Protection DNS rebinding et entrées SAN du certificat TLS
Server → Transport	`MCP_SERVER_SECURITY_ALLOWED_ORIGINS`	L'origine du serveur (ex. `https://tolk.domain.com:8443`)	Validation CORS / en-tête Origin
Authentication → Identité	`AUTH_ISSUER`	L'URL HTTPS de votre serveur (ex. `https://tolk.domain.com:8443`)	Intégré dans les tokens JWT et les métadonnées OAuth ; CN du certificat TLS

Paramètres globaux — onglet Server, reverse proxy et sécurité du transport

Paramètres globaux — onglet Authentication, AUTH_ISSUER

Champs d'organisation du certificat

Dans Paramètres globaux, vous pouvez aussi renseigner les champs CERT_* (Country, State, Organization, OU) de l'onglet TLS / Crypto : ils complètent le sujet du certificat auto-signé et des futurs CSR.

5.3 Appliquer & redémarrer¶

Un bandeau indique le nombre de modifications en attente. Cliquez sur Appliquer & redémarrer : la page Appliquer les modifications de configuration liste les modifications en attente (valeurs avant / après, auteur — chacune peut être annulée) et exécute les contrôles avant redémarrage :

Contrôle d'intégrité — les fichiers logiciels correspondent au manifeste signé ;
Certificats TLS — chaque service démarrera avec un certificat valide. L'identité du serveur ayant changé, ce contrôle peut indiquer que le certificat auto-signé sera régénéré au redémarrage : c'est le comportement attendu ;
Clients actifs / Sessions admin actives — les clients MCP et sessions d'administration que le redémarrage interrompra brièvement.

Vérifiez qu'aucun statut n'est en Échec, puis cliquez sur Redémarrer maintenant.

Appliquer les modifications — modifications en attente et contrôles avant redémarrage

Après le redémarrage :

le serveur quitte le mode récupération : le point de terminaison MCP est servi sur MCP_SERVER_PORT (défaut 8443) et les outils des produits sous licence deviennent disponibles ;
le certificat TLS auto-signé est régénéré automatiquement avec l'identité de votre serveur — CN = hôte de AUTH_ISSUER, entrées SAN dérivées de MCP_SERVER_SECURITY_ALLOWED_HOSTS (et MCP_SERVER_PUBLIC_URL), sans localhost / 127.0.0.1. Votre navigateur affiche un nouvel avertissement de certificat : c'est attendu.

La page Licence affiche désormais le détail de la licence (client, niveau, expiration, produits activés, nombre max de clients).

5.4 Faire confiance aux certificats Cisco UC¶

La vérification des certificats TLS des noeuds Cisco UC est activée par défaut (SERVER_CUCM_SSL_VERIFY, SERVER_IMP_SSL_VERIFY, SERVER_CUC_SSL_VERIFY = True). Tolk doit donc faire confiance à la CA qui a émis les certificats tomcat de vos noeuds (ou les certificats tomcat eux-mêmes). Pour les téléphones IP et les terminaux RoomOS, la vérification est désactivée par défaut (SERVER_CUCM_PHONES_SSL_VERIFY, SERVER_CUCM_ROOMOS_SSL_VERIFY = False) : aucun magasin de confiance n'est nécessaire, sauf si vous l'activez.

Ouvrez la page Produits, puis l'onglet de votre produit (CUCM, IMP, CUC — seuls les produits sous licence sont affichés).
Sur le paramètre SERVER_<PRODUIT>_SSL_CA_BUNDLE, cliquez sur Voir / Éditer pour ouvrir le Magasin de confiance (CA).
Collez le ou les certificats PEM dans Ajouter un certificat — les doublons sont ignorés.
Cliquez sur Appliquer & redémarrer pour charger le magasin de confiance mis à jour.

Page Produits — magasin de confiance CA

Passez en revue les autres paramètres produit sur la même page (ports, timeouts, sous-modules téléphones IP et RoomOS…) ; voir Setup pour la référence complète.

5.5 Tester la connectivité vers Cisco UC (recommandé)¶

Avant de connecter un agent IA, vérifiez que Tolk peut joindre vos noeuds Cisco UC :

Ouvrez Outils → Test de connectivité produit.
Sélectionnez le produit (CUCM, IM & Presence, Unity Connection, téléphone IP ou terminal RoomOS), saisissez le FQDN ou l'adresse IP du noeud ou du terminal et, optionnellement, les identifiants API et SSH (OS admin) — ils ne servent qu'à ce test et ne sont jamais stockés.
Cliquez sur Lancer le test. Les contrôles sont listés dans l'ordre, du réseau jusqu'à l'application : DNS, TCP, TLS (certificat, chaîne vérifiée avec le magasin de confiance du produit, horloge), authentification, API et CLI SSH.

Outils — test de connectivité produit

Corrigez tout contrôle en échec (pare-feu, DNS, CA manquante dans le magasin de confiance, rôle du compte…) avant d'aller plus loin.

5.6 Utiliser des certificats signés par une CA (optionnel)¶

Tolk utilise deux certificats TLS indépendants, chacun généré automatiquement en auto-signé au premier démarrage et entièrement gérable depuis l'interface Web d'administration (page Paramètres globaux) :

Certificat du serveur MCP — présenté sur le port MCP ; c'est le certificat auquel vos agents IA se connectent.
Certificat de l'interface Web d'administration — présenté sur le port admin. Par défaut, il réutilise le certificat du serveur MCP (ADMIN_UI_TLS_REUSE_MCP_CERT='1'), il n'y a donc rien de séparé à gérer.

Pour remplacer un certificat auto-signé par un certificat signé par votre CA interne, suivez l'onglet correspondant ci-dessous. Le processus est identique dans les deux cas : vérifier le sujet → générer le CSR → le faire signer par votre CA → importer le .crt → Appliquer & redémarrer. Chaque service conserve une seule paire certificat/clé : le certificat signé par la CA importé remplace l'auto-signé dans le même fichier.

MCP Server CertificateWebadmin UI Certificate

Géré sur la page Paramètres globaux → onglet TLS / Crypto → section Certificat du serveur MCP (MCP_TLS_CERT_FILE, MCP_TLS_KEY_FILE, MCP_TLS_CSR_FILE).

Vérifier les champs du sujet. Le FQDN AUTH_ISSUER est utilisé pour le CN et le premier SAN du certificat (le port de l'URL est ignoré — un certificat est lié à un nom d'hôte, pas à un port) ; les autres hôtes non locaux de MCP_SERVER_SECURITY_ALLOWED_HOSTS et l'hôte de MCP_SERVER_PUBLIC_URL sont ajoutés en SAN secondaires. Les champs CERT_* (Country, State, Org, OU) complètent le reste du sujet.
Générer le CSR. Cliquez sur Générer le CSR… : un aperçu affiche le sujet (CN, O, OU, L, ST, C), la clé et la liste des SAN. Supprimez un SAN avec sa croix rouge ✕ ou saisissez-en un supplémentaire (nom d'hôte, joker *.domaine ou adresse IP) puis cliquez sur Ajouter — ces modifications ne s'appliquent qu'à ce CSR. Le CSR est signé avec la clé privée existante du serveur (la clé est préservée ; une nouvelle n'est générée que si aucune n'existe). Téléchargez le fichier .csr généré.
Faire signer par votre CA. Soumettez le CSR à votre CA interne et récupérez le certificat signé (.crt, format PEM). L'Extended Key Usage (EKU) requise est "Not Critical - TLS WWW Server Authentication".
Importer le certificat. De retour dans la section Certificat du serveur MCP, téléversez le .crt signé en tant que MCP_TLS_CERT_FILE. S'il correspond à la clé privée, le CSR désormais consommé est supprimé automatiquement.
Appliquer & redémarrer. L'import d'un certificat programme une modification nécessitant un redémarrage — cliquez sur Apply & restart (Appliquer & redémarrer) pour le charger. Avant le redémarrage, le contrôle Certificats TLS de la page vérifie pour chaque service que le certificat et la clé sont présents, valides, appariés et non expirés (avertissement si plus de 50 % de la durée de vie est écoulée, échec si le redémarrage échouerait).

Le certificat du port admin possède deux modes, tous deux configurés sur la page Paramètres globaux → onglet Admin UI → section TLS.

Réutiliser le certificat MCP — par défaut

Laissez ADMIN_UI_TLS_REUSE_MCP_CERT activé ('1'). L'interface d'administration présente le même certificat que le serveur MCP — y compris votre certificat signé par la CA une fois importé ci-dessus. Rien d'autre à faire. Cela fonctionne car les SAN du certificat sont liés au nom d'hôte, pas au port : le même certificat est valide sur les deux ports (tant que l'interface d'administration partage le nom d'hôte du serveur MCP).

Certificat dédié signé par une CA

À n'utiliser que si l'interface d'administration doit présenter un certificat différent (par ex. un nom d'hôte différent de celui du point de terminaison MCP).

Désactiver la réutilisation. Réglez ADMIN_UI_TLS_REUSE_MCP_CERT sur '0'. Tant que vous n'importez pas de certificat signé par une CA, l'interface d'administration génère son propre certificat auto-signé.
Vérifier les champs du sujet. Le CN de l'interface d'administration est l'hôte de AUTH_ISSUER ; ses SAN proviennent de ADMIN_UI_TLS_ALLOWED_HOSTS (laisser vide pour réutiliser MCP_SERVER_SECURITY_ALLOWED_HOSTS) plus l'hôte de MCP_SERVER_PUBLIC_URL, sans boucle locale ; les champs d'organisation réutilisent les paramètres partagés CERT_*.
Générer le CSR. Dans la section TLS, cliquez sur Générer le CSR… (même aperçu et même édition des SAN que pour le certificat MCP). Il est signé avec la clé privée propre à l'interface d'administration (préservée entre les régénérations). Téléchargez le .csr.
Signer & importer. Faites-le signer par votre CA. L'Extended Key Usage (EKU) requise est "Not Critical - TLS WWW Server Authentication". Puis téléversez le .crt obtenu dans la même section. Le CSR consommé est supprimé automatiquement lorsqu'il correspond à la clé.
Appliquer & redémarrer pour charger le nouveau certificat de l'interface d'administration.

Après le redémarrage, le serveur présente votre certificat signé par la CA au lieu du certificat auto-signé.

Pour revenir à un certificat auto-signé, utilisez Supprimer certificat + clé sur la page du certificat puis redémarrez.

Étape 6 — Connecter votre agent IA¶

6.1 Choisir le mode d'authentification¶

Avant de déclarer votre premier client, choisissez le mode d'authentification global AUTH_MODE : il détermine les identifiants délivrés aux clients et la façon dont les agents IA s'authentifient.

`AUTH_MODE`	Identifiants délivrés à chaque client	Adapté à
`jwt` (défaut)	Un token bearer JWT signé longue durée (`AUTH_TOKEN_EXPIRY_DAYS`, défaut 365 jours), placé en en-tête `Authorization` statique dans la configuration de l'agent	La configuration la plus simple — la plupart des agents IA
`oauth2`	Un `client_id` et un `client_secret` à usage unique ; l'agent obtient des tokens d'accès courte durée (`AUTH_OAUTH_TOKEN_EXPIRY_SECONDS`, défaut 1 heure) via OAuth 2.1 — authorization code + PKCE pour les IDE IA, client credentials pour les scripts	Une hygiène des identifiants plus stricte — agents compatibles OAuth, pipelines automatisés
`jwt+oauth2`	Hybride — chaque client déclare son propre mode (`jwt`, `oauth2` ou `jwt+oauth2`) à sa création	Environnements mixtes

Ouvrez Paramètres globaux → onglet Authentication → section Identité.
Cliquez sur Modifier sur AUTH_MODE, sélectionnez le mode puis cliquez sur Enregistrer.

Si vous conservez le mode jwt par défaut, il n'y a rien à modifier. En mode oauth2 ou jwt+oauth2, passez aussi en revue la section URIs de redirection OAuth2 du même onglet : AUTH_OAUTH_REDIRECT_URI_ENFORCEMENT='strict' avec une liste blanche AUTH_OAUTH_REDIRECT_URIS est recommandé en production (voir Setup).

Paramètres globaux — onglet Authentication, AUTH_MODE

La modification est mise en attente : elle est appliquée avec le nouveau client lors du Appliquer & redémarrer de l'étape 6.2 — un seul redémarrage suffit.

Choisir le mode avant de distribuer des identifiants

Changer AUTH_MODE alors que des clients existent invalide les identifiants déjà distribués : les tokens émis dans l'ancien mode sont refusés, et les nouveaux identifiants doivent être retransmis à chaque propriétaire de client. Un mode plus restrictif que celui d'un client est refusé : en jwt+oauth2, passez d'abord les clients dans le mode cible depuis la page Clients. Le passage en jwt+oauth2 conserve à chaque client existant son mode précédent.

6.2 Créer un client¶

Chaque agent IA s'authentifie en tant que client déclaré. Créez-en un depuis l'interface Web d'administration :

Ouvrez la page Clients et cliquez sur Ajouter un client.
Déclarez le client — nom, sujet (le claim JWT sub, ex. sub-<nom>-AAAAMMJJ) et profil RBAC ; en mode jwt+oauth2, également son mode d'authentification — puis cliquez sur Créer le client.
La modification est mise en attente. Cliquez sur Appliquer & redémarrer pour activer le nouveau client (et le AUTH_MODE choisi à l'étape 6.1).

Page Clients — ajout d'un client

Immuabilité du sujet

Le sujet est intégré dans chaque token émis pour le client : le modifier ultérieurement invalide les identifiants déjà distribués.

6.3 Récupérer les identifiants du client¶

Après le redémarrage, revenez sur la page Clients et cliquez sur Voir les identifiants pour votre client.

Les informations de connexion s'affichent, notamment :

Champ	Usage
URL du serveur	Le point de terminaison MCP, ex. `https://tolk.domain.com:8443/mcp/`
Client ID	Identifiant de client OAuth 2.1
Token JWT	Token bearer longue durée (mode JWT, défaut : 365 jours)
Secret client OAuth2	Secret du client (mode OAuth 2.1)

Informations de connexion du client

Affiché une seule fois

Ces identifiants ne sont affichés qu'une seule fois — copiez-les maintenant et transmettez-les de façon sécurisée au propriétaire du client. Ils ne peuvent plus être réaffichés ensuite ; en cas de perte, utilisez Réinitialiser les tokens sur la page Clients pour en générer de nouveaux.

6.4 Configurer votre premier agent IA¶

Ajoutez le serveur MCP au fichier de configuration de votre agent. Les exemples ci-dessous concernent le mode jwt, avec le token récupéré ci-dessus.

Mode OAuth 2.1

En mode oauth2, déclarez le serveur sans l'en-tête Authorization : un agent compatible OAuth découvre lui-même le serveur d'autorisation et ouvre la page de connexion Tolk dans votre navigateur, où vous saisissez le client_id et le client_secret (voir la FAQ pour un exemple OpenCode). Un agent supportant le type client credentials peut aussi lire le client_id et le client_secret dans sa configuration et obtenir ses jetons sans navigateur (voir Mode OAuth 2.1).

Claude DesktopOpencodeCursorPersonnalisé / Autre

Éditez claude_desktop_config.json :

{
  "mcpServers": {
    "tolk-vip-mcp-server-jwt": {
      "command": "/home/user/.nvm/versions/node/vxx.xx.x/bin/npx",
      "args": [
        "mcp-remote@latest",
        "https://tolk.domain.com:8443/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <paste-token-here>",
        "NODE_EXTRA_CA_CERTS": "/home/user/.config/Claude/ROOT_CA.cer"
      }
    }
  }
}

Éditez opencode.json :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tolk-vip-mcp-server": {
      "type": "remote",
      "url": "https://tolk.domain.com:8443/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer <paste-token-here>"
      }
    }
  }
}

Éditez ~/.cursor/mcp.json (ou le fichier .cursor/mcp.json au niveau du projet) :

{
  "mcpServers": {
    "tolk-cisco-uc": {
      "url": "https://tolk.domain.com:8443/mcp",
      "headers": {
        "Authorization": "Bearer <paste-token-here>"
      }
    }
  }
}

Tout client compatible MCP utilisant le transport Streamable HTTP :

Endpoint : https://tolk.domain.com:8443/mcp/
Transport: streamable-http
Auth     : Authorization: Bearer <paste-token-here>

6.5 Faire confiance au certificat du serveur¶

Votre agent IA doit faire confiance au certificat TLS du serveur MCP — qu'il s'agisse du certificat auto-signé généré automatiquement ou d'un certificat signé par une CA déployé à l'étape 5.6. Importez le certificat dans le magasin de confiance de votre client ou configurez le client pour l'accepter.

6.6 Vérifier la connexion¶

Demandez à votre agent IA de vérifier la connectivité au serveur MCP et de lister les outils disponibles.

Vous devriez voir le statut du serveur MCP tel que MCP server is healthy and ready et la liste des outils (common_, infra_ et {products}_).

Vérifier la connectivité au serveur MCP tolk-cisco-uc, et lister tous les outils disponibles.

Et ensuite ?¶

Guide	Ce que vous y trouverez
Setup	Configuration avancée : référence complète des paramètres, configuration TLS, durcissement du transport, journalisation d'audit, modes d'authentification, gestion des clients, profils RBAC
Operations	Opérations courantes : démarrage/arrêt, supervision, sauvegarde, mise à niveau, rotation des clés