Chapter 13: Using policy engines with existing systems

Introduction

The introduction explains why ACME must modernize authorization as its internal collaboration platform becomes a multi-tenant SaaS service, while retaining its existing sharing model.

• Existing authorization migration challenge: Explain why ACME could not simply carry its existing authorization approach into C³, and why adopting a policy engine must preserve working workflows rather than replace everything at once.
  Why it matters: The reason for the migration explains why ACME builds on its existing system instead of replacing its sharing workflows.
• Platform and tenant authorization layers: Distinguish the new platform authorization layer from the existing tenant sharing model, explaining what changes and what remains in place for C³.
  Why it matters: Separating platform safeguards from tenant collaboration lets C³ support multiple customers without discarding its established sharing model.

Key terms: externalized authorization, policy engine, Customer Collaboration Cloud (C³), platform authorization layer, ReBAC, tenant workspaces, tenant isolation

13.1 From internal tool to external service: ACME’s next chapter

ACME’s internal collaboration tool becomes a multi-tenant cloud service that retains ReBAC sharing within a new, two-layer authorization architecture.

• Multi-tenant authorization requirements: Explain why customer requests changed ACME’s collaboration platform from an internal, single-tenant tool into a multi-tenant service, and what boundaries that change required.
  Why it matters: The new customer requirements explain why the original authorization setup was no longer enough.
• Platform and tenant authorization layers: Distinguish the platform and tenant authorization layers in C³, and explain how they preserve the original relationship-based sharing model.
  Why it matters: The two layers let ACME govern the cloud service without discarding useful collaboration permissions.

Key terms: single-tenant, multi-tenant, tenant, administrative boundary, platform authorization layer, tenant-level authorization, ReBAC, namespace

13.2 Understanding the starting point

The section explains why ACME’s project-ID checks were inadequate for a shared cloud service and how externalizing authorization would change its approach.

• Project ID boundary assumptions: Explain how project IDs served as informal workspace boundaries and why that approach worked while Customer Collaboration operated inside ACME’s trust boundary.
  Why it matters: The old checks made sense only under the operating assumptions ACME was about to leave behind.
• Limits of embedded authorization: Describe why project-ID checks embedded in individual services could not provide reliable tenant isolation or manageable access policy for C³ as a shared cloud service.
  Why it matters: This is why extending the old checks would not solve C³’s authorization problem.
• Externalized authorization shift: Explain the proposed shift from service-specific project-ID checks to structured authorization requests evaluated by a policy engine.
  Why it matters: It states the architectural change that addresses the old platform’s scattered checks.

Key terms: project_id, trust boundary, formal tenant model, tenant isolation, embedded in application logic, duplicate logic, opaque policy, externalizing authorization, structured authorization requests, policy engine

13.3 Identity and tenancy foundation for C³

ACME’s move to a multi-tenant Customer Collaboration Cloud requires an identity and tenancy foundation before it can create new policies.

• Separate identity and tenancy: Explain why ACME could not carry over its internal approach of storing identity and project membership together, and why tenancy must become an enforceable boundary in C³.
  Why it matters: Policy decisions depend on a sound distinction between a person’s identity and the tenant boundary that governs access.
• Customer-owned identity providers: Explain why C³ must accept identity from tenants’ own identity providers instead of making tenants depend on ACME’s identity system.
  Why it matters: External identity lets customers use C³ without relying on ACME to administer their users.

Key terms: identity, tenancy, multi-tenant environment, enforceable boundary, identity providers, ACME’s identity system, administrative dependency

13.3.1 From project IDs to tenants

This section explains how C³ replaces project IDs with explicit tenant boundaries that authorization can enforce.

• Enforceable tenant boundary: Explain how C³ changes tenancy from a project-ID convention into an authorization boundary by scoping principals, resources, relationship graphs, policy bundles, and audit records to a tenant.
  Why it matters: Tenant isolation becomes an authorization rule rather than merely an application convention.
