Skip to main content

Entity Model and Configuration

EnforceAuth organizes authorization work under entities — a hierarchy of organizations and systems that own policy sources, bundle destinations, environments, secrets, and API keys.

Manage the tree at System Settings → Entity Management (/system-settings/entities).

Entity types​

TypeRole
OrganizationTenant-scoped root or intermediate node; global defaults for policy source, bundle destination, and environments
SystemDeployable unit — typically one application or service boundary that receives bundles and sends decision logs

The API also supports user entities for identity graph use cases; the console create form offers Organization and System only.

Hierarchy rules​

  • Every new entity (except tenant bootstrap) must have a parent — you cannot create arbitrary root orgs after initial setup. The form error is explicit: Select a parent entity. New root entities can only be created during tenant setup.
  • Root organizations have no parents and display a Root badge. Root entities cannot be deleted.
  • Navigate Path to Root, Parents, and Children on the entity detail page. Empty states: No parent entities / No child entities.

Views on Entity Management:

  • Table — flat list with type and relationships
  • Graph — visual hierarchy

Subtitle on the page: Entity Structure with org/system counts.

What attaches to an entity​

Entity detail groups operational config:

SectionPurpose
RelationshipsParent/child links in the authz graph
ConfigurationPolicy source, bundle destination, environments
SecretsCredentials for Git, cloud storage, etc.
API KeysService identities for decision log ingestion
CI/CD TokensPipeline authentication for automated deploys

Routes:

  • List: /system-settings/entities
  • Create: /entities/new
  • Detail: /entities/:id
  • Edit: /entities/:id/edit

Legacy /entities redirects to System Settings.

Configuration types​

Three config kinds drive deployments:

Policy source​

Connects Git (GitHub today) with branch and policy_path. EnforceAuth clones the repo during deploy and runs opa test + bundle build.

Org-level note in UI: Global default, can be overridden at system level.

Bundle destination​

Where PDPs fetch bundles — S3, GCS, Azure Blob, or Git output. System-level note: If blank, inherits from parent organization.

Environments​

Maps environment names (e.g. dev, staging, prod) to promotion targets and optional per-environment branch/path or destination overrides. See Deployments.

Configuration inheritance​

Child entities inherit effective config from ancestors unless they define an override.

The console resolves inheritance via the effective-config API and shows:

  • Inherited from parent entity name — dashed border on inherited cards
  • Will inherit from parent entity — placeholder when a field is empty
  • InheritedPathDisplay — merged policy or bundle paths from ancestors

Depth in API responses: 0 = defined on this entity, >0 = from an ancestor.

Practical rules:

  • Set policy source and bundle destination at the org if most systems share one repo or storage account
  • Override at the system when a team needs an isolated repo or bucket
  • Environment bundle destination overrides can be partial — storage backend identity may still come from the parent

Deploy eligibility uses effective config: a system with no local policy source still deploys if it inherits both source and destination from its org.

Policies and entities​

On the Policies page, each row shows:

  • System — owning entity name
  • Inherited By / Imposed On — how policy packages flow through the hierarchy

This helps answer whether a Rego file applies only locally or propagates to descendant systems.

Deployability checklist​

Before an entity appears in the Deploy dialog:

  1. Effective policy source exists (local or inherited)
  2. Effective bundle destination exists (local or inherited)
  3. Target environment is configured on the entity

Missing pieces surface as Not configured, Missing policy source, or Missing bundle destination in the deploy picker.

API keys and decision logs​

API keys scoped to an entity authenticate OPA/EOPA instances that send decision logs for policies under that subtree. See Decision logs.

Common patterns​

Single org, many systems​

Acme Corp (org)
├── Payments API (system)
├── Admin Portal (system)
└── Data Pipeline (system)

Org holds default Git repo and S3 bucket; systems override only when teams need isolation.

Business unit per org​

Enterprise Root (org)
├── Retail Division (org)
│   └── Storefront (system)
└── Wholesale Division (org)
    └── B2B API (system)

Each division owns environments and promotion chains independently.

Verify success​

  • Entity appears in hierarchy with correct parent
  • Effective config shows expected source/destination (own or inherited)
  • Deploy dialog lists the entity without configuration warnings
  • Policies and decision logs scope to the intended system name