Skip to main content

Authorization Topology Service

Summary​

Authorization Topology Service manages the metadata that maps authorization decisions to the correct evaluation contexts. It maintains awareness of how Resources, Tenants, Organizations, and other entities relate to each other, enabling policies to be evaluated against the appropriate data.

Why It Exists​

Authorization decisions depend on context. A policy that grants access to "documents in the user's department" requires knowing:

  • Which department does the user belong to?
  • Which documents belong to that department?
  • How are departments organized within the tenant?

Authorization Topology Service provides this contextual awareness by maintaining metadata about entity relationships and data mappings.

Where It Fits in Keymate​

The topology service works alongside the Compile & Artifact Pipeline to ensure policies reference valid contexts:

Boundaries​

This component handles:

  • Entity relationship metadata
  • Context mapping for policy evaluation
  • Topology validation during compilation
  • Schema definitions for authorization contexts

This component does not handle:

  • Policy definition (Admin Console)
  • Policy compilation (Compile & Artifact Pipeline)
  • Runtime policy evaluation (Policy Engine, FGA Engine)
  • Entity data storage (external systems)

How It Works​

Topology Metadata​

The service maintains metadata describing:

Metadata TypeDescription
Entity TypesDefined entity categories (User, Resource, Organization)
RelationshipsHow entities relate to each other
AttributesProperties available on each entity type
SchemasStructure definitions for authorization contexts

Context Mapping​

When policies reference attributes like "user.department" or "resource.owner", the topology service provides:

  1. Attribute resolution — Where to find the attribute value
  2. Relationship traversal — How to navigate entity relationships
  3. Schema validation — Whether the reference is valid

Schema Definitions​

Schemas define the structure of authorization contexts:

Integration with Compilation​

During policy compilation, the topology service:

  1. Validates attribute references exist in schemas
  2. Verifies relationship paths are valid
  3. Provides context mapping data for the compiled artifact

Diagram​

Example Scenario​

Scenario​

A policy author creates a ReBAC policy that grants access based on the "editor" relationship between users and documents. The topology service validates this relationship exists.

Input​

  • Actor: Compile & Artifact Pipeline
  • Resource: ReBAC policy referencing "editor" relationship
  • Action: Validate topology
  • Context: Document resource type, User entity type

Expected Outcome​

  • Result: Validation passes, relationship mapping included in artifact
  • Why: "editor" relationship is defined between User and Document in the topology schema

Common Misunderstandings​

  • Topology service stores entity data — It stores metadata about entity structure, not the actual entity data
  • All attributes must be pre-defined — Core attributes are defined in topology; dynamic attributes may be resolved at runtime
warning

Topology changes affect all policies that reference the modified schemas. Test topology updates thoroughly before deploying to production.

Design Notes / Best Practices​

  • Define clear, stable schemas before creating policies
  • Use consistent naming conventions for attributes and relationships
  • Document relationship semantics for policy authors
  • Version topology schemas to track changes
tip

Start with a minimal topology schema covering core entities. Extend the schema as new authorization patterns emerge.

  • Multi-tenant authorization with tenant-specific schemas
  • Complex organizational hierarchies
  • Resource ownership and delegation models
  • Dynamic attribute resolution

Compile & Artifact Pipeline

How topology informs compilation

FGA Engine

Relationship-based authorization at runtime

Resources and Scopes

Resource model concepts