• Three tenant elements: Describe the three elements ACME gives each C³ tenant: a globally unique tenant_id independent of database keys, a namespace for entities, relationships, and policies, and a tenant-directory record for ownership, configuration, and identity-provider metadata.
  Why it matters: These elements give each tenant a distinct identity, policy namespace, and configuration record.

Key terms: project IDs, tenant_id, authorization model, tenant, namespace, tenant directory

13.3.2 Unified customer identity via OIDC

C³ uses OIDC for customer authentication, gives both customer identity modes a common token shape, and obtains changing authorization data from PIPs.

• Customer OIDC identity modes: Explain why ACME uses OIDC for customers and distinguish C³’s federated and hosted identity modes.
  Why it matters: The two modes accommodate different tenants without making customer authentication part of ACME’s internal identity system.
• Common token identity mapping: Describe what both OIDC modes put in tokens and how those values help the PEP identify a caller and map them to a Cedar entity.
  Why it matters: A common token shape gives the PEP a consistent way to identify customer callers across both modes.
• Current authorization data from PIPs: Explain why C³ keeps dynamic or high-cardinality customer data out of tokens and where it obtains that data during evaluation.
  Why it matters: Keeping changeable data out of tokens avoids making access decisions from outdated directory snapshots.

Key terms: OpenID Connect (OIDC), Federated OIDC, Hosted OIDC, identity provider, tenant directory, tokens, sub, iss, aud, tenant_id

13.3.3 Device posture for ACME employees

This section explains why ACME checks device posture for its own employees but not for tenant customers, and how employee posture informs platform authorization.

• Managed device posture boundary: Explain why ACME can require device posture tokens from employees but not from tenant customers.
  Why it matters: It keeps ACME’s device requirements within the boundary of devices it actually manages.
• Employee posture in authorization: Describe how the PEP uses an employee’s identity and device posture tokens, and how the resulting context supports platform policies.
  Why it matters: It shows how ACME can enforce a zero-trust baseline for sensitive operations without checking customer-managed devices.

Key terms: device posture, posture tokens, signed compliance attestations, PEP, OIDC token, signed posture token, platform policies, tenant-scoped authorization model

13.4 Designing for externalized authorization

C³ moves authorization decisions out of application code by having PEPs construct requests for PDPs, which evaluate platform and tenant rules.

• PEP as authorization broker: Describe how a C³ PEP sits between an application and the policy engine, preparing a normalized authorization request so each service need not understand Cedar.
  Why it matters: This separates application enforcement from policy evaluation without making every service understand Cedar.
• Initiating authority in requests: Explain why C³ authorization must reflect the initiating principal’s authority rather than merely a service’s ability to reach a resource, and identify the PARC information carried in the request.
  Why it matters: Keeping the caller’s authority in the decision helps prevent a service from acting as a confused deputy.
• Platform and tenant evaluation: Describe the two layers in which C³ evaluates a constructed authorization request and what each layer governs.
  Why it matters: The two layers distinguish cloud-wide constraints from a tenant’s collaboration rules.

Key terms: PEP, PDP, normalized authorization request, authority context, confused deputy problem, initiating principal, PARC, tenant, context, platform rules

13.4.1 Platform and tenant PDPs

This section explains how C³ separates platform-wide authorization from tenant-specific collaboration decisions.

• Platform and tenant PDP roles: Explain what each PDP decides, why platform rules are checked first, and who governs each layer.
  Why it matters: The separation lets tenants control collaboration without overriding ACME’s platform protections.

Key terms: C³ PDP, tenant PDPs, platform policies, tenant’s namespace, ReBAC graph

13.4.2 Deployment options for tenant PDPs

ACME offers shared and dedicated tenant PDP deployments while preserving tenant isolation and a consistent division between platform governance and collaboration decisions.

