Un esquema es la parte de un sistema de autorización que menos cambia y la que más cosas rompe cuando cambia. En el artículo es la configuración del espacio de nombres: “A namespace configuration specifies its relations as well as its storage parameters” (La configuración de un espacio de nombres especifica sus relaciones, así como sus parámetros de almacenamiento) (§2.3). En Google había “more than 1,500 namespaces” (más de 1,500 espacios de nombres), y sus archivos de configuración “range from tens of lines to thousands of lines, with the median near 500 lines” (van de decenas a miles de líneas, con una mediana cercana a 500 líneas) (§4). Esta página trata tres cosas: cómo evita el artículo que un cambio de configuración parta en dos una misma solicitud, cómo obligan los productos actuales a eliminar una relación por pasos y cómo probar un modelo antes de ponerlo en producción.
Las configuraciones de relación en sí (_this, computed_userset, tuple_to_userset) se explican en Tuplas de relación y usersets. Esta página trata de cómo cambiarlas.
Cómo versiona el artículo las configuraciones de los espacios de nombres
Las configuraciones residen en su propia base de datos 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” (Hay una base de datos para almacenar las tuplas de relación de cada espacio de nombres de cliente, una base de datos para contener todas las configuraciones de los espacios de nombres y una base de datos de registro de cambios compartida por todos los espacios de nombres) (§3). La base de datos de configuraciones es una tabla más un registro:
Así, cada versión de la configuración tiene una marca de tiempo de confirmación, y cada servidor tiene un cierto rango de versiones. El peligro es una solicitud que se reparte (véase Arquitectura): si el servidor que la recibe ya ha cargado una configuración nueva y el servidor en el que delega todavía no, las dos mitades de una misma comprobación se evaluarían con reglas distintas. El artículo lo descarta: “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 elige una única marca de tiempo de instantánea para los metadatos de configuración al evaluar cada solicitud de cliente. Todos los aclservers de un clúster usan esa misma marca de tiempo para la misma solicitud, incluidas las subsolicitudes que se reparten a partir de la solicitud original del cliente) (§3.2.2).
¿Qué marca de tiempo puede usar una solicitud cuando los servidores de un clúster han cargado versiones de configuración distintas?
Obsérvese que la nueva configuración no se usa en el momento en que se confirma. Pasa a ser utilizable cuando todos los servidores del clúster pueden servirla. En palabras del artículo, “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” (cada servidor de un clúster puede tener acceso a un rango distinto de marcas de tiempo de configuración debido a reinicios o a la latencia de red. Zanzibar debe elegir una marca de tiempo que esté disponible en todos ellos. Para facilitarlo, un proceso de monitorización registra el rango de marcas de tiempo disponible en cada servidor y los agrega, comunicando a todos los demás servidores un rango disponible globalmente. En cada solicitud entrante, el servidor elige un momento de este rango, lo que garantiza que todos los servidores puedan seguir sirviendo aunque ya no puedan leer del almacén de configuraciones) (§3.2.2).
El artículo se detiene ahí. No dice cómo migra las tuplas un cliente cuando elimina una relación, si una escritura de configuración se contrasta con las tuplas existentes ni cómo se relaciona la marca de tiempo de configuración con la instantánea de tuplas elegida para la misma solicitud. Solo dice que ⟨namespace⟩ y ⟨relation⟩ “are predefined in client configurations” (están predefinidos en las configuraciones de los clientes) (§2.1), y que una relación forma parte de la clave primaria de cada tupla (§2.1, §3.1.1). El resto de esta página trata de cómo gestionan ese hueco los sistemas de código abierto.
Versiones del esquema en dos productos
Los dos productos más documentados tomaron decisiones distintas.
- SpiceDB tiene un único esquema actual por despliegue, que se sustituye con
WriteSchema. La documentación de AuthZed dice que SpiceDB “processes all calls to the WriteSchema in a safe manner: it is not possible to break the type safety of a schema” (procesa todas las llamadas a WriteSchema de forma segura: no es posible romper la seguridad de tipos de un esquema), lo que significa que “it is not possible to accidentally remove a relation that is still referenced by one or more relationships” (no es posible eliminar por accidente una relación a la que todavía hacen referencia una o varias relaciones almacenadas) (migrating a schema). Una entrada de AuthZed de 2022 añade que las escrituras de esquema son totalmente consistentes, de modo que las escrituras de relaciones posteriores a una escritura de esquema se evalúan con el nuevo esquema (online schema migrations). - OpenFGA conserva todas las versiones. “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.” (Los modelos de autorización de OpenFGA son inmutables: se crean una vez y después ya no pueden eliminarse ni modificarse. Cada vez que se escribe un modelo de autorización, se crea una nueva versión.) Las solicitudes pueden nombrar un
authorization_model_id; sin él, “OpenFGA will use the last created Authorization Model for that store” (OpenFGA usará el último modelo de autorización creado para ese store) (immutable models). La documentación recomienda fijar el ID en la configuración, lo que también permite hacer comprobaciones en la sombra contra un modelo nuevo antes de cambiar.
El diseño del artículo queda entre los dos: un registro de cambios con marcas de tiempo de confirmación como clave, como el historial de versiones de OpenFGA, pero con los servidores pasando siempre a la versión más reciente, como SpiceDB. Más sobre cada producto: SpiceDB, OpenFGA.
Eliminar una relación requiere tres pasos
Añadir es fácil. En SpiceDB, “Adding a new relation to a definition is always allowed, as it cannot change any existing types or computation” (añadir una nueva relation a una definition siempre está permitido, ya que no puede cambiar ningún tipo ni cálculo existente), y cambiar cómo se calcula un permiso está permitido siempre que haga referencia a relaciones o permisos definidos (migrating a schema).
Eliminar, no. La misma página: “For type safety reasons, any removal of a relation with data, or a relation or permission referenced by another relation or permission is disallowed.” (Por motivos de seguridad de tipos, no se permite eliminar una relation con datos, ni una relation o un permission a los que haga referencia otra relation u otro permission.) Una relación solo puede desaparecer cuando sus tuplas han desaparecido, y sus tuplas solo pueden desaparecer de forma segura cuando nada calcula el acceso a partir de ellas. Así que la eliminación tiene un orden.
Tómese el doc del ejemplo de referencia con una relación adicional hipotética, editor, que el equipo quiere quitar. En el lenguaje de esquemas de SpiceDB empieza así:
definition doc {
relation parent: folder
relation owner: user
relation editor: user
relation viewer: user | group#member
permission view = owner + editor + viewer + parent->view
}
¿Qué cambia cada paso y por qué no puede saltarse ninguno?
Obsérvese dónde cambia realmente el acceso: en el paso 1, no en el paso 3. En cuanto el permiso deja de leer editor, a un editor que no sea también propietario o lector se le deniega el acceso, mientras las tuplas siguen en disco. Ese es el momento de detenerse y observar. La entrada de AuthZed, que numera sus pasos de otra forma, dice de este estado, antes de eliminar ningún dato: “You can stay at step 2 for as long as desired, in production, to retain your ability to roll back the change” (puede quedarse en el paso 2 todo el tiempo que desee, en producción, para conservar la capacidad de revertir el cambio) (online schema migrations): revertir el paso 1 es una escritura de esquema, mientras que revertir el paso 2 supone restaurar tuplas. Los tres pasos proceden de la documentación de migraciones de AuthZed, que también describe el mismo patrón para quitar un tipo de sujeto permitido de una relación (primero eliminar esas relaciones y después editar el esquema).
Renombrar una relación es una eliminación más una adición. La documentación de SpiceDB lo recorre: añadir la nueva relación e incluirla en el permiso, hacer que la aplicación escriba ambas, rellenar los datos, quitar la relación antigua del permiso, dejar de escribirla y después eliminarla con los tres pasos anteriores (migrating a schema). La versión de OpenFGA del mismo trabajo se apoya en los modelos inmutables: escribir el nuevo modelo (un ID nuevo que producción todavía no usa), actualizar la aplicación, copiar las tuplas al nuevo nombre de relación y después desplegar la aplicación apuntando al nuevo ID de modelo (immutable models).
Probar un modelo con archivos de aserciones
Los dos productos leen un archivo YAML que contiene un modelo, algunas tuplas y las respuestas esperadas. Los ejemplos siguientes codifican el ejemplo de referencia (Anne es propietaria del readme; Beto pertenece a eng; los miembros de eng ven el readme; Chen ve la carpeta A). Siguen el formato documentado de cada producto, pero se escribieron para esta página y no se han ejecutado.
OpenFGA: .fga.yaml
Un archivo .fga.yaml tiene un model (o model_file), tuples opcionales y tests; una prueba puede contener bloques check, list_objects y list_users, cada uno con 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 de OpenFGA lo ejecuta con fga model test --tests <filename>.fga.yaml e imprime el número de pruebas superadas por tipo de prueba (testing models).
SpiceDB: archivos de validación
Un archivo de validación de SpiceDB tiene un schema (o schemaFile), relationships como una única cadena de varias líneas en lugar de una lista YAML, assertions con assertTrue y assertFalse, y un bloque validation opcional de relaciones esperadas que enumera cada sujeto con acceso y cómo lo obtuvo (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 lo ejecuta “using the same parsing logic that the SpiceDB binary uses” (con la misma lógica de análisis que usa el binario de SpiceDB), y desde zed v0.25.0 acepta varios archivos a la vez (zed validate validations/*) (validation, testing, debugging). Esta página omite el bloque validation porque no se ha comprobado su salida exacta para un userset de grupo; la documentación muestra la forma "[user:you] is <document:validation-testing-debugging#reader>".
Los dos archivos prueban el modelo, contra tuplas inventadas. Son pruebas unitarias del esquema, no una comprobación de los datos de producción.
Ejecutarlas en CI
¿Dónde va cada tipo de comprobación entre una pull request y producción?
Obsérvese la nota de la izquierda. AuthZed lo dice directamente: “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” (una escritura de esquema puede seguir fallando si se elimina una relación y todavía hay instancias de esa relación en su base de datos. zed no conoce sus datos) (validation, testing, debugging). La eliminación en tres pasos descrita más arriba es un procedimiento de despliegue, no algo que un archivo de pruebas pueda demostrar.
Los dos proyectos publican GitHub Actions. Para SpiceDB, authzed/action-spicedb-validate ejecuta la validación de zed sobre un archivo; AuthZed lo califica de “highly recommended because it can prevent deployments of unverified changes” (muy recomendable porque puede impedir despliegues de cambios no verificados) (documentación). Para OpenFGA, openfga/action-openfga-test instala la CLI y ejecuta fga model test sobre cada archivo que coincida con *.fga.yaml bajo test_path (action.yml). Un workflow mínimo con ambos:
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/
Para cambios mayores, SpiceDB incluye además un servidor de pruebas de integración (spicedb serve-testing, o la acción authzed/action-spicedb) que da a cada clave precompartida “an isolated, empty datastore” (un almacén de datos aislado y vacío), de modo que las pruebas de la aplicación pueden ejecutarse en paralelo contra una sola instancia (documentación). Los ID de modelo fijados de OpenFGA permiten comprobaciones en la sombra: enviar la misma comprobación al modelo antiguo y al nuevo y comparar antes de cambiar (immutable models).
Secciones del artículo: configuraciones de los espacios de nombres §2.3; almacenamiento de las configuraciones §3.1.3; una marca de tiempo de configuración por solicitud §3.2.2; número de espacios de nombres y tamaño de las configuraciones §4. Los términos están en el glosario.
Fuentes
- Artículo de Zanzibar, §2.1, §2.3, §3, §3.1.3, §3.2.2, §4 (transcripción de este sitio)
- AuthZed, Migrating a Schema in SpiceDB: authzed.com/docs/spicedb/modeling/migrating-schema
- Blog de 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 de Auth0 (2025-12-17): auth0.com/blog/continuous-authorization-testing-fga-github-ci-cd