EnforceAuth Onboarding Guide

This guide takes you from "I have an EnforceAuth account" to "I have a production-ready system with policies flowing dev → staging → prod, telemetry coming back, and my team in the console." Plan on 1–2 hours for a real setup (versus 10 minutes for a throwaway demo — for that, see Your First 10 Minutes).

It follows the product's actual onboarding wizard and then the platform's real objects. Where a step is a one-time account action, it's marked [once per tenant]; where it repeats per application, it's marked [per system].

What you'll accomplish

Complete the onboarding wizard (org info, contacts, review, MSA, confirmation)
Understand and lay out your entity tree (organizations + systems)
Connect a Git policy source and a bundle destination
Store secrets, mint API keys and CI/CD tokens
Run your first deployment and set up dev → staging → prod promotion
Point a PDP (OPA or EOPA) at your bundles and confirm decision logs
Invite your team and set up users, groups, and roles
Turn on automation (GitHub Actions) and integrations (MCP, CI providers)

Part 0 — Before you begin

Decide your PDP: OPA or EOPA [once per tenant]

Do this first — it colors later choices. Default to OSS OPA. Choose EOPA only for a concrete need: decision-log masking at the PDP before logs leave your network, delta bundles at very large fleet scale, or bundle partitioning. Same Rego, same bundles, same pipeline either way. Full decision matrix: OPA vs EOPA.

Gather prerequisites

You'll need	For	Notes
A Git repo with Rego (a `package` + an `allow` rule)	Policy source	Or use EACommerce to start
An S3 / GCS / Azure Blob location EnforceAuth can write	Bundle destination	Git-output destination works too
Ability to run/config OPA or EOPA	The PDP that enforces	Your infra
Admin rights in your GitHub org	To install the EnforceAuth GitHub App	For repo read + Actions
`eactl` (optional)	CLI ops + diagnostics	`brew install enforceauth/tap/eactl`

Part 1 — The onboarding wizard [once per tenant]

The console's onboarding is a six-step wizard. Steps map to the real flow: welcome → setup-org → setup-contacts → setup-review → msa → confirmation.

Screenshots below are of the running console (Entity Management, Deployments, etc.). The wizard steps are documented from the product's onboarding flow; capture live wizard screenshots on a fresh tenant, since an already-bootstrapped tenant skips straight to the Dashboard.

Step 1 — Welcome

Read the summary of what you're setting up. This is also where you pick your implementation style:

SaaS — EnforceAuth-hosted control plane (most teams).
On-premises — control plane in your environment (enterprise).

Step 2 — Organization info (`setup-org`)

Fill in your organization details:

Organization name — becomes your tenant-scoped root entity.
Industry — technology, healthcare, finance/banking, education, retail/e-commerce, government, manufacturing, or other. (Used for tailoring and compliance framing.)
Access tier — free, starter, or an enterprise tier (enterprise-t1/t2/t3) up to unlimited. Start where your plan sits; this can change with your account team.

Step 3 — Contacts (`setup-contacts`)

Add the people EnforceAuth should know:

Primary contact — name, title, email, phone (with country code).
Optionally indicate whether a sales contact may reach out. These drive account communication and support routing — get them right.

Step 4 — Review (`setup-review`)

Confirm everything from Steps 2–3 on one screen. Edit anything that's off before continuing. What you approve here is exactly what gets provisioned.

Step 5 — MSA (`msa`)

Review and accept the Master Service Agreement / terms.

Accepting terms is a decision only an authorized person at your company should make. If you're setting up on someone else's behalf, route the MSA to whoever owns contracts before accepting. Do not accept terms you're not authorized to accept.

Step 6 — Confirmation (`confirmation`)

Your tenant is provisioned. You now have a root Organization and can enter the console proper.

Verify: you can reach the Dashboard and open System Settings → Entity Management and see your root org (it shows a Root badge; root entities can't be deleted). ✅

Part 2 — Design your entity tree [once per tenant, then per system]

Everything in EnforceAuth hangs off the entity tree. Get the shape right before you wire config, because config inherits down the tree.

The two entity types you create

Type	Use it for
Organization	Your root, plus intermediate grouping nodes (by business unit, product line, or environment strategy). Holds global default policy source, bundle destination, and environments.
System	A single application or service boundary — the deployable unit that receives bundles and emits decision logs.

The API also has user entities for identity-graph use cases, but the console's create form offers Organization and System only. Stick to those.

Rules that shape your design

Every entity except the tenant root must have a parent. You can't create new root orgs after setup ("New root entities can only be created during tenant setup").
Root orgs can't be deleted.
Children inherit effective config from ancestors unless they override it. Inherited cards show a dashed border and "Inherited from parent"; empty overridable fields show "Will inherit from parent".

A good starting shape

Acme (root org)                    ← put shared Git + storage + environments here
├── Payments (org)                 ← business-unit grouping (optional)
│   ├── payments-api (system)      ← deployable
│   └── payments-worker (system)   ← deployable
└── Platform (org)
    └── gateway (system)

Put shared policy source and bundle destination on Acme (or on the business-unit org). Individual systems inherit and only override what's genuinely different (e.g. a different policy_path or a per-system bucket path).

Create it

Entity Management table

System Settings → Entity Management (/system-settings/entities).
Create Entity for any intermediate orgs (set Parent Entity to the root).
Create each deployable app as a System with the right org as its Parent Entity.
Use the Table view to scan relationships and the Graph view to sanity-check hierarchy. The page subtitle shows org/system counts.

Create Entity form

Verify: your systems appear under the right parents; the entity detail page shows correct Path to Root, Parents, and Children. ✅

Part 3 — Wire configuration on the entity [per system, or once on a shared org]

Open an entity → Configuration. Three config kinds drive deployments.

3a. Policy source (Git)

First authorize GitHub: System Settings → Integrations → Connect GitHub installs the EnforceAuth GitHub App so policy sources can read private repos without per-user PATs (github.com and GitHub Enterprise Server).
On the entity's Policy Source, click Configure and select the repo, branch, and policy_path (the folder containing your Rego package).

Integrations — Connect GitHub

On deploy, EnforceAuth clones the repo, runs opa test, and builds the bundle. Set this on a parent org if multiple systems share one policy repo; override branch/policy_path per system as needed.

3b. Bundle destination

Where PDPs fetch bundles. Pick one:

S3 / GCS / Azure Blob — provide bucket/container + path.
Git output — write the built bundle back to a repo/branch.

System-level note in the UI: If blank, inherits from parent organization. Use per-environment path overrides so dev, staging, and prod bundles don't collide (e.g. .../dev/bundle.tar.gz).

3c. Environments

Map environment names to promotion targets. The standard chain is dev → staging → prod. Each environment can carry its own branch/path or destination override. This is what makes promotion meaningful — a bundle proven in dev is promoted, not rebuilt, into staging then prod.

Verify: the entity's Configuration shows a resolved Policy source, Bundle destination, and at least dev/staging/prod environments (directly set or inherited). ✅

Part 4 — Secrets, API keys, and CI/CD tokens [per entity]

On the entity detail page — the Secrets, API Keys, and CI/CD Tokens tabs:

Entity detail tabs: Relationships, Configuration, Secrets, API Keys, CI/CD Tokens

Section	What goes here	When
Secrets	Git credentials, cloud-storage keys	Whenever a source/destination needs auth
API Keys	Service identity a PDP uses to send decision logs; scoped to the entity	Before you start a PDP that reports telemetry
CI/CD Tokens	Pipeline auth for automated deploys (GitHub Actions / `eactl` in CI)	When you turn on automation (Part 7)

API key hygiene:

Scope each key to the narrowest entity that needs it.
Copy it at creation — it's shown once. Store it in your own secret manager, not in plaintext config committed to Git.
Rotate on a schedule and immediately if exposed. See API keys for PDP config and rotation.

Never paste live API keys, cloud keys, or tokens into a shared doc, ticket, or chat. Put them in your secret manager and reference them.

Verify: the entity lists at least one API key; your secret manager holds the value. ✅

Part 5 — First deployment and the promotion chain

Run the first deploy (dev)

Deployments page

Go to Deployments → Deploy.
Trigger a deployment for your system in dev.
Track the run through its phases: test (opa test) → build (bundle) → publish (to destination).

If it fails, use eactl diagnose:

eactl diagnose preflight — end-to-end check of the whole setup
eactl diagnose permissions — destination write access
eactl diagnose secrets — credential resolution
eactl diagnose runs — inspect recent pipeline runs

Promote dev → staging → prod

Once dev is green and validated:

From the deployment/Deployments page, promote the successful bundle to staging.
Validate in staging (run your PEP integration tests, check decision logs).
Promote to prod.

Promotion moves the same tested artifact forward — you're not rebuilding, so prod runs exactly what staging proved. If a promotion goes wrong, use restore/rollback to return the environment to the previous good bundle. See Deployments and Multi-environment best practices.

Verify: Deployments shows successful runs in each environment; prod has an active bundle. ✅

Part 6 — Point your PDP at EnforceAuth and confirm telemetry

Configure your OPA/EOPA instances with a services block pointing at the bundle destination for their environment, and a decision_logs block pointing at EnforceAuth authenticated with the entity's API key. Copy the exact block from the API Keys / Decision logs pages — it's pre-filled with your URLs.
Wire your application's PEP to query the PDP for authorization decisions (this is your app calling OPA, not EnforceAuth). See Application integration and PDP integration.
Send real traffic (or test traffic).

Verify: the Decisions page shows decision logs for the system, with input, result, and source. ✅

Part 7 — Automate deployments [per system]

GitHub Actions

Add the EnforceAuth deploy-action to your policy repo's workflow.
Authenticate it with a CI/CD token (Part 4) stored as a GitHub Actions secret.
On merge to your policy branch, the Action runs the pipeline and deploys — no manual trigger.

See GitHub Actions and CI/CD. Configure branch → environment mapping so main deploys dev (or prod, per your policy).

The CLI

eactl pipeline runs the same test → build → deploy from any CI or locally; eactl pipeline serve runs a local dev server that mirrors the pipeline API.

Verify: a merge to the policy repo produces a new deployment in Deployments without anyone clicking "deploy." ✅

Part 8 — Bring in your team [once per tenant]

System Settings → User Management (tabs: Groups · Users · Invitations · Audit trail):

User Management

Users → Add User — invite teammates by email (or Bulk Import many). Invitations arrive via the Accept Invitation / Join Organization flow and appear under the Invitations tab.
Groups — group users and assign access so permissions scale with the org rather than per-person.
Assign least-privilege roles: policy authors, deployers, and read-only/compliance viewers get different access. Compliance/audit users typically need Decisions and the Audit trail — not deploy rights.

Verify: at least one teammate has accepted an invitation and can sign in with the intended access. ✅

Part 9 — Integrations and optional wiring

Under System Settings:

Integrations — Connect GitHub (the EnforceAuth GitHub App) so policy sources read private repos without per-user PATs.
Functionality Management — tenant-wide feature flags. Treat broad flag changes as a security-relevant action — enable narrowly, not everything at once ("Reverting an override falls back to the platform default").
MCP for AI agents — EnforceAuth ships an MCP server to expose policy/authorization context to agents. A Connect MCP card wasn't visible in the portal for this tenant (likely flag-gated); confirm the live route before enabling, and only for agents you trust.

Onboarding completion checklist

Where to go next

User Guide — full task reference for every console area and eactl.
Multi-environment best practices — promotion, overrides, and safe rollback.
Continuous compliance & Audit evidence — turn decision logs into audit-ready evidence.
Testing policies — make opa test a real gate before deploys.
Migration guides — coming from Styra DAS™ / EOPA or OPA / OCP.

What you'll accomplish​

Part 0 — Before you begin​

Decide your PDP: OPA or EOPA [once per tenant]​

Gather prerequisites​

Part 1 — The onboarding wizard [once per tenant]​

Step 1 — Welcome​

Step 2 — Organization info (setup-org)​

Step 3 — Contacts (setup-contacts)​

Step 4 — Review (setup-review)​

Step 5 — MSA (msa)​

Step 6 — Confirmation (confirmation)​

Part 2 — Design your entity tree [once per tenant, then per system]​

The two entity types you create​

Rules that shape your design​

A good starting shape​

Create it​

Part 3 — Wire configuration on the entity [per system, or once on a shared org]​

3a. Policy source (Git)​

3b. Bundle destination​

3c. Environments​

Part 4 — Secrets, API keys, and CI/CD tokens [per entity]​

Part 5 — First deployment and the promotion chain​

Run the first deploy (dev)​

Promote dev → staging → prod​

Part 6 — Point your PDP at EnforceAuth and confirm telemetry​

Part 7 — Automate deployments [per system]​

GitHub Actions​

The CLI​

Part 8 — Bring in your team [once per tenant]​

Part 9 — Integrations and optional wiring​

Onboarding completion checklist​

Where to go next​