• Shared PDP tenant isolation: Explain how ACME uses a shared PDP cluster for most tenants while keeping each tenant’s authorization data isolated.
  Why it matters: Sharing a PDP cluster does not mean sharing tenants’ authorization data.
• Dedicated PDP deployment choices: Describe what dedicated tenant PDPs offer premium tenants and which architectural constraints remain in place.
  Why it matters: A dedicated deployment gives a tenant more control without removing ACME’s platform-level rules.

Key terms: shared PDP cluster, tenant’s namespace, tenant_id, policy bundle, dedicated PDP instances, shared schema, platform policies, approved templates, C³ PDP

13.4.3 Authorization request flow

Traces a C³ authorization request through global and tenant policy checks, then explains why the example uses two layers rather than one unified policy stack.

• Two-layer authorization request flow: Trace a C³ request from the client through gateway normalization, global policy enforcement, tenant policy enforcement, and authorized processing. Explain that a forbid at either layer stops the request and that both layers record decisions.
  Why it matters: The two checks let C³ enforce platform governance without losing tenant-specific control over sharing.
• Split versus unified policy stack: Distinguish C³’s two-layer example from a feasible single-PEP, single-PDP design, including what each C³ layer governs and why a unified design may be attractive.
  Why it matters: The diagram illustrates distinct responsibilities, not a rule that every deployment needs two policy engines.

Key terms: C³, global PEP, C³ PDP, tenant PEP, tenant PDP, PARC, global PEP/PDP pair, tenant-specific PEP/PDP pairs, unified policy layer, tenant_id

13.5 Policy enforcement points in the stack

C³ places policy enforcement at multiple points in the stack so requests are covered with the right context, while backend decisions remain authoritative.

• Layered enforcement placement: Explain why C³ places policy enforcement points both at the platform edge and inside collaboration services, and what each location protects.
  Why it matters: Where enforcement happens determines which requests a layer can stop and what context it can use.
• UI and backend authority: Distinguish the UI’s use of policy information from authoritative backend enforcement.
  Why it matters: What the interface shows is not the final authority over access.

Key terms: PEPs, platform edge, collaboration services, request path, UI, policy information, backend enforcement

13.5.1 Global enforcement: The ACME gateway

This section explains how the ACME gateway enforces platform-wide requirements before requests reach tenant services, and why tenant-level checks remain necessary.

• Gateway authorization flow: Trace how the gateway verifies a caller, establishes tenant scope, obtains a global policy decision, and forwards a permitted request.
  Why it matters: This flow shows what must happen before a request can proceed to a tenant environment.
• Global and tenant check boundary: Explain why the gateway handles platform-wide enforcement and why document-level collaboration checks happen closer to tenant services.
  Why it matters: The gateway's position makes global checks effective, but it does not replace checks that need tenant-specific relationships.

Key terms: OIDC tokens, device posture tokens, tenant context, C³ PDP, normalized authorization context, edge enforcement point, platform-wide requirements, relationship context, document-level collaboration decisions

13.5.2 Tenant-level enforcement: Collaboration services

Tenant collaboration services enforce fine-grained access after the platform gateway, using tenant-specific decisions and data close to the protected operation.

• Tenant service enforcement flow: Trace how a collaboration service PEP handles a protected operation: it maps the application action to a Cedar action, asks the tenant PDP for a decision, and proceeds only if the result is permit.
  Why it matters: The service must enforce the tenant’s decision before carrying out an operation on its data.
• Service placement benefits and costs: Explain why PEPs in collaboration services can make fine-grained decisions with richer context and lower latency than gateway-only enforcement, and describe the resulting need for consistent service integration.
  Why it matters: Moving enforcement close to data improves decisions only if services apply policy consistently.

Key terms: PEP, tenant PDP, Cedar policy actions, ReBAC policies, permit, service PEPs, richer context, lower latency, service integration

13.5.3 UI and client-side enforcement

Explains how C³ uses authorization decisions to make its UI useful and its access lists accurate without treating client-side behavior as security enforcement.

• UI visibility versus enforcement: Distinguish the UI’s use of authorization information from security enforcement: it hides or disables actions the backend would deny, but protected operations still pass through a gateway or service PEP.
  Why it matters: A hidden button is helpful to users, but it is not an access-control boundary.
• Relationship graph candidate searches: Describe how C³ starts an access-list query with candidates from the tenant’s ReBAC graph, traversing from a principal toward resources or from a resource toward connected principals.
  Why it matters: Graph search makes access discovery possible without mistaking a list of relationships for a final policy decision.
• Static policy scope prefilter: Explain how C³ uses information known when a policy is published to produce a simplified scope and prefilter graph candidates before PDP evaluation.
  Why it matters: Filtering on known conditions keeps large discovery queries efficient without presenting the prefilter as a complete authorization decision.
• PDP confirmation and listable exception: Trace how C³ confirms remaining candidates with the tenant PDP, and distinguish that step from the purely relational cases it designates listable.
  Why it matters: Final confirmation prevents a plausible graph match from appearing in the UI when live policy conditions would deny it.
• Responsive and consistent access lists: Describe the practices C³ uses to keep large access-list queries responsive while reflecting current policy decisions, including how it checks administrative access questions.
  Why it matters: Fast lists are useful only if they remain consistent with what people could actually access.

Key terms: UI, gateway, service PEP, backend enforcement, ReBAC graph, candidate principals or resources, discovery questions, partial evaluation, policy residual, scope prefilter

13.5.4 Consistency through shared components

This section explains how shared components keep authorization requests consistent across C³’s distributed enforcement points.

• Consistent distributed enforcement: Explain how a shared request-building library keeps gateway, service, and UI enforcement aligned, and why that consistency matters.
  Why it matters: A decision at the gateway, in a service, or in the UI should reflect the same understanding of who is acting and what they are accessing.

Key terms: shared components, request-building library, PEPs, principal, action, resource

13.5.5 Operational tradeoffs

Compares the operational strengths of gateway, service, and UI enforcement in C³ and explains why the layers work together.

• Complementary enforcement layers: Explain how each enforcement layer’s place in the stack shapes what it can do: gateway PEPs protect platform boundaries early, service PEPs use resource context for fine-grained rules, and UI enforcement improves usability without replacing backend checks.
  Why it matters: Choosing where to enforce a decision depends on what that layer can see and protect.

Key terms: gateway PEPs, service PEPs, UI enforcement, platform boundary, resource context

13.5.6 Three layers of policy

C³ separates policies by scope and ownership so tenants can customize collaboration without gaining control over platform rules.

• Three policy layers: Distinguish C³’s system, global application, and tenant policies by what each governs.
  Why it matters: The layers clarify which rules apply to platform operations, the service as a whole, and collaboration within a tenant.
• Tenant customization boundaries: Explain who controls the policy layers and why that division matters for tenant customization.
  Why it matters: Clear ownership lets C³ support tenant-specific rules while retaining control of platform-wide decisions.

Key terms: system policies, global application policies, tenant policies, ReBAC, scope, ownership, tenant customization, platform authority

13.5.7 Shared schema and type safety

This section explains how a shared Cedar schema, prepublication checks, and controlled templates let C³ tenants customize authorization without weakening platform constraints.

• Shared authorization schema: Explain how one Cedar schema gives system, application, and tenant policies a common set of entity types, actions, attributes, and relationships, while preventing tenant policies from redefining that model or bypassing platform constraints.
  Why it matters: A common schema lets tenants express their own restrictions without changing what the platform’s policies mean.
• Prepublication policy checks: Describe how ACME validates policies against the shared schema and tests them with representative data before publication, and what kinds of problems those checks catch.
  Why it matters: Checking policies before publication reduces the chance that a tenant customization will fail at runtime.
