EnforceAuth User Guide

The complete, task-oriented reference for using EnforceAuth day to day. If you're brand new, start with Your First 10 Minutes or the Onboarding Guide; come here when you need to do a specific thing and want the exact steps, routes, and verification.

How this guide is organized — one chapter per area of the product:

1. Concepts you must know
2. The console: navigation & dashboard
3. Entities: organizations & systems
4. Configuration: policy sources, bundle destinations, environments
5. Policies: authoring, drafts, and detail
6. Deployments: running, promoting, rolling back
7. Decision logs & monitoring
8. Secrets, API keys & CI/CD tokens
9. Users, groups & invitations
10. System Settings portal: Functionality & Integrations
11. Connect MCP (AI agents)
12. The eactl CLI
13. GitHub Actions & CI/CD automation
14. Audit & compliance evidence
15. Troubleshooting
16. Glossary

Console URLs: console.enforceauth.com (prod) / console.enforceauth.dev. API: api.enforceauth.com/docs.

---

1. Concepts you must know

EnforceAuth is an enterprise authorization control plane for Policy as Code. It sits above your policy engines. It is not a PDP, not an IAM/SSO provider, and not a SIEM. The loop it manages is Define → Enforce → Audit:

• Define — Rego policies in Git, reviewed like code, with version history.
• Enforce — EnforceAuth builds OPA bundles and promotes them across environments to your PDP fleet.
• Audit — every decision is logged for investigation, replay, coverage, and compliance.

Your PDP is OPA or EOPA. OSS OPA is the default; Enterprise OPA (EOPA) adds decision-log masking at the PDP, delta bundles at large scale, and bundle partitioning. Same Rego, same bundles, same pipeline. Cedar (Arbi) and Zanzibar (iBar) engines are on the roadmap.

Runtime boundary: authorization checks are synchronous (PEP → your PDP) and customer-operated. EnforceAuth does not sit on that path. An EnforceAuth API outage does not stop local evaluation of an already-activated bundle; a PDP outage does (typically fail-closed). See Runtime boundary and scope of responsibility.

The object model (used everywhere in this guide):

Object	One-line definition
Organization	Tenant-scoped root or grouping node in the entity tree; holds shared config defaults
System	A deployable unit — one app/service — that receives bundles and emits decision logs
Environment	A promotion target: dev → staging → prod
Policy source	Git repo + branch + policy_path that supplies Rego
Bundle destination	S3 / GCS / Azure Blob / Git output where PDPs fetch bundles
Deployment	A pipeline run: opa test → bundle build → publish → (promote)
Secret	Credential for Git or cloud storage, attached to an entity
API key	Service identity a PDP uses to send decision logs; entity-scoped
CI/CD token	Pipeline authentication for automated deploys
Decision log	One authorization decision ingested from a PDP
PDP	Policy Decision Point — the OPA/EOPA engine that enforces
PEP	Policy Enforcement Point — your app code that calls the PDP

---

2. The console: navigation & dashboard

Left navigation

The console's top-level areas are exactly these (in order):

• Dashboard — real-time health overview.
• Policies — statistics and policy management.
• Decisions — decision logs from your PDPs.
• Deployments — trigger and track pipeline runs.
• Analytics — Coming Soon.
• System Settings — the admin portal (Functionality Management, Entity Management, User Management, Integrations; Alerts / Admin Analytics / Billing are Coming Soon).

Your identity and Collapse Sidebar sit at the bottom of the left rail.

Where the "other" things live. There is no top-level Monitoring, Audit Logs, Secrets, or Settings nav item. Instead:

• Audit trail → System Settings → User Management → Audit trail.
• Secrets, API Keys, CI/CD Tokens → per-entity tabs on the entity detail page.
• Feature flags → System Settings → Functionality Management (tenant-wide).
• Integrations (GitHub App) → System Settings → Integrations.

Dashboard

/ — Real-time overview of your policy enforcement platform.

The landing page after sign-in. Pick a Timeframe (24 hours / 7 days / 30 days). Policy Statistics shows Active vs. Total policies; Decision Statistics shows Total Decisions, Average Duration, and Decision Volume Over Time. Pause stops the live refresh; Refresh now forces an update. "View policies" / "View decisions" jump into those areas.

A visual tour of every page in this chapter is collected in the Console Visual Reference.

---

3. Entities: organizations & systems

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

Entity types

• Organization — root or intermediate grouping node; holds global default policy source, bundle destination, and environments.
• System — the deployable unit; typically one application or service boundary.

The API also supports user entities (identity-graph use cases), but the console create form offers Organization and System only.

Hierarchy rules

• Every entity except the tenant root must have a parent. New root orgs can only be created during tenant setup — the form says so explicitly if you try.
• Root orgs show a Root badge and cannot be deleted.
• The detail page shows Path to Root, Parents, and Children (empty states read No parent entities / No child entities).

Views

• Table — flat list with type and relationships.
• Graph — visual hierarchy. Page subtitle ("Entity Structure") shows org/system counts.

What attaches to an entity

The detail page groups operational config into sections:

Section	Purpose
Relationships	Parent/child links in the authz graph
Configuration	Policy source, bundle destination, environments
Secrets	Credentials for Git, cloud storage, etc.
API Keys	Service identities for decision-log ingestion
CI/CD Tokens	Pipeline authentication for automated deploys

Routes

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

Configuration inheritance

Children inherit effective config from ancestors unless they define an override. The console resolves this via the effective-config API and shows:

• Inherited from parent name — dashed border on inherited cards.
• Will inherit from parent — placeholder on an empty overridable field.

Design tip: push shared Git + storage config up to an org; override only the genuinely-different fields on individual systems.

How-to: create an organization and system

1. System Settings → Entity Management → Create Entity.
2. Basic Information: enter a Name (required), pick Type (Organization or System), and choose a Parent Entity ("Select an existing organization to create this entity as a child"). Add a Description.
3. (Optional) External Integration: set External ID and External System (e.g. salesforce) to link the entity to an outside system of record.
4. For a system, open it and set Configuration (next chapter).

Verify: the entity shows correct type and Path to Root.

---

4. Configuration

Set on any entity's Configuration section. Three kinds drive deployments. Set shared values high in the tree; override low.

4a. Policy source

• Storage type: Git (GitHub today).
• Fields: repository, branch, policy_path (folder holding the Rego package).
• Access: authorize the EnforceAuth GitHub App (System Settings → Integrations); store any needed credential as a Secret on the entity.
• On deploy: EnforceAuth clones the repo, runs opa test, then builds the bundle.
• Org-level note in UI: Global default, can be overridden at system level.

4b. Bundle destination

Where PDPs fetch bundles:

• S3 — bucket + path
• GCS — bucket + path
• Azure Blob — container + path
• Git output — write the built bundle back to a repo/branch
• System-level note: If blank, inherits from parent organization.

Use per-environment path overrides so dev/staging/prod artifacts don't collide.

4c. Environments

Map environment names (dev, staging, prod) to promotion targets, with optional per-environment branch/path or destination overrides. This defines your promotion chain.

Verify: the entity's Configuration shows resolved Policy source, Bundle destination, and environments (set or inherited).

---

5. Policies

Manage policy content from the Policies area (/policies).

The page has two tabs — Statistics Overview and Policies. The overview tiles count Active · Error · Draft · Disabled · Total Policies, plus Coverage (% of policies evaluating live traffic), with a 24h/7d/30d timeframe, Top 10 Triggered Policies, and Policy Usage Over Time.

• Policies list — every policy visible to you, with status.
• Create policy — start a new policy.
• Draft policy — work on a draft before it's finalized/deployed. Drafts let you iterate on Rego without affecting what's live.
• Policy detail — view a single policy: its content, source, and history.

The relationship to Git: the deployable source of truth for policy content is your policy source repo — Rego is authored, reviewed, and versioned in Git, and EnforceAuth builds bundles from it. The Policies pages give you an in-console view and drafting surface over that content. Keep Git as the canonical author-and-review path; use the console to inspect, draft, and understand what will ship.

How-to: review what a policy will deploy

1. Open Policies → the policy → Policy detail.
2. Confirm the package, rules, and source branch/path match what you expect.
3. Cross-check against the Deployments page to see which bundle/environment currently carries it.

Verify: the policy's source and the target system's policy_path agree.

Make opa test a real gate: policies that fail tests fail the deploy's test phase. See Testing policies.

---

6. Deployments

The Deployments page (/deployments) is where pipeline runs are triggered and tracked. It's scoped to all entities and auto-refreshes every 60s.

Stat tiles across the top: Initiated · In Progress · Successful · Failed. Search by run ID / entity / user, filter by Status, and start a run with Deploy. Until a policy source is configured the list is empty ("Policy deployments will appear here once you configure a policy source and trigger a deployment").

Pipeline phases

Every deployment runs: test (opa test on the policy source) → build (assemble the OPA bundle) → publish (write the artifact to the bundle destination). A green run means a real, tested bundle now lives at the destination.

Ways to trigger a deployment

1. Manually — the Deploy button, for a system + environment.
2. GitHub Actions — on merge, via the deploy-action (see chapter 13).
3. Webhooks / eactl — from any CI using eactl pipeline.

Promotion (dev → staging → prod)

Promotion moves the same tested artifact forward instead of rebuilding:

1. Deploy and validate in dev.
2. Promote to staging; validate (integration tests, decision logs).
3. Promote to prod. This guarantees prod runs exactly what staging proved.

Rollback / restore

If a promotion misbehaves, restore the environment to its previous good bundle. Because artifacts are versioned, rollback is selecting a known-good bundle — not a rebuild. See Deployments and Multi-environment best practices.

How-to: first deployment

1. Deployments → Deploy → your system in dev.
2. Watch test → build → publish.
3. On failure, run eactl diagnose preflight (chapter 12).

Verify: one succeeded run; artifact present at the destination.

---

7. Decision logs & monitoring

Decisions (/decisions)

Real-time policy evaluation log across all entities.

Every authorization decision your PDPs make is ingested here (when they're configured with an entity API key). Each log shows the input, the result, and the source system. Filter by Decision ID, outcome, policy, and time range; Pause / Refresh now control the stream. Use Decisions to:

• Confirm a newly-wired PDP is reporting.
• Investigate a specific allow/deny ("why was this denied?").
• Decision Replay — re-run a recorded decision for investigation, coverage, and audit.

Decision logs are the raw material for continuous authorization and audit evidence (chapter 14).

Fleet monitoring

Fleet-level operational visibility — PDP health and bundle activation status — tells you whether every PDP is on the bundle you expect and catches one stuck on a stale bundle or gone quiet. In the current console this surfaces through the Dashboard health tiles and the Deployments run history rather than a separate top-level "Monitoring" nav item (a MonitoringPage exists in the codebase and may appear under a flag). Verify the live surface before linking to it.

How-to: confirm a PDP is live

1. Configure the PDP with the entity's API key + bundle URL (chapter 8).
2. Send a query.
3. Open Decisions; wait past your decision_logs reporting delay.

Verify: the decision appears with correct input/result/source.

---

8. Secrets, API keys & CI/CD tokens

All three are managed per entity, on the entity detail page's Secrets, API Keys, and CI/CD Tokens tabs.

Secrets

Credentials the pipeline needs: Git access, cloud-storage keys. Stored against the entity that uses them. Never commit these to Git; store them here (or in your own secret manager and reference them).

API keys

The service identity a PDP uses to send decision logs, scoped to an entity.

• Create: entity → API Keys → create → copy immediately (shown once).
• Use: paste into your OPA/EOPA decision_logs config. Copy the pre-filled block from the API Keys / Decision logs page.
• Scope narrowly: the smallest entity that needs it.
• Rotate: on a schedule and immediately on exposure. See API keys.

CI/CD tokens

Authenticate automated deploys (GitHub Actions, eactl in CI). Mint per entity; store as a CI secret (e.g. a GitHub Actions secret).

Security: treat every key/token as production-sensitive. Don't paste live values into shared docs, tickets, or chat. Rotate on exposure. Prefer your secret manager as the system of record.

---

9. Users, groups & invitations

System Settings → User Management (/system-settings/users) — Manage who has access to EnforceAuth and what they can see.

One page, four tabs:

• Users — invite, view, and manage people. Filter by Status, User Group, and Entities. Add User invites one; Bulk Import onboards many.
• Groups — group users to assign access at scale rather than per person.
• Invitations — pending invites; recipients complete the Accept Invitation / Join Organization flow to get in.
• Audit trail — the record of who changed what in EnforceAuth (this is where audit lives — there is no separate top-level Audit Logs page).

Least-privilege guidance

Different roles need different access:

• Policy authors — Policies + policy source repos.
• Deployers / platform — Deployments, entities, secrets/keys.
• Compliance / audit — Decisions + Audit trail; typically not deploy rights.

How-to: invite a teammate

1. System Settings → User Management → Users → Add User; enter the email.
2. Assign to the right Group / role.
3. They accept via the invitation link and sign in.

Verify: the user appears active with the intended access.

---

10. System Settings portal: Functionality & Integrations

System Settings (/system-settings) is a portal of admin cards: Functionality Management, Entity Management (chapter 3), User Management (chapter 9), and Integrations. Alerts & Notifications, Admin Analytics, and Billing are Coming Soon.

Functionality Management (feature flags)

/system-settings/functionality

Tenant-wide feature flags: "Control which product features are available to everyone in your organization. Changes apply tenant-wide." Toggling a flag affects everyone; "Reverting an override falls back to the platform default."

Feature flags are security-relevant. Enabling capabilities broadly can widen access. Turn on what you need deliberately; avoid "enable everything." Review flag changes like any other access change.

Integrations (GitHub App)

/system-settings/integrations

Connect third-party services so EnforceAuth can read policy sources on your behalf. Today this is GitHub: install the EnforceAuth GitHub App on your org so policy_source rows can read private repositories without per-user PATs. Supports github.com and GitHub Enterprise Server. Click Connect GitHub to start. Prefer this over personal access tokens — it survives individual users leaving.

CI providers / CI-CD tokens: pipeline authentication for automated deploys is managed as CI/CD Tokens on the relevant entity (chapter 8), not as a separate top-level Settings page.

---

11. Connect MCP (AI agents)

EnforceAuth ships an MCP server that exposes policy and authorization context to AI agents over the Model Context Protocol.

Verify the live surface before publishing steps. A Connect MCP card did not appear in the System Settings portal for this tenant — it may be flag-gated (see Functionality Management) or reached by a direct route. Treat MCP as an available platform capability and confirm the exact console path on your build.

When you do enable it:

• Enable MCP only for agents you trust.
• Scope what the connection can reach deliberately.
• Treat the MCP credential like any other secret.

---

12. The eactl CLI

eactl is EnforceAuth's Go CLI. It embeds the OPA Control Plane, so alongside EnforceAuth-specific commands you get OCP's policy/bundle/server operations.

Install

brew install enforceauth/tap/eactl

(from the homebrew-tap). An install.sh is also available in the ctl package.

Top-level commands

• eactl pipeline — Run the policy pipeline (test, build, deploy) for an entity. This is the same test → build → publish the console triggers, runnable from CI or locally.
  • eactl pipeline serve — run a local HTTP server that mirrors the pipeline API for development.
• eactl diagnose — troubleshooting tools for pipeline issues:
  • eactl diagnose preflight — end-to-end readiness check (run this first when a deploy fails).
  • eactl diagnose permissions — verify write access to the bundle destination.
  • eactl diagnose secrets — verify credential resolution.
  • eactl diagnose runs — inspect recent pipeline runs.
• Plus the embedded OPA Control Plane commands for policy/bundle/server operations.

How-to: deploy from the terminal

1. Authenticate eactl (CI/CD token / env config).
2. eactl diagnose preflight — confirm the entity is deploy-ready.
3. eactl pipeline — run test → build → deploy.

Verify: the run shows in Deployments; eactl diagnose runs lists it as succeeded.

See Tools → eactl for the full command reference.

---

13. GitHub Actions & CI/CD automation

Automate deploys so a merge ships policy.

1. Add the EnforceAuth deploy-action to your policy repo's workflow.
2. Store a CI/CD token (chapter 8) as a GitHub Actions secret.
3. Map branches to environments (e.g. main → dev, tags → prod) per your promotion policy.

On merge, the Action runs the pipeline and creates a deployment automatically. See GitHub Actions and CI/CD.

Verify: a merge to the policy branch produces a new run in Deployments with no manual trigger.

---

14. Audit & compliance evidence

• Audit trail — the record of who changed what in EnforceAuth (entity edits, deploys, key changes, user/role changes), found under System Settings → User Management → Audit trail (chapter 9). Use for internal governance and change forensics.
• Decision logs (chapter 7) — the record of what your PDPs decided. These are the evidence that authorization is actually enforced continuously.

Together they support continuous compliance: EnforceAuth turns decision telemetry into audit evidence for regulated workloads. See Continuous compliance and Audit evidence for building an audit package (coverage, decision replay, immutable trails).

How-to: pull audit evidence for a review

1. Scope the window and system.
2. Export/inspect Decision logs for enforcement coverage.
3. Pair with the Audit trail to show policy-change governance.

Verify: you can show, for a period, both what was decided and who changed the controlling policy.

---

15. Troubleshooting

Symptom	Likely cause	Fix
Deploy fails at test	policy_path wrong or opa test failing	Run opa test locally on the same path; fix Rego/tests
Deploy fails at build	Malformed bundle inputs	Check policy source structure; review run logs
Deploy fails at publish	Destination credentials/permissions	eactl diagnose permissions + eactl diagnose secrets
PDP won't load bundle	Wrong bundle URL/creds in OPA services	Confirm artifact exists at destination; re-copy config
No decision logs	API key wrong/expired or decision_logs misconfigured	Re-copy block from Decision logs page; wait past max_delay_seconds
PDP on stale bundle	Bundle not promoted / polling issue	Confirm promotion reached that environment; check Dashboard health
Can't create a root org	By design	Root orgs are created only at tenant setup; create under an existing parent
Inherited config unexpected	Override missing/misplaced	Check the entity's effective config; set an override at the right level
Everything at once	—	eactl diagnose preflight runs the full readiness check

Also see Integrations & troubleshooting in the platform docs.

---

16. Glossary

• Control plane — EnforceAuth itself: governs policy lifecycle, deployment, and audit above your PDPs. Not on the per-request authorization path.
• Data plane / runtime — your PEP → PDP path; synchronous, customer-operated. See Runtime boundary.
• PDP (Policy Decision Point) — OPA/EOPA; evaluates policy and returns allow/deny. You operate availability.
• PEP (Policy Enforcement Point) — your application code that calls the PDP and enforces the result.
• Bundle — the packaged, tested policy artifact (bundle.tar.gz) a PDP downloads.
• Entity — a node in your tree; an Organization or a System.
• Policy source — the Git repo/branch/path supplying Rego.
• Bundle destination — the storage a PDP fetches bundles from.
• Decision log — a single recorded authorization decision.
• Promotion — moving a tested bundle dev → staging → prod without rebuilding.
• OPA — Open Policy Agent (OSS default PDP). EOPA — Enterprise OPA (masking, delta bundles, partitioning).
• Rego — OPA's policy language.
• MCP — Model Context Protocol; how AI agents connect to EnforceAuth.
• eactl — EnforceAuth CLI (embeds OPA Control Plane).

---

Related reading

• Your First 10 Minutes · Onboarding Guide · Console Visual Reference
• EnforceAuth platform overview, Entity model, Policy sources, Bundle destinations, Deployments, API keys, Decision logs
• OPA vs EOPA, Application integration, PDP integration
• Continuous compliance, Audit evidence, Multi-environment best practices
• API Reference — api.enforceauth.com/docs