La commande tosiam-config
Sur cette page
tosiam-config est un jar autonome qui parle à un serveur TOSIAM par son API REST. Il ne demande ni les bibliothèques du serveur, ni un accès au config store : il fonctionne depuis un poste ou une CI, contre un serveur distant.
Où trouver la commande#
-
Distribution :
tosiam/tosiam-config.jardans le zipTosiAM-<version>.zipde la page de téléchargement. Il demande Java 17 ou plus récent :java -jar tosiam-config.jar --help -
Image TOSIAM : la commande
tosiam-configest dans l’image, voir Import au démarrage.
Utilisez la commande de la version du serveur : une CLI X.Y accepte un serveur X.Y ou X.(Y-1) et refuse les autres.
S’authentifier#
La CLI ouvre une session avec un compte d’administration, amadmin par défaut, du royaume racine ou du royaume donné par --login-realm. Le mot de passe n’est jamais passé en argument :
| Réglage | Option | Variable d’environnement |
|---|---|---|
| Compte | --username <nom> | TOSIAM_CONFIG_USERNAME (défaut amadmin) |
| Royaume du compte | --login-realm <royaume> | TOSIAM_CONFIG_LOGIN_REALM (défaut /) |
| Mot de passe | --password-file <fichier> | TOSIAM_CONFIG_PASSWORD |
| Autorité de certification du serveur | --ca-cert <fichier.pem> | — (défaut : celles de la JVM) |
L’URL du serveur comprend son contexte : --server https://am.example.com/tosiam. Le serveur refuse un hôte qui n’est pas un nom complet : localhost et 127.0.0.1 ne conviennent pas.
Avec un client OAuth2#
À la place d’un compte et de son mot de passe, la CLI peut s’authentifier par un client OAuth2 confidentiel, sans aucun secret partagé avec le serveur. Elle obtient un jeton par client_credentials, en s’authentifiant par sa clé (private_key_jwt) ou par son certificat (mTLS). Elle échange ensuite ce jeton contre la session d’un compte de service, dans un graphe qui contient le nœud ClientCredentialsSessionNode. Le reste ne change pas : délégation, droits du compte, audit de connexion. Voir l’ADR-0005 pour la revue de sécurité.
java -jar tosiam-config.jar plan --server https://am.example.com/tosiam --dir ./tosiam-config --realm /clients \
--login-realm /clients --client-id ci-clients --client-assertion-key ci-clients.pk8.pem --auth-graph ci| Option | Rôle |
|---|---|
--client-id <id> | Le client, dans le royaume --login-realm |
--client-assertion-key <fichier> | Sa clé privée PKCS#8 non chiffrée (BEGIN PRIVATE KEY), RSA (RS256) ou EC P-256 (ES256) : private_key_jwt |
--client-cert <fichier> et --client-key <fichier> | Ou son certificat et sa clé, présentés dans la poignée de main TLS (tls_client_auth, self_signed_tls_client_auth) |
--auth-graph <graphe> ou --auth-chain <chaîne> | Le graphe qui ouvre la session, ou la chaîne qui le contient (pour la chaîne des administrateurs obligatoire) |
--scope <portée> | La portée demandée, tosiam:config par défaut |
Mise en place, dans le royaume du client :
- le fournisseur OAuth2, avec la portée
tosiam:configparmi ses portées ; - le client : confidentiel, grant
client_credentials, portéetosiam:config, méthodeprivate_key_jwt(clé publique en certificat ou en JWKS) ou mTLS ; - le compte de service, un utilisateur du royaume, avec les privilèges de délégation nécessaires (
RealmAdminpour un royaume) ; - un graphe
ClientCredentialsSessionNode→SuccessNode, avec le client dansclientset le compte dansserviceAccount, et son instance de module (et une chaîne, au besoin).
Exporter#
export TOSIAM_CONFIG_PASSWORD='…'
java -jar tosiam-config.jar export --server https://am.example.com/tosiam \
--dir ./tosiam-config --realm /clientsDataStore: 1 exported
Script: 3 exported
SubGraph: 0 exported
AuthGraph: 2 exported
...
Export written in tosiam-config/realms/clients
The secrets are written as ${secret:…}: provide them by ${env:…} or ${file:…}.L’export remplace les fichiers du royaume par ceux du serveur. --kinds Script,AuthGraph limite l’export (et le plan) à certains types. Remplacez ensuite les références ${secret:…} par des références ${env:…} ou ${file:…} : voir Secrets.
Valider les fichiers#
validate vérifie le répertoire sans serveur : c’est l’étape à placer en tête d’une CI, avant tout plan.
java -jar tosiam-config.jar validate --dir ./tosiam-configwarning: realm /clients: OAuth2Client app1: the secret coreOAuth2ClientConfig/userpassword is not given (${secret:…}): an update keeps the value of the server, a creation that needs it is refused by the plan
error: realms/clients/scripts/decision.yaml: the source decision.js is not found beside the file
error: realm /clients: AuthGraph login is declared twice
error: realm /clients: OAuth2Client app2: ${env:APP2_SECRET} at coreOAuth2ClientConfig/userpassword: the variable APP2_SECRET is not defined
Invalid: 3 error(s), 1 warning(s).Sans option, toute l’arborescence est vérifiée : global/ et chaque royaume de realms/. --realm ou --global limite la vérification, --kinds aussi.
| Contrôle | Erreur |
|---|---|
tosiam.yaml | absent, formatVersion absent ou plus récent que la commande |
Périmètre géré (managed:) | entrée sans realm ni global: true, type inconnu ou d’une autre portée, Realm (un royaume n’est jamais supprimé) ; un royaume sans répertoire est un avertissement |
| Royaumes | deux répertoires pour le même royaume, realm.yaml illisible (path, active, aliases) |
| Format des fichiers | YAML ou JSON illisible, kind, apiVersion, metadata.name ; enveloppe d’export pour un graphe ; metadata.id et source à côté du fichier pour un script |
| Doublons | deux objets d’un type de même nom ou de même identifiant |
| Références | ${env:NOM} dont la variable n’est pas définie, ${file:/chemin} dont le fichier n’existe pas |
Un ${secret:…} laissé par l’export n’est qu’un avertissement : une mise à jour garde la valeur du serveur. Un fichier ou un répertoire qu’aucun type ne lit (un .yml, un répertoire script/ mal nommé) est aussi un avertissement.
Avec --server (et un compte), validate lit en plus les schémas du serveur, rien d’autre, et n’écrit rien. Il vérifie alors les fichiers comme pour une installation neuve : un secret que le schéma déclare obligatoire (required) et que les fichiers ne donnent pas est une erreur, comme une référence placée hors d’un secret.
Calculer le plan#
java -jar tosiam-config.jar plan --server https://am.example.com/tosiam --dir ./tosiam-config --realm /clients+ Script decision (6f0c…)
~ AuthGraph login
steps/password/config/maxAttempts: 3 → 5
~ OAuth2Client app1
coreOAuth2ClientConfig/userpassword: secret rewritten
! Script legacy-check (91aa…) (on the server, not in the files)
Plan: 1 to create, 2 to update, 0 to delete, 1 on the server only.| Symbole | Signification |
|---|---|
+ | Créé : dans les fichiers, pas sur le serveur |
~ | Modifié, avec les chemins qui diffèrent (valeur du serveur → valeur des fichiers) |
- | Supprimé, avec --prune=managed seulement |
! | Sur le serveur seulement : jamais supprimé hors du périmètre géré |
Le plan n’écrit rien. Il se termine par la liste des problèmes qui empêchent d’appliquer, par exemple un secret obligatoire non fourni ou un conflit de nom.
Appliquer#
java -jar tosiam-config.jar apply --server https://am.example.com/tosiam --dir ./tosiam-config --realm /clientsL’application recalcule le plan, refuse s’il a des problèmes, puis applique les créations et les modifications dans l’ordre des dépendances, et les suppressions en dernier. Elle affiche ce qui a été appliqué ; sur une erreur, ce qui a été appliqué avant elle.
Appliquer exactement le plan relu#
En CI, on relit le plan avant de l’appliquer. plan --out l’enregistre avec l’empreinte de l’état du serveur ; apply --plan applique exactement ce plan, et refuse si le serveur ou les fichiers ont changé depuis :
java -jar tosiam-config.jar plan --server "$URL" --dir ./tosiam-config --realm /clients --out plan.json
# revue du plan…
java -jar tosiam-config.jar apply --server "$URL" --dir ./tosiam-config --realm /clients --plan plan.jsonLe fichier plan.json ne contient que les noms des objets et des empreintes : celle de l’état du serveur, et celle de chaque objet d’un changement (son état sur le serveur et dans les fichiers, ses secrets exclus). Aucune valeur de la configuration n’y figure.
Conflits#
Un conflit est un objet qui ne peut pas être appliqué tel quel :
- un objet à créer dont le nom est déjà pris sur le serveur sous un autre identifiant (un script recréé à la main, un type de ressource) ;
- un service global ou un onglet de configuration serveur que le serveur ne connaît pas (une autre version) ;
- avec
--plan, un objet qui a changé sur le serveur ou dans les fichiers depuis le plan relu.
--on-conflict choisit la conduite :
| Valeur | Effet |
|---|---|
fail (défaut) | L’application est refusée avant toute écriture |
skip | L’objet en conflit est laissé de côté et signalé, les autres sont appliqués |
java -jar tosiam-config.jar apply --server "$URL" --dir ./tosiam-config --realm /clients --on-conflict skip~ AuthGraph login
Applied: 1 change(s).
Skipped (--on-conflict=skip):
+ Script decision (6f0c…): Script decision (6f0c…): the server has a script of this name under another id (91aa…)Avec --plan, skip applique les seuls objets dont l’empreinte n’a pas changé depuis la revue ; un changement apparu depuis n’est pas appliqué (not in the plan). plan --on-conflict skip annonce les objets qui seront laissés de côté, sans les compter comme des problèmes.
Un objet qui diffère simplement du serveur n’est pas un conflit : il est mis à jour, les fichiers décrivant l’état voulu.
La configuration globale#
--global remplace --realm : la commande traite le répertoire global/ (services globaux, sous-instances, configuration serveur par défaut), avec un administrateur global.
java -jar tosiam-config.jar export --global --server https://am.example.com/tosiam --dir ./tosiam-config
java -jar tosiam-config.jar plan --global --server https://am.example.com/tosiam --dir ./tosiam-configTous les royaumes#
--all-realms calcule le plan ou applique la configuration globale, quand le répertoire global/ existe, puis chaque royaume du répertoire realms/, les royaumes parents avant leurs sous-royaumes. Avant la première écriture, l’application calcule le plan de tous les royaumes : un problème ou un droit manquant dans le dernier royaume empêche d’appliquer le premier. Elle s’arrête ensuite au premier royaume en erreur. Cette option ne se combine pas avec --realm, --global, --out ni --plan.
Supprimer#
--prune=managed supprime les objets du périmètre déclaré dans tosiam.yaml qui n’ont pas de fichier ; le plan les annonce par -. Sans cette option (--prune=none), rien n’est supprimé.
Droits du compte#
L’application vérifie les droits du compte avant la première écriture, et nomme le type d’objet refusé :
Error: OAuth2Client (realm /clients): the account has no right on this type of object: GET /api/agent-types/OAuth2Client/schema: HTTP 403 (Forbidden: global-admin role required.)| Fichiers | Compte nécessaire |
|---|---|
| Les objets d’un royaume : data stores, scripts, graphes, services, clients OAuth2, agents web, politiques, entités SAML, cercles de confiance, STS | Administrateur de ce royaume, ou administrateur global |
| Un royaume absent du serveur, à créer | Administrateur global |
global/ | Administrateur global |
Un administrateur de royaume lit les types et les schémas des data stores, des agents et des cercles de confiance, communs à tous les royaumes et sans secret, mais rien de la configuration globale ni d’un autre royaume. Avant la version 3.38.0, ces schémas lui étaient refusés : il ne gérait ni les data stores, ni les agents, ni les cercles de confiance de son royaume.
Options#
| Option | Commandes | Rôle |
|---|---|---|
--server <url> | toutes | URL du serveur, avec son contexte ; facultatif pour validate (lecture des schémas) |
--dir <répertoire> | toutes | Répertoire de la configuration |
--realm <royaume> | toutes | Royaume, / par défaut |
--global | toutes | La configuration globale (global/) au lieu d’un royaume |
--all-realms | plan, apply | global/ s’il existe, puis chaque royaume du répertoire realms/ |
--kinds <k1,k2> | toutes | Types d’objets, tous par défaut |
--out <fichier> | plan | Enregistre le plan |
--plan <fichier> | apply | Applique le plan enregistré |
--prune <none|managed> | plan, apply | Suppression des objets du périmètre géré absents des fichiers |
--on-conflict <fail|skip> | plan, apply | Conduite sur un conflit, fail par défaut |
--username, --login-realm, --password-file, --ca-cert | toutes | Voir S’authentifier |
--client-id, --client-assertion-key, --client-cert, --client-key, --auth-graph, --auth-chain, --scope | toutes | Voir Avec un client OAuth2 |
Codes de retour#
| Code | Signification |
|---|---|
0 | Fait, aucun écart, ou fichiers valides |
2 | Le plan a des écarts |
1 | Erreur, ou problème qui empêche d’appliquer |
64 | Mauvais usage de la commande |
Le code 2 permet à une CI de détecter une dérive : un plan planifié qui sort en 2 signale une modification faite à la main sur le serveur.
Exemple d’intégration continue#
Les fichiers sont dans git, le mot de passe du compte de service et les secrets dans les variables protégées de la CI :
#!/bin/sh
set -eu
URL=https://recette.example.com/tosiam
CLI="java -jar tosiam-config.jar"
# les références ${env:APP1_SECRET}… des fichiers sont lues dans l'environnement de la CI
# étape « validate » (sur chaque demande de fusion) : sans serveur
$CLI validate --dir tosiam-config
# étape « plan » (sur chaque demande de fusion) : le plan est publié pour la revue
status=0
$CLI plan --server "$URL" --dir tosiam-config --realm /clients --out plan.json || status=$?
# 0 : aucun écart, 2 : écarts à relire ; tout autre code est une erreur
[ "$status" -eq 0 ] || [ "$status" -eq 2 ] || exit "$status"
# étape « apply » (après fusion, sur validation) : exactement le plan relu
$CLI apply --server "$URL" --dir tosiam-config --realm /clients --plan plan.jsonMis à jour le