• Template bounded tenant control: Distinguish C³’s product-level customization templates from tenants editing Cedar directly: describe what the tenant configures, what the policy service generates, and what ACME controls before publication.
  Why it matters: Templates give tenants useful choices while keeping policy structure and platform guardrails under ACME’s control.

Key terms: shared Cedar schema, entity types, action names, tenant namespace, shared schema, representative data, type errors, invalid attributes, policy template, parameter value

13.5.8 Policy life cycle and distribution

This section explains how ACME creates, validates, scopes, distributes, audits, and rolls out policies for shared and dedicated PDPs.

• Controlled policy creation and validation: Describe who develops system, application, and tenant policies, and how ACME checks each policy before publication.
  Why it matters: These checks help prevent unreviewed or invalid policies from reaching PDPs.
• Scoped storage and PDP distribution: Trace how ACME stores policies by scope and delivers the relevant bundle to each PDP.
  Why it matters: Scoping and distribution let different PDP deployments receive the policies relevant to their decisions.
• Policy traceability and rollback: Explain how policy identifiers, versions, and decision logs support investigation and rollback.
  Why it matters: When a decision is questioned, ACME can identify the policy version involved rather than guessing which rules were active.
• Staged updates and policy authority: Describe how validated changes reach different tenants and which policies remain authoritative.
  Why it matters: Different rollout schedules do not change which platform policies govern access.

Key terms: approved templates, shared schema, validation, central policy repository, tenant_id, policy distribution service, policy bundle, PDP, policy_id, version

13.5.9 Governance and safety

This subsection explains how C³ lets tenants customize access without overriding ACME’s higher-level safeguards.

• Tenant policy safety boundaries: Explain why tenant policies can restrict access but cannot permit an action forbidden by system or application policies, and how Cedar’s default-deny model supports that boundary.
  Why it matters: Tenant customization must not undermine compliance, support-access controls, data residency, or tenant isolation.

Key terms: tenant policies, system or application policies, default-deny model, higher-level guardrails

13.5.10 Benefits of the layered model

This section explains how C³’s layered authorization model separates platform and tenant responsibilities while preserving shared auditability and policy-as-code controls.

• Platform and tenant authority: Distinguish ACME’s authorization responsibilities from tenants’ responsibilities in C³.
  Why it matters: Clear authority boundaries let tenants customize collaboration without taking control of platform-wide protections.
• Shared foundations for auditing: Explain how shared foundations let ACME audit layered authorization decisions without assigning every policy to one owner.
  Why it matters: Common policy and logging foundations make decisions traceable even when different parties govern different policies.
• Policy-as-code for tenant customization: Describe how existing policy-as-code practices extend to C³’s controlled tenant customization.
  Why it matters: Tenant-specific policies remain subject to the same managed practices as platform policies.

Key terms: layered model, tenant boundaries, namespaces, approved configuration options, schema, policy repository, validation process, logging format, tenant_id, policy_id

13.6 Case studies inside ACME

Introduces ACME’s pilot case studies, each testing a different boundary of its two-layer authorization model.

13.6.1 Case 1: Cross-tenant legal review

This case shows how layered policies let ACME’s legal team review documents across customer tenants without granting broad access or building tenant-specific workflows.

• Cross-tenant review checks: Trace how a legal review request reaches the policy decision point and describe the system and application policy checks that limit access.
  Why it matters: These checks show how an employee can work across tenants without receiving unrestricted access to their documents.
• Layered policy tradeoff: Explain why keeping the legal-review checks in layered policy is preferable to broad platform access or separate workflows for each tenant.
  Why it matters: The case illustrates the operational and security reasons to enforce cross-tenant limits through shared policy.

Key terms: PEP, C³ PDP, system policy, application policy, compliant devices, metadata, layered architecture, data residency, compliance boundaries, overreach risk

13.6.2 Case 2: Support escalation

The section shows how ACME grants temporary, approved support access to a customer tenant while enforcing its scope through policy.

