Le schéma est la partie d’un système d’autorisation qui change le moins souvent et dont les changements provoquent le plus de défaillances. Dans l’article, il s’agit de la configuration d’espace de noms : « A namespace configuration specifies its relations as well as its storage parameters » (une configuration d’espace de noms spécifie ses relations ainsi que ses paramètres de stockage) (§2.3). Chez Google, il y avait « more than 1,500 namespaces » (plus de 1,500 espaces de noms), et leurs fichiers de configuration « range from tens of lines to thousands of lines, with the median near 500 lines » (comptent de quelques dizaines à plusieurs milliers de lignes, avec une médiane proche de 500 lignes) (§4). Cette page traite trois points : comment l’article empêche une modification de configuration de couper une requête en deux, comment les produits actuels obligent à supprimer une relation par étapes, et comment tester un modèle avant sa mise en production.
Les configurations de relations elles-mêmes (_this, computed_userset, tuple_to_userset) sont expliquées sur la page Tuples de relation et usersets. Cette page porte sur leur modification.
Comment l’article versionne les configurations d’espaces de noms
Les configurations résident dans leur propre base de données Spanner : « There is one database to store relation tuples for each client namespace, one database to hold all namespace configurations, and one changelog database shared across all namespaces » (il existe une base de données stockant les tuples de relation pour chaque espace de noms client, une base de données contenant toutes les configurations d’espaces de noms, et une base de données de journal des modifications partagée par tous les espaces de noms) (§3). La base de données des configurations est constituée d’une table et d’un journal :
Chaque version de configuration possède donc un horodatage de validation, et chaque serveur détient une certaine plage de versions. Le danger est celui d’une requête qui se répartit sur plusieurs serveurs (voir Architecture) : si le serveur qui la reçoit a déjà chargé une nouvelle configuration et que le serveur auquel il délègue ne l’a pas encore fait, les deux moitiés d’un même Check seraient évaluées selon des règles différentes. L’article exclut ce cas : « Zanzibar chooses a single snapshot timestamp for config metadata when evaluating each client request. All aclservers in a cluster use that same timestamp for the same request, including for any subrequests that fan out from the original client request » (Zanzibar choisit un unique horodatage d’instantané pour les métadonnées de configuration lors de l’évaluation de chaque requête client. Tous les aclservers d’un cluster utilisent ce même horodatage pour une même requête, y compris pour toutes les sous-requêtes issues de la requête client d’origine) (§3.2.2).
Quel horodatage une requête peut-elle utiliser lorsque les serveurs d’un cluster ont chargé des versions de configuration différentes ?
Remarquez que la nouvelle configuration n’est pas utilisée dès sa validation. Elle devient utilisable lorsque tous les serveurs du cluster peuvent la servir. Selon les termes de l’article, « each server in a cluster may have access to a different range of config timestamps due to restarts or network latency. Zanzibar must pick a timestamp that is available across all of them. To facilitate this, a monitoring job tracks the timestamp range available to every server and aggregates them, reporting a globally available range to every other server. On each incoming request the server picks a time from this range, ensuring that all servers can continue serving even if they are no longer able to read from the config storage » (chaque serveur d’un cluster peut avoir accès à une plage différente d’horodatages de configuration, en raison de redémarrages ou de la latence du réseau. Zanzibar doit choisir un horodatage disponible sur l’ensemble d’entre eux. Pour faciliter cela, une tâche de surveillance suit la plage d’horodatages disponible sur chaque serveur et les agrège, en communiquant à chacun des autres serveurs une plage disponible globalement. Pour chaque requête entrante, le serveur choisit un instant dans cette plage, garantissant ainsi que tous les serveurs peuvent continuer à servir même s’ils ne sont plus en mesure de lire le stockage des configurations) (§3.2.2).
L’article s’arrête là. Il ne dit pas comment un client migre ses tuples lorsqu’il supprime une relation, si une écriture de configuration est contrôlée par rapport aux tuples existants, ni comment l’horodatage de configuration se rapporte à l’instantané de tuples choisi pour la même requête. Il indique seulement que ⟨namespace⟩ et ⟨relation⟩ « are predefined in client configurations » (sont prédéfinis dans les configurations des clients) (§2.1), et qu’une relation fait partie de la clé primaire de chaque tuple (§2.1, §3.1.1). Le reste de cette page porte sur la manière dont les systèmes open source comblent cette lacune.
Les versions de schéma dans deux produits
Les deux produits les mieux documentés ont fait des choix différents.
- SpiceDB a un seul schéma courant par déploiement, remplacé au moyen de
WriteSchema. La documentation d’AuthZed indique que SpiceDB « processes all calls to the WriteSchema in a safe manner: it is not possible to break the type safety of a schema » (traite tous les appels à WriteSchema de manière sûre : il n’est pas possible de rompre la sûreté de typage d’un schéma), ce qui signifie qu’« it is not possible to accidentally remove a relation that is still referenced by one or more relationships » (il n’est pas possible de supprimer accidentellement une relation encore référencée par une ou plusieurs relations stockées) (migrating a schema). Un billet d’AuthZed de 2022 ajoute que les écritures de schéma sont entièrement cohérentes, si bien que les écritures de relations postérieures à une écriture de schéma sont évaluées selon le nouveau schéma (online schema migrations). - OpenFGA conserve toutes les versions. « Authorization Models in OpenFGA are immutable, they are created once and then can no longer be deleted or modified. Each time you write an authorization model, a new version is created. » (Les modèles d’autorisation d’OpenFGA sont immuables : ils sont créés une fois et ne peuvent ensuite plus être supprimés ni modifiés. Chaque fois que vous écrivez un modèle d’autorisation, une nouvelle version est créée.) Les requêtes peuvent désigner un
authorization_model_id; sans celui-ci, « OpenFGA will use the last created Authorization Model for that store » (OpenFGA utilisera le dernier modèle d’autorisation créé pour ce store) (immutable models). La documentation recommande de fixer l’identifiant dans la configuration, ce qui permet aussi d’effectuer des vérifications fantômes (shadow checks) sur un nouveau modèle avant de basculer.
La conception de l’article se situe entre les deux : un journal des modifications ayant pour clé l’horodatage de validation, comme l’historique des versions d’OpenFGA, mais avec des serveurs qui passent toujours à la version la plus récente, comme SpiceDB. Pour en savoir plus sur chaque produit : SpiceDB, OpenFGA.
Supprimer une relation demande trois étapes
Ajouter est facile. Dans SpiceDB, « Adding a new relation to a definition is always allowed, as it cannot change any existing types or computation » (ajouter une nouvelle relation à une definition est toujours autorisé, car cela ne peut modifier aucun type ni aucun calcul existant), et modifier la manière dont une permission est calculée est autorisé tant qu’elle fait référence à des relations ou permissions définies (migrating a schema).
Supprimer ne l’est pas. La même page : « For type safety reasons, any removal of a relation with data, or a relation or permission referenced by another relation or permission is disallowed. » (Pour des raisons de sûreté de typage, toute suppression d’une relation contenant des données, ou d’une relation ou permission référencée par une autre relation ou permission, est interdite.) Une relation ne peut disparaître qu’une fois ses tuples supprimés, et ses tuples ne peuvent être supprimés sans risque qu’une fois que plus rien ne calcule d’accès à partir d’eux. La suppression suit donc un ordre.
Prenons le doc de l’exemple suivi avec une relation supplémentaire hypothétique, editor, que l’équipe veut retirer. Dans le langage de schéma de SpiceDB, on part de ceci :
definition doc {
relation parent: folder
relation owner: user
relation editor: user
relation viewer: user | group#member
permission view = owner + editor + viewer + parent->view
}
Que change chaque étape, et pourquoi aucune ne peut-elle être sautée ?
Remarquez où l’accès change réellement : à l’étape 1, et non à l’étape 3. Dès que la permission cesse de lire editor, un éditeur qui n’est pas aussi propriétaire ou lecteur se voit refuser l’accès, alors que les tuples sont toujours sur le disque. C’est le moment de s’arrêter et d’observer. Le billet d’AuthZed, qui numérote ses étapes autrement, dit de cet état, avant toute suppression de données : « You can stay at step 2 for as long as desired, in production, to retain your ability to roll back the change » (vous pouvez rester à l’étape 2 aussi longtemps que vous le souhaitez, en production, afin de conserver la possibilité d’annuler la modification) (online schema migrations) : annuler l’étape 1 est une écriture de schéma, tandis qu’annuler l’étape 2 suppose de restaurer des tuples. Les trois étapes proviennent de la documentation de migration d’AuthZed, qui décrit aussi le même procédé pour retirer un type de sujet autorisé d’une relation (supprimer d’abord ces relations stockées, puis modifier le schéma).
Renommer une relation revient à une suppression plus un ajout. La documentation de SpiceDB détaille la démarche : ajouter la nouvelle relation et l’inclure dans la permission, faire écrire les deux par l’application, remplir rétroactivement (backfill), retirer l’ancienne relation de la permission, cesser de l’écrire, puis la supprimer avec les trois étapes ci-dessus (migrating a schema). La version OpenFGA de la même opération s’appuie sur les modèles immuables : écrire le nouveau modèle (un nouvel identifiant que la production n’utilise pas encore), mettre à jour l’application, copier les tuples vers le nouveau nom de relation, puis déployer l’application pointant vers le nouvel identifiant de modèle (immutable models).
Tester un modèle avec des fichiers d’assertions
Les deux produits lisent un fichier YAML contenant un modèle, quelques tuples et les réponses attendues. Les exemples ci-dessous encodent l’exemple suivi (Anne est propriétaire du readme ; Beto est dans eng ; les membres d’eng voient le readme ; Chen voit le dossier A). Ils suivent le format documenté de chaque produit, mais ont été écrits pour cette page et n’ont pas été exécutés.
OpenFGA : .fga.yaml
Un fichier .fga.yaml comporte un model (ou model_file), des tuples facultatifs et des tests ; un test peut contenir des blocs check, list_objects et list_users, chacun avec des assertions (testing models).
name: Running example
model: |
model
schema 1.1
type user
type group
relations
define member: [user]
type folder
relations
define viewer: [user]
type doc
relations
define parent: [folder]
define owner: [user]
define viewer: [user, group#member] or owner or viewer from parent
tuples:
- user: user:anne
relation: owner
object: doc:readme
- user: user:beto
relation: member
object: group:eng
- user: group:eng#member
relation: viewer
object: doc:readme
- user: folder:A
relation: parent
object: doc:readme
- user: user:chen
relation: viewer
object: folder:A
tests:
- name: readme access
check:
- user: user:anne
object: doc:readme
assertions:
owner: true
viewer: true
- user: user:chen
object: doc:readme
assertions:
owner: false
viewer: true
list_objects:
- user: user:beto
type: doc
assertions:
viewer:
- doc:readme
La CLI d’OpenFGA l’exécute avec fga model test --tests <filename>.fga.yaml et affiche un nombre de réussites par type de test (testing models).
SpiceDB : fichiers de validation
Un fichier de validation SpiceDB comporte un schema (ou schemaFile), des relationships sous la forme d’une seule chaîne multiligne plutôt que d’une liste YAML, des assertions avec assertTrue et assertFalse, et un bloc validation facultatif de relations attendues (expected relations) qui énumère chaque sujet disposant d’un accès et la manière dont il l’a obtenu (validation, testing, debugging).
schema: |-
definition user {}
definition group {
relation member: user
}
definition folder {
relation viewer: user
permission view = viewer
}
definition doc {
relation parent: folder
relation owner: user
relation viewer: user | group#member
permission view = owner + viewer + parent->view
}
relationships: |-
doc:readme#owner@user:anne
group:eng#member@user:beto
doc:readme#viewer@group:eng#member
doc:readme#parent@folder:A
folder:A#viewer@user:chen
assertions:
assertTrue:
- doc:readme#view@user:anne
- doc:readme#view@user:beto
- doc:readme#view@user:chen
assertFalse:
- doc:readme#owner@user:chen
zed validate l’exécute « using the same parsing logic that the SpiceDB binary uses » (en utilisant la même logique d’analyse que le binaire SpiceDB), et accepte depuis zed v0.25.0 plusieurs fichiers à la fois (zed validate validations/*) (validation, testing, debugging). Cette page omet le bloc validation, car sa sortie exacte pour un userset de groupe n’a pas été vérifiée ; la documentation montre la forme "[user:you] is <document:validation-testing-debugging#reader>".
Les deux fichiers testent le modèle, sur des tuples que vous inventez. Ce sont des tests unitaires du schéma, et non un contrôle des données de production.
Les exécuter en CI
Où chaque type de contrôle se place-t-il entre une pull request et la production ?
Remarquez la note de gauche. AuthZed le dit directement : « a schema write can still fail if a relation is removed and there are still instances of that relation in your database. zed doesn’t know about your data » (une écriture de schéma peut encore échouer si une relation est supprimée alors qu’il existe encore des instances de cette relation dans votre base de données. zed ne connaît pas vos données) (validation, testing, debugging). La suppression en trois étapes décrite plus haut est une procédure de déploiement, et non quelque chose qu’un fichier de test peut prouver.
Les deux projets publient des GitHub Actions. Pour SpiceDB, authzed/action-spicedb-validate exécute la validation de zed sur un fichier ; AuthZed la qualifie de « highly recommended because it can prevent deployments of unverified changes » (vivement recommandée, car elle peut empêcher le déploiement de modifications non vérifiées) (docs). Pour OpenFGA, openfga/action-openfga-test installe la CLI et exécute fga model test sur chaque fichier correspondant à *.fga.yaml sous test_path (action.yml). Un workflow minimal avec les deux :
name: Authorization model
on:
pull_request:
paths: ["authz/**"]
jobs:
spicedb:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: authzed/action-spicedb-validate@v1
with:
validationfile: authz/spicedb.yaml
openfga:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: openfga/action-openfga-test@v0.1.1
with:
test_path: authz/
Pour des modifications plus importantes, SpiceDB fournit aussi un serveur de tests d’intégration (spicedb serve-testing, ou l’action authzed/action-spicedb) qui donne à chaque clé prépartagée « an isolated, empty datastore » (un stockage de données isolé et vide), si bien que les tests de l’application peuvent s’exécuter en parallèle sur une seule instance (docs). Les identifiants de modèle fixés d’OpenFGA permettent des vérifications fantômes : envoyer la même vérification à l’ancien et au nouveau modèle et comparer avant de basculer (immutable models).
Sections de l’article : configurations d’espaces de noms §2.3 ; stockage des configurations §3.1.3 ; un seul horodatage de configuration par requête §3.2.2 ; nombre d’espaces de noms et taille des configurations §4. Les termes figurent dans le glossaire.
Sources
- Article Zanzibar, §2.1, §2.3, §3, §3.1.3, §3.2.2, §4 (transcription de ce site)
- AuthZed, Migrating a Schema in SpiceDB : authzed.com/docs/spicedb/modeling/migrating-schema
- Blog d’AuthZed, Online Schema Migrations in SpiceDB (2022-02-03) : authzed.com/blog/online-schema-migrations
- AuthZed, Validation, Testing, Debugging SpiceDB Schemas : authzed.com/docs/spicedb/modeling/validation-testing-debugging
- OpenFGA, Testing Models : openfga.dev/docs/modeling/testing
- OpenFGA, Immutable Authorization Models : openfga.dev/docs/getting-started/immutable-models
- OpenFGA Model Testing Action, action.yml : github.com/openfga/action-openfga-test
- Carla Urrea Stabile, Continuous Authorization Testing: FGA, GitHub Actions, and CI/CD, blog d’Auth0 (2025-12-17) : auth0.com/blog/continuous-authorization-testing-fga-github-ci-cd