You are reading Nightly documentation for 0.12.4.dev0+g50bde75.

This documentation may describe behavior that differs from Stable.

Open Stable documentation

Documentation version

0.12.4.dev0+g50bde75 · Nightly
Stable Beta Nightly

Organization governance

Organization governance

Organization governance adds enterprise identity, tenant scope, role-based access, organization
policy, retention/legal-hold planning, and tamper-evident audit to Holaryn Agent. It is an additional
security layer; it does not replace the local sandbox, autonomy posture, approval gate, or
information-flow protections.

Most standalone installations will initially show Settings -> Organization Governance ->
Organization governance is not active. That is expected. Holaryn does not invent an organization
identity or silently enroll your local agent. An enterprise deployment must attach its identity,
directory, policy, and audit services.

What appears when it is active

The page shows:

  • your authenticated principal and authentication strength;
  • the organization/workspace/project/run scope carried by this session;
  • active roles and effective permissions;
  • every policy bundle version and its draft, staged, active, or retired state;
  • a simulator that explains allow/review/deny without executing an action; and
  • the audit chain's verification result, record count, head hash, and export control.

These details are evidence, not a new source of authority. The server computes them from the
authenticated context and active policy.

Roles and policy

Roles grant the maximum permission a principal may use at a scope. Policy can narrow that maximum.
The decision order is:

  1. tenant scope must match;
  2. an active role must grant the permission;
  3. any matching deny wins;
  4. review may be satisfied only by a scoped, unexpired administrator exception;
  5. otherwise a matching review asks for one-action approval;
  6. a matching allow permits policy evaluation to continue; and
  7. the bundle default applies.

An organization-policy allow never turns off your local approval posture. A policy deny cannot be
overridden from the approval dialog.

Safely changing policy

Policy changes use real version history:

  1. Start from the JSON template under New draft policy.
  2. Keep an explicit administrator allow rule. Without it you may need local recovery to fix a
    lockout.
  3. Change the version, selectors, effects, reason codes, and change note.
  4. Choose Propose draft. The server validates tenant ownership, identity, bounds, and selectors.
  5. Use Policy simulation against the draft. Test ordinary user actions, administrator actions,
    denies, review rules, and another-tenant scope through an integration test.
  6. Choose Stage version N. Staging does not affect live actions.
  7. After review, choose Activate version N.

To roll back, choose Roll back to version N beside a retired version. Holaryn creates and activates
a new version containing the old policy; it never rewrites history.

Reading a simulation

The result includes:

  • effect: allow, review, or deny;
  • reason codes suitable for support and automation;
  • whether RBAC granted the requested permission;
  • effective roles;
  • matching rule ids; and
  • the exact bundle id, version, and digest.

Simulation is itself an audited administrator action, but it never runs the action being simulated.

Audit verification and export

The local audit ledger links each canonical record to the previous record with SHA-256. The page
shows verified only when sequence, prior hash, and content hash all validate. A failed chain
becomes read-only.

Choose Export this scope to create a unique JSONL file beneath the host's controlled governance
export directory. The status message shows the exact local path and record count. A
workspace-scoped auditor cannot export a different workspace or omit the scope to get the full
organization.

The hash chain detects edits, gaps, and reordering. It is not a digital signature or WORM storage.
Organizations that need independent evidence should connect the audit sink to their SIEM/archive
and checkpoint the head hash using their KMS/HSM.

Session revocation and background work

When directory data changes or a user is revoked, Holaryn advances that principal's session epoch.
Foreground sessions, web chats, and delegated subagents then fail validation. Child work receives a
registered context that cannot widen the parent's tenant scope or expiry.

External job runners and managed connectors must implement the same revalidation contract in their
adapter. Do not treat possession of a queued task as permanent authorization.

The governance service can compute a deterministic deletion plan for primary and derived resources.
Legal hold wins before deletion, and primary deletion cascades to derived resources in stable order.
Your deployment must supply idempotent deleters and an absence verifier for every remote resource
kind it enables. The standalone agent does not guess how to delete an IdP object, external secret,
remote vector, or Platform resource.

If access is unexpectedly denied

  1. Read the policy reason codes in the transcript activity or simulator.
  2. Confirm the organization and workspace scope.
  3. Confirm the user's directory status, synchronized groups, and session expiry.
  4. Confirm an active role grants the permission.
  5. Check matching deny and review rules in the exact active policy digest.
  6. Verify the audit chain. Policy/audit failure intentionally blocks action.
  7. If the identity plane is unavailable, follow your organization's tested local-recovery runbook.

Do not delete or truncate the audit file to make the host writable. Preserve it and follow the
enterprise governance recovery and incident runbook.

← Previous First-success onboarding Next → Peers and networking