• Support escalation request flow: Trace how a support engineer requests access, receives an approved short-lived credential, and has a later request evaluated by system policies and the tenant PDP.
  Why it matters: The sequence shows that approval starts an escalation but does not bypass authorization when the engineer uses it.
• Time-limited policy enforcement: Explain how the escalation uses credential attributes and policy checks to limit access by tenant and time, and why expiration ends access without manual cleanup.
  Why it matters: Policy checks and expiration keep temporary access bounded without relying on someone to revoke it manually.
• Delegated authority boundary: Explain why the support portal’s permission to request an escalation and the support tools’ ability to reach resources do not themselves authorize the engineer’s access.
  Why it matters: The boundary prevents a support system’s broad capabilities from becoming unintended authority over customer resources.

Key terms: support portal, delegated access, short-lived credential, PEP, PARC authorization request, system policies, ABAC, time-limited, attribute-based access, confused-deputy failures

13.6.3 Case 3: Custom collaboration template

A customer uses a tenant-specific policy template to extend collaboration to outside contractors while ACME retains application-level safeguards.

• Bounded tenant collaboration rules: Explain how the customer’s customized rule supports collaboration with outside contractors without full tenant membership, and how ACME’s policies continue to constrain it.
  Why it matters: It shows how customer-specific access can coexist with safeguards that the customer cannot set aside.

Key terms: policy-template system, tenant administrator, collaborator, Cedar rule, tenant’s dedicated PDP, application-layer policies

13.6.4 Case 4: Automated backup verification

This case shows how C³ authorizes a nightly backup process outside the tenant scope while keeping it within the platform’s auditing and governance framework.

• Backup Service Authorization: Trace how C³ authorizes its nightly backup service: a system PEP authenticates the backup agent with a service credential, and a system PDP evaluates a policy granting read-only access to encrypted tenant metadata for audit and restore testing. Explain how the shared schema keeps the process within the same policy syntax and logging pipeline despite its running outside the tenant scope.
  Why it matters: Automated platform jobs need bounded, auditable access even when they do not pass through tenant enforcement points.

Key terms: system PEP, service credential, system PDP, shared schema, logging pipeline

13.6.5 Lessons from the pilots

The section draws lessons from ACME’s pilots and shows that layered, externalized authorization applies across trust boundaries beyond multi-tenant SaaS.

• Purpose of each policy layer: Explain how distinct policy layers let ACME govern cross-tenant authority while allowing tenant collaboration and customization, and how shared schemas and logs make decisions traceable.
  Why it matters: Clear responsibilities let tenants customize access without losing platform control or the ability to trace a decision.
• Authorization beyond SaaS tenancy: Explain why ACME’s externalized authorization architecture also applies outside SaaS, and distinguish what stays the same from what changes between its ABAC and ReBAC uses.
  Why it matters: The same architecture can govern different kinds of access without being tied to customers or one authorization model.

Key terms: platform policies, tenant policies, templates, shared schemas, logs, externalized authorization, trust boundaries, ABAC, ReBAC, PDPs

13.7 Putting lessons into practice

C³’s migration provides a flexible integration pattern for policy engines and shows why externalized authorization requires operational coordination and governance.

• Coherent policy engine integration: Describe the decisions in ACME’s repeatable pattern for integrating a policy engine into an existing system, without treating the sequence as a rigid deployment plan.
  Why it matters: The pattern helps keep authorization coherent as an existing system adopts a policy engine.
• Operational dependencies and governance: Explain why adopting a policy engine creates a governance challenge rather than only a code change.
  Why it matters: A working policy engine still needs people and processes to keep its decisions trustworthy over time.
• Benefits of separating policy: Explain what ACME gained by treating authorization as part of system design and separating policy from code.
  Why it matters: These benefits explain why ACME made authorization a first-class design concern during its move to a multi-tenant platform.

Key terms: policy engine, identity model, enforcement points, schemas, visibility queries, auditable, operational dependencies, governance, policy layer, signals

13.8 Summary