Configuration déclarative
La configuration déclarative décrit la configuration des royaumes, et la configuration globale, dans des fichiers, un objet par fichier, que l’on range dans git, relit en revue et promeut d’un environnement à l’autre. Le cycle est celui des outils d’infrastructure :
- export : les objets d’un royaume sont écrits en fichiers ;
- plan : les fichiers sont comparés au serveur, sans rien écrire ;
- apply : les écarts sont appliqués au serveur.
Un même moteur sert trois points d’entrée :
| Point d’entrée | Usage |
|---|---|
La commande tosiam-config | Poste d’un exploitant, intégration continue |
| L’import au démarrage | Image TOSIAM et chart Helm : la configuration est appliquée quand le serveur démarre |
| L’écran « Export / import » de la console | Exporter, prévisualiser et appliquer depuis un navigateur |
Le moteur ne passe que par l’API REST d’administration (/api) : les écritures subissent les mêmes contrôles que celles de la console (droits, validation, masquage des secrets).
Objets pris en charge#
Type (kind) | Répertoire | Fichiers |
|---|---|---|
DataStore | datastores/ | <nom>.yaml |
Script | scripts/ | <nom>.yaml et le code, <nom>.js ou <nom>.groovy |
SubGraph | subgraphs/ | <nom>.json |
AuthGraph | authgraphs/ | <nom>.json |
RealmService | services/ | <service>.yaml |
OAuth2Client | agents/OAuth2Client/ | <id>.yaml |
WebAgent | agents/WebAgent/ | <id>.yaml |
ResourceType | resourcetypes/ | <nom>.yaml |
PolicySet | policysets/ | <nom>.yaml |
Policy | policies/<ensemble de politiques>/ | <nom>.yaml |
SamlProvider | federation/providers/ | <entityID>.yaml : métadonnées standard et étendues |
CircleOfTrust | federation/circlesoftrust/ | <nom>.yaml |
RestSTS | sts/rest/ | <instance>.yaml |
Le royaume lui-même est décrit par son fichier realm.yaml : voir Le royaume.
La configuration globale, dans le répertoire global/ (à partir de la 3.38.0 également) :
Type (kind) | Répertoire | Fichiers |
|---|---|---|
GlobalService | global/services/ | <service>.yaml (federation/common devient federation_common.yaml) |
GlobalServiceInstance | global/instances/ | <service>_<type>_<instance>.yaml |
ServerDefault | global/server-default/ | <onglet>.yaml : general, security, session, sdk, cts, uma, advanced |
Voir La configuration globale.
Voir aussi La fédération SAML et Le STS.
Le répertoire de configuration#
tosiam-config/
├── tosiam.yaml # version du format, périmètre géré
├── global/ # la configuration globale
│ ├── services/session.yaml
│ ├── instances/RadiusServerService_radiusClient_vpn.yaml
│ └── server-default/advanced.yaml
└── realms/
├── _root/ # le royaume racine
│ ├── realm.yaml # chemin, statut et alias DNS du royaume
│ ├── scripts/
│ │ ├── decision.yaml
│ │ └── decision.js
│ ├── authgraphs/login.json
│ └── agents/OAuth2Client/app1.yaml
└── clients__mobile/ # le royaume /clients/mobile
└── ...- Un répertoire par royaume sous
realms/, à plat :_rootpour le royaume racine, sinon le chemin du royaume dont les/sont remplacés par__. Le chemin écrit dansrealm.yaml(path: /clients/mobile) l’emporte sur le nom du répertoire, qui peut donc être renommé. tosiam.yamlporte la version du format (formatVersion: 1) et, au besoin, le périmètre géré.global/est facultatif : il porte la configuration globale.
La configuration globale#
Le répertoire global/ décrit ce qui ne dépend d’aucun royaume. Il est traité par --global, et avant les royaumes par --all-realms, donc aussi par l’import au démarrage. Il demande un administrateur global.
- Services globaux (
GlobalService) : leurs attributs globaux et les valeurs par défaut de leurs attributs de royaume. Un service existe sur tous les serveurs : il est mis à jour, jamais créé ni supprimé. Un fichier d’un service que le serveur ne connaît pas est un problème du plan. - Sous-instances (
GlobalServiceInstance, nom<service>/<type>/<instance>, par exempleRadiusServerService/radiusClient/vpn) : clients RADIUS, configurations CORS, applications du tableau de bord, gestionnaires d’audit (audit/CSV/Global CSV Handler). Elles sont créées, modifiées et, dans le périmètre géré, supprimées. Les contextes de script (scripting/contexts/…) sont ceux du produit : ils sont modifiés, jamais créés ni supprimés. - Configuration serveur par défaut (
ServerDefault, un fichier par onglet) : les valeurs héritées par tous les serveurs, mises à jour seulement. Une propriété absente du fichier n’est pas comparée, et n’est pas retirée du serveur : l’API n’écrit que les propriétés qu’elle reçoit. Les mots de passe (CTS, CRL, magasins UMA) sont des secrets comme les autres. Les propriétés de l’installation ne sont jamais exportées : clé de chiffrement, clé des jetons CSRF, version et révision du produit.
Les fiches de chaque serveur, les sites et les instances de serveur ne sont pas pris en charge : ils décrivent l’environnement (noms d’hôte, URL) plutôt que la configuration à promouvoir.
La fédération SAML#
Une entité SAML (SamlProvider, hébergée ou distante) est décrite par ses métadonnées standard et étendues, celles qu’échangent ssoadm export-entity et import-entity. Son nom est son entityID :
kind: SamlProvider
apiVersion: config.tosiam.io/v1
metadata:
name: https://idp.example.com
spec:
metadata: |
<ns4:EntityDescriptor entityID="https://idp.example.com" …>
extendedMetadata: |
<ns7:EntityConfig entityID="https://idp.example.com" hosted="true">
<ns7:IDPSSOConfig metaAlias="/idp">
…
secrets:
IDPSSOConfig:
signingCertKeyPass: ${env:IDP_KEY_PASS}
basicAuthPassword: "${secret:…}"
saeAppSecretList: "${secret:…}"- Les documents sont comparés une fois réindentés : leur mise en page n’est pas un écart. Ils peuvent contenir des références
${env:…}(une URL, par exemple). - Les secrets de la configuration étendue d’une entité hébergée (
signingCertKeyPass,basicAuthPassword,saeAppSecretList) ne sont jamais exportés ni dans le XML : ils sont donnés soussecrets, comme les autres secrets. Un secret non fourni garde sa valeur sur le serveur. - L’appartenance d’une entité aux cercles de confiance (
CircleOfTrust) est décrite par les cercles (trustedProviders,<entityID>|saml2), appliqués après les entités. Elle n’est pas écrite dans la configuration étendue de l’entité. - Le
metaAliasd’une entité hébergée contient le chemin de son royaume (/clients/idp) : pour copier une entité vers un autre royaume, changez-le. - Dans le périmètre géré, une entité ou un cercle sans fichier est supprimé.
Le STS#
Une instance STS (RestSTS) est décrite par sa configuration, telle que la renvoie l’API : deployment-config, supported-token-transforms, saml2-config, oidc-id-token-config… Elle est publiée à sa création.
- Le royaume et l’identifiant de l’instance (
deployment-realm,deployment-url-element) ne sont pas dans le fichier : ce sont ceux du répertoire du royaume et du nom du fichier. Copiée dans un autre royaume, l’instance y est publiée telle quelle. - Les secrets (mots de passe des keystores et des clés SAML2 et OIDC, client secret OIDC) ne sont jamais exportés : ils sont écrits sous forme de références, à fournir par
${env:…}ou${file:…}. Non fournis, ils gardent leur valeur sur le serveur. La création d’une instance exige les secrets que sa configuration rend obligatoires (le client secret d’une signature HMAC, les mots de passe du keystore et de la clé d’une signature RSA) : le serveur la refuse sinon (400). - Dans le périmètre géré, une instance sans fichier est supprimée.
Le royaume#
realm.yaml décrit le royaume lui-même :
path: /clients/mobile
active: true
aliases:
- mobile.example.com- Un royaume absent du serveur est créé par l’application, avant ses objets : actif et sans alias, sauf si
realm.yamldit autre chose. Son royaume parent doit exister, ou être appliqué avant lui (--all-realmsapplique les parents d’abord). La création d’un royaume demande un administrateur global. - Un royaume présent est mis à jour quand
activeoualiasesdiffère de ce que déclarerealm.yaml. - Une clé absente de
realm.yamln’est pas gérée : le serveur garde sa valeur. Unrealm.yamlqui n’a quepathne change ni le statut ni les alias. - Un royaume n’est jamais supprimé, même avec
--prune=managed.
Un objet par fichier#
Les fichiers sont écrits en YAML et peuvent être lus en YAML ou en JSON. Chacun porte kind, apiVersion et metadata.name ; le contenu est sous spec, avec les noms d’attributs de l’API REST :
apiVersion: config.tosiam.io/v1
kind: OAuth2Client
metadata:
name: app1
spec:
coreOAuth2ClientConfig:
com.forgerock.openam.oauth2provider.clientType:
inherited: false
value: Confidential
com.forgerock.openam.oauth2provider.redirectionURIs:
inherited: false
value:
- ${env:APP1_REDIRECT_URI}
userpassword: ${file:/run/secrets/tosiam-config/app1-secret}Particularités :
- Royaume : il n’est pas écrit dans les fichiers d’objets. C’est le répertoire qui le donne : copier
realms/_rootenrealms/recettepromeut la configuration du royaume racine vers le royaume/recette. - Identité : un objet est identifié par son nom, sauf les scripts et les types de ressource, identifiés par leur identifiant (
metadata.id). À la création, cet identifiant est repris : un même script a le même identifiant sur tous les serveurs. Un objet à créer dont le nom est déjà pris sur le serveur sous un autre identifiant est un conflit, signalé avant toute écriture. - Graphes : un graphe est écrit dans l’enveloppe JSON d’export de la console, un graphe par fichier. Un fichier exporté par la CLI s’importe dans l’éditeur de graphes de la console, et inversement, à une exception près : l’éditeur refuse encore un sous-graphe dont un paramètre a une valeur par défaut.
- Scripts : le code est dans un fichier à part, nommé par l’attribut
sourcedu.yaml. - Sortie stable : clés triées, listes sans ordre triées, aucun horodatage. Deux exports d’une même configuration donnent les mêmes fichiers, et un diff git ne montre que les vrais changements.
- Scripts globaux : ceux du produit et ceux créés en global sont listés dans chaque royaume, mais ne sont ni exportés, ni comparés, ni supprimés.
Secrets et valeurs propres à un environnement#
L’API ne renvoie jamais un secret. À l’export, chaque secret est remplacé par une référence ${secret:…} qui indique où il se trouvait :
userpassword: ${secret:realms/_root/agents/OAuth2Client/app1/coreOAuth2ClientConfig/userpassword}Avant l’application, remplacez-la par une référence qui fournit la valeur. Deux sortes de références sont résolues, dans toute valeur, pas seulement dans les secrets :
| Référence | Valeur |
|---|---|
${env:NOM} | La variable d’environnement NOM |
${file:/chemin} | Le contenu du fichier, sans ses fins de ligne finales (un Secret Kubernetes monté, un fichier de la CI) |
Une valeur peut contenir plusieurs références au milieu d’un texte : https://${env:HOST}/callback. Seuls les préfixes env:, file: et secret: font une référence : ${org}, par exemple un paramètre de sous-graphe, est laissé tel quel. Dans le code d’un script, rien n’est remplacé.
Quand une référence ne peut pas être résolue (${secret:…}, variable absente, fichier absent) :
- sur un objet modifié, un secret non fourni est conservé par le serveur ; toute autre valeur est un problème qui empêche l’application ;
- sur un objet créé, un secret déclaré obligatoire par le schéma du serveur (le mot de passe d’un client confidentiel, celui de la connexion d’un data store) doit être fourni ; un secret facultatif non fourni est omis.
Le serveur ne renvoyant pas les secrets, le plan ne sait pas si un secret fourni diffère de la valeur en place : un secret fourni est toujours réécrit, et annoncé comme tel (secret rewritten).
Suppressions et périmètre géré#
Par défaut, rien n’est supprimé : un objet présent sur le serveur et absent des fichiers est seulement signalé (!, « sur le serveur seulement »).
Pour que les fichiers fassent foi, déclarez dans tosiam.yaml le périmètre géré, puis appliquez avec --prune=managed :
formatVersion: 1
managed:
- realm: /
kinds: [OAuth2Client, AuthGraph, Script]
exclude:
- kind: Script
name: "Legacy *"
- realm: /clients
kinds: ["*"]
- global: true # la configuration globale (global/)
kinds: [GlobalServiceInstance]Un objet est supprimé s’il est dans le périmètre (royaume et type déclarés, nom non exclu ; * est un joker) et n’a pas de fichier. Le périmètre est versionné avec le reste : il n’y a ni fichier d’état local, ni marqueur sur les objets du serveur.
Certains objets ne sont jamais supprimés, même dans le périmètre : le royaume lui-même, les services de royaume, les scripts globaux, le type de ressource URL, l’ensemble de politiques iPlanetAMWebAgentService, les services globaux, les contextes de script et les onglets de la configuration serveur par défaut.
Ordre d’application et reprise#
La configuration globale est appliquée avant les royaumes : services globaux, sous-instances, configuration serveur par défaut. Dans un royaume, les objets sont créés et modifiés dans l’ordre de leurs dépendances : le royaume, les data stores, scripts, sous-graphes, graphes, services, clients OAuth2, agents web, types de ressource, ensembles de politiques, politiques, entités SAML, cercles de confiance, instances STS. Les suppressions suivent l’ordre inverse.
Il n’y a pas de transaction : à la première erreur, l’application s’arrête, et ce qui a été appliqué le reste. Comme le plan est recalculé à chaque fois, une nouvelle application reprend là où l’autre s’est arrêtée.
Compatibilité des versions#
Une CLI de version X.Y accepte un serveur X.Y ou X.(Y-1), pour couvrir la promotion pendant une montée de version, et refuse les autres. Un fichier tosiam.yaml d’un format plus récent que celui de la CLI est refusé.