Authorization

Authorization providers back dynamic subject authorization state. They are separate from platform login: providers.authentication.<name> decides how users sign in to Gestalt, while providers.authorization.<name> stores authorization relationships and answers authorization queries for Gestalt itself.

This relationship-oriented authorization model is inspired by Google Zanzibar , Google’s global authorization system.

How authorization providers work

Static shared policies still live under top-level authorization.policies. When server.providers.authorization selects a provider, Gestalt writes its authorization model plus dynamic subject plugin and built-in admin relationships into that provider and uses it for runtime subject authorization checks.

Dynamic human plugin/admin grants and the built-in authorization control-plane APIs require an authorization provider. If you omit providers.authorization, Gestalt still evaluates static policy members from config, but there is no provider-backed relationship storage or dynamic subject-grant control plane.

Product authorization semantics

At the product level, authorization is about subjects and runtime surfaces. Gestalt resolves each request to a canonical subject such as user:<id>, service_account:<id>, or a system subject, then asks whether that subject may access the thing they are trying to use. Static memberships under authorization.policies are always available. When you configure an authorization provider, Gestalt adds dynamic relationship storage on top so those decisions can change without editing YAML.

This is separate from authentication. Authentication answers who the caller is. Authorization answers what that caller may do once their subject is known.

Plugin invocation

Plugin authorization happens at request time. Gestalt checks whether the calling subject may access the plugin or operation before it invokes the target. The subject’s upstream connection is also scoped to that same subject, so access is both identity-aware and credential-aware.

Workflow execution

Workflow authorization happens twice. Gestalt checks access when a user creates a schedule, then checks again when that schedule or trigger fires later. User owned workflows keep the creating subject plus a permission ceiling for delayed execution. Config-managed workflows use the system config subject instead.

UI routes

Mounted UI bundles can bind an authorizationPolicy, and their manifests can declare route-level allowedRoles. Gestalt resolves the caller’s subject, derives their role for the bound policy, and checks that role before serving the matched route. The built-in admin UI uses the same model.

First-party authorization providers

First-party authorization providers live under valon-technologies/gestalt-providers/authorization.

Configuring providers.authorization

server:
  providers:
    indexeddb: main
    authorization: indexeddb
 
providers:
  indexeddb:
    main:
      source: https://artifacts.example.com/indexeddb/relationaldb/v0.0.1-alpha.1/provider-release.yaml
      config:
        dsn: ${DATABASE_URL}
 
  authorization:
    indexeddb:
      source: https://artifacts.example.com/authorization/indexeddb/v0.0.1-alpha.1/provider-release.yaml
      config:
        indexeddb: main

The first-party authorization/indexeddb provider expects the name of a host IndexedDB provider and stores authorization models plus relationships there.

Operational notes

server.providers.authorization selects the host authorization provider. If more than one entry exists under providers.authorization, set server.providers.authorization explicitly or mark one entry default: true. Built-in admin authorization membership and inspection APIs use the selected provider. Static policy members still take precedence over dynamic grants.

Building your own authorization provider

Implementation details for the decision plane, relationship control plane, and model lifecycle now live under Custom Providers > Authorization.

What to read next

For the full server and provider config structure, read Configuration. For the exact providers.authorization reference, continue to Config File. If you want to see how these semantics apply to concrete surfaces, read Plugin, Workflow, and UI. For provider implementation details, see Custom Authorization Providers.