Chapter 10: Policy as code: Effective authorization policies
The introduction explains why ACME needs authorization policies that remain effective as systems and requirements change, and frames dependable policy around design, management, and assurance.
After this chapter you will be able to
- Durable policy design. Explain why a policy that works today may not remain effective as roles, projects, or compliance rules change, and describe the qualities ACME wants in its policies.
- Externalized authorization logic. Explain why ACME wants policies outside application code while keeping them precise enough for running systems to enforce.
- Dependable policy perspectives. Describe the three perspectives the introduction uses to frame dependable authorization policy: design, management, and assurance. Explain why decisions about authorship, review, and conflicts also matter to sustainability.
- Effective policy qualities. Explain why writing effective authorization policies involves more than encoding rules in Cedar, and describe the qualities ACME’s identity team sought.
- Consistent project-based policy scopes. Explain why ACME replaced a broad manager-based document policy with project-based scoping. Describe the conflicting answers the two approaches gave for a manager outside Project Alpha.
- Least-privilege policy scope. Explain why ACME’s all-employees document permission violated least privilege and how restricting access to project members addressed the problem.
- Policy logic versus changing facts. Explain why hard-coding department names made ACME’s deployment policy brittle and how referencing roles from HR and identity systems preserved its intent.
- Governance of policy data. Explain why separating policy from data also requires stewardship of the roles and other attributes a policy uses.
- Fine-grained policies and simple roles. Explain why ACME separated viewing, editing, and sharing in its policies while keeping a bundled collaborator role in the UI. Contrast the permissions this enables with the over-permissioning caused by the original doc:all action.
- Stable bases for access. Explain why ACME replaced an exact job-title check with legal-team membership for access to legal drafts.
- Secure and sustainable policy design. Explain why effective policies involve more than granting or denying access at one moment, and describe how the principles together support security and long-term sustainability.
- Repository and store responsibilities. Distinguish a policy repository from a policy store, including how ACME divided authoring and runtime responsibilities.
- Reviewed policy deployment path. Trace how ACME moves a policy change from a repository to a runtime store, and explain why it disallows direct store edits.
- Schema-backed policy consistency. Explain why ACME added Cedar schemas and how schema type-checking keeps policies consistent across repositories.
- Validation exposes model gaps. Describe how validation exposed the missing department attribute and led ACME to reconsider where organizational data belongs.
- Traceable policy change history. Explain how making policy changes through reviewed pull requests creates a record of when and why a policy changed, who approved it, and what was released.
- Business-level policy review. Describe how policy reviewers assess authorization intent and scope, not just syntax, and how different stakeholders contribute to that review.
- Authorization decision visibility. Explain how ACME used decision logs to identify the policy and condition behind a denial, and metrics to check authorization latency.
- Versioned policy bundle rollback. Describe how ACME recovered when a new deployment policy accidentally blocked weekend rollouts.
- Policy CI pipeline flow. Trace how a policy change moves from a pull request through automated checks, merging, bundle publication, and runtime use at ACME.
- Early errors and repeatable deployment. Explain the two benefits ACME gets from putting policy changes through this pipeline.
- Request-driven policy testing. Describe how to test a policy by sending a realistic authorization request to the PDP and comparing its decision with the expected result. Explain why both allowed and denied cases, realistic entity relationships, and automated checks matter.
- Static analysis alongside tests. Explain how Cedar Analysis complements request-driven tests by examining policy sets against the schema for structural problems.
- Three policy practice perspectives. Distinguish design, management, and assurance: design expresses the right access intent, management treats policies as code, and assurance checks their behavior before production.
- Dependable authorization decisions. Explain why ACME combines these practices: small policy mistakes can expose data or block work, while external, tested policies make allow-or-deny decisions clearer and aligned with business rules.
What it builds on
- From concept to policy (chapter 9) · Introduces the move from an authorization concept to a policy.
- Policy as Code (chapter 6) · Introduces Policy as Code.
- Authoring ACME’s core policies (chapter 9) · Introduces authoring policies in Cedar, which this section distinguishes from making policies effective.
- Applying Cedar’s policy patterns (chapter 9) · Assumes familiarity with expressing permissions through policy patterns.
- Modeling your schema first (chapter 9) · Uses the idea that a policy schema defines entities.
- Mapping requests to Cedar evaluations (chapter 9) · Introduces runtime Cedar evaluations that rely on deployed policies.
- How schema shapes policies (chapter 9) · The connection between a Cedar schema and the policies written against it.
Section by section
Introduction
The introduction explains why ACME needs authorization policies that remain effective as systems and requirements change, and frames dependable policy around design, management, and assurance.
- Durable policy design: Explain why a policy that works today may not remain effective as roles, projects, or compliance rules change, and describe the qualities ACME wants in its policies.
Why it matters: Access rules need to remain useful when the organization changes, not merely pass an initial check. - Externalized authorization logic: Explain why ACME wants policies outside application code while keeping them precise enough for running systems to enforce.
Why it matters: Separating policies from applications can make access rules easier to update while keeping them enforceable. - Dependable policy perspectives: Describe the three perspectives the introduction uses to frame dependable authorization policy: design, management, and assurance. Explain why decisions about authorship, review, and conflicts also matter to sustainability.
Why it matters: Policies become a dependable part of a system only when their design, handling, behavior, and oversight are considered.
Key terms: design artifacts, clear, consistent, resilient to change, authorization logic, externalized, real-time decisions, design, management, assurance
10.1 Principles of effective authorization policies
This section frames effective authorization policy as more than writing Cedar rules: policies must be understandable, resilient to change, and precise without obstructing business goals.
- Effective policy qualities: Explain why writing effective authorization policies involves more than encoding rules in Cedar, and describe the qualities ACME’s identity team sought.
Why it matters: These qualities provide a way to judge policies beyond whether their rules can be written in Cedar.
Key terms: dynamic authorization, Cedar, least privilege
10.1.1 Clarity and consistency
This subsection uses ACME’s document-access policies to show why consistent, project-based scoping makes authorization clearer and more predictable.
- Consistent project-based policy scopes: Explain why ACME replaced a broad manager-based document policy with project-based scoping. Describe the conflicting answers the two approaches gave for a manager outside Project Alpha.
Why it matters: Consistent scopes make access decisions easier to understand and less likely to produce conflicting expectations.
Key terms: scope, project membership, organizational role, project container
10.1.2 Least privilege
This section explains least privilege through ACME’s overly broad document-access policy and its project-scoped correction.
- Least-privilege policy scope: Explain why ACME’s all-employees document permission violated least privilege and how restricting access to project members addressed the problem.
Why it matters: Narrow policy scope keeps sensitive documents from reaching people who do not need them for their work.
Key terms: least privilege, all employees, project container, project members
10.1.3 Separation of policy and data
This section shows how separating authorization logic from changeable organizational facts makes policies more durable, provided the data they rely on is governed.
- Policy logic versus changing facts: Explain why hard-coding department names made ACME’s deployment policy brittle and how referencing roles from HR and identity systems preserved its intent.
Why it matters: Separating the rule from changing labels helps legitimate access survive reorganizations. - Durable entities and relationships: Describe how durable project entities and management relationships avoid tying access to changeable project codes or individual names.
Why it matters: The same design principle protects access rules from project renames and staff replacements. - Governance of policy data: Explain why separating policy from data also requires stewardship of the roles and other attributes a policy uses.
Why it matters: A well-written rule can still produce unreliable access decisions if its underlying data is poorly maintained.
Key terms: policy, hard-coded data, data driven, roles, project code, project entity, management relationship, relationship in a graph, durable roles, governed assets
10.1.4 Granularity and grouping
This section explains why authorization policies should distinguish individual actions even when the user interface groups them into simple roles.
- Fine-grained policies and simple roles: Explain why ACME separated viewing, editing, and sharing in its policies while keeping a bundled collaborator role in the UI. Contrast the permissions this enables with the over-permissioning caused by the original doc:all action.
Why it matters: Keeping policies more precise than UI roles makes access easier to manage without granting capabilities users should not have.
Key terms: fine-grained actions, doc:all, collaborator role, bundled action
10.1.5 Stability across change
The section shows how to keep authorization policies aligned with changing organizations and turns common policy mistakes into practical review criteria.
- Stable bases for access: Explain why ACME replaced an exact job-title check with legal-team membership for access to legal drafts.
Why it matters: Access should continue to match people’s responsibilities when organizational details change. - Common policy design pitfalls: Describe how least-privilege scope, shared policy logic, authoritative data, and consistent naming address the policy design pitfalls listed here.
Why it matters: These choices prevent broad grants, divergent checks, stale embedded data, and confusing policy names. - Validation and policy review: Describe how ACME uses validation, test requests, and review questions to catch policy mistakes before access problems arise.
Why it matters: Routine review and testing can reveal unintended access behavior before users encounter it.
Key terms: job title, volatile attribute, team membership, stable entities, least privilege, policies as code, authoritative systems, naming conventions, schema, test requests
10.1.6 From principles to practice
The section brings together five policy-design principles to show why effective authorization policies must remain secure and sustainable beyond an individual access decision.
- Secure and sustainable policy design: Explain why effective policies involve more than granting or denying access at one moment, and describe how the principles together support security and long-term sustainability.
Why it matters: A policy should work safely now without becoming fragile or unmanageable as circumstances change.
Key terms: least privilege, separation of policy and data, granularity and grouping, durable entities
10.2 Policy as Code in practice
ACME’s example shows why Policy as Code separates reviewed policy authoring from runtime execution and uses a controlled process to move changes between them.
- Need for consistent policy management: Explain why ACME replaced scattered, application-specific authorization rules with a policy-as-code approach.
Why it matters: The incident explains why changing individual rules was not enough. - Repository and store responsibilities: Distinguish a policy repository from a policy store, including how ACME divided authoring and runtime responsibilities.
Why it matters: Keeping authoring separate from execution gives teams a clear place to propose changes without turning the runtime store into an editing workspace. - Reviewed policy deployment path: Trace how ACME moves a policy change from a repository to a runtime store, and explain why it disallows direct store edits.
Why it matters: A controlled path makes production policy changes traceable and recoverable.
Key terms: Policy as Code, authorization rules, policy repository, policy store, Cedar authorizer, continuous integration, signed policy bundle, promote, roll back, drift
10.2.1 Schemas and validation
ACME uses Cedar schemas and validation to keep policies consistent and expose gaps in its authorization data model.
- Schema-backed policy consistency: Explain why ACME added Cedar schemas and how schema type-checking keeps policies consistent across repositories.
Why it matters: A schema gives teams a common vocabulary before their policies are combined. - Validation exposes model gaps: Describe how validation exposed the missing department attribute and led ACME to reconsider where organizational data belongs.
Why it matters: A validation error can reveal that the underlying data model needs attention, not just that a policy needs editing.
Key terms: Cedar schemas, principal types, resource types, actions, type-checked, validation, department attribute, principals, entity store, roles
10.2.2 Versioning and review
This section shows how version-controlled policy changes create an audit trail and how reviews improve authorization decisions.
- Traceable policy change history: Explain how making policy changes through reviewed pull requests creates a record of when and why a policy changed, who approved it, and what was released.
Why it matters: A traceable history lets a team answer an auditor's question with evidence of the decision and its limits. - Business-level policy review: Describe how policy reviewers assess authorization intent and scope, not just syntax, and how different stakeholders contribute to that review.
Why it matters: A policy can be syntactically correct yet grant access more broadly than intended.
Key terms: Git, pull request, signed, versioned bundle, reviewer comments, code reviews, business-level questions, intent, scope
10.2.3 Operational considerations
ACME uses centralized policy stores, decision logs, metrics, and versioned bundles to make authorization easier to diagnose, monitor, and recover when a policy change causes problems.
- Authorization decision visibility: Explain how ACME used decision logs to identify the policy and condition behind a denial, and metrics to check authorization latency.
Why it matters: Engineers could investigate access failures without first asking the identity team. - Versioned policy bundle rollback: Describe how ACME recovered when a new deployment policy accidentally blocked weekend rollouts.
Why it matters: A bad policy deployment need not remain in effect while the team diagnoses it.
Key terms: centralized policy stores, decision logs, decision_id, metrics, latency, versioned bundles, rollbacks, previous bundle
10.2.4 Continuous integration for policies
This section traces ACME’s CI pipeline from policy pull request to runtime use and explains how it catches errors early and makes deployment repeatable.
- Policy CI pipeline flow: Trace how a policy change moves from a pull request through automated checks, merging, bundle publication, and runtime use at ACME.
Why it matters: The pipeline connects reviewed policy changes to the policies actually used for access decisions. - Early errors and repeatable deployment: Explain the two benefits ACME gets from putting policy changes through this pipeline.
Why it matters: Early feedback and a consistent release process make policy changes easier to fix and manage.
Key terms: continuous integration (CI) pipeline, pull request, signed bundle, policy store, authorizer, policy errors, runtime failures, repeatable, reviewed source, version history
10.3 Testing policies effectively
The section explains how request-driven tests and static analysis work together to catch authorization-policy errors before deployment.
- Request-driven policy testing: Describe how to test a policy by sending a realistic authorization request to the PDP and comparing its decision with the expected result. Explain why both allowed and denied cases, realistic entity relationships, and automated checks matter.
Why it matters: A policy that compiles can still grant the wrong access or block legitimate work. - Policy test categories: Distinguish unit, scenario, and regression tests from coverage checks in ACME’s policy-testing approach.
Why it matters: Using several kinds of checks makes it less likely that an interaction, old bug, or untested rule will be overlooked. - Static analysis alongside tests: Explain how Cedar Analysis complements request-driven tests by examining policy sets against the schema for structural problems.
Why it matters: The two methods provide a stronger safety net together than either provides alone.
Key terms: principal, action, resource, request context, entity data, PDP, unit tests, scenario tests, regression tests, coverage checks
10.4 Pulling it together
This section brings together policy design, management, and assurance as the practices that make authorization decisions dependable.
- Three policy practice perspectives: Distinguish design, management, and assurance: design expresses the right access intent, management treats policies as code, and assurance checks their behavior before production.
Why it matters: A policy can express the right rule yet still be unreliable if its changes and behavior are not managed and checked. - Dependable authorization decisions: Explain why ACME combines these practices: small policy mistakes can expose data or block work, while external, tested policies make allow-or-deny decisions clearer and aligned with business rules.
Why it matters: Even a short policy can have serious consequences, so ACME needs confidence in both the rule and the resulting decision.
Key terms: design, management, assurance, policy as code, unified, reliable record system, external, transparent, business rules
10.5 Summary
Where this is used later
- Why governance matters for authorization (chapter 14) · Returns to why governance matters for authorization.
- Governance frameworks for policy management (chapter 14) · Develops the governance responsibilities introduced for policy data.
- Benefits of the layered model (chapter 13) · Introduces the policy-as-code practices extended here to a multi-tenant setting.
- Policy life cycle and distribution (chapter 13) · Builds on the distinction between managing policy changes and distributing them for runtime use.
- Regulatory compliance and authorization (chapter 14) · Provides an example of policy change evidence relevant to regulatory compliance.
- (chapter intro) (chapter 14) · Policy versioning and review as part of Policy as Code practice.
- Review and approve (chapter 14) · Builds toward review and approval as part of the policy management life cycle.
- Monitor (chapter 14) · Monitoring policy use builds on the ability to inspect decisions and operational metrics.
Concepts explained in this chapter
- testA test is an executable check that evaluates software behavior against expected outcomes.
- policyAn authorization policy is a declarative rule or set of rules that determines which subjects may perform which actions on which resources under specified conditions.
- principle of least privilegeThe principle of least privilege requires each subject to receive only the access necessary to perform its authorized tasks.
- static analysisStatic analysis is the examination of programs or policies without executing them to identify properties, errors, or behavioral consequences.
- policy storeA policy store is a repository that contains authorization policies for retrieval and evaluation.
- policy as codePolicy as code is an approach that represents policy as machine-readable, version-controlled, and testable software artifacts.
- policy repositoryA policy repository is a managed source location containing authorization policies and their revisions before deployment to a policy store.
- schema validationSchema validation is the process of checking data or configuration against the structure, types, and constraints defined by a schema.
- Cedar Analysis CLICedar Analysis is a static analysis tool for checking Cedar policies and their properties.
- scenario testingScenario testing evaluates behavior through specified end-to-end or contextual usage scenarios, potentially involving multiple policies or relationships.
- brittle policyA brittle policy is an authorization policy whose correctness depends on volatile details and therefore can fail when those details change.
- request-driven testA request-driven test evaluates authorization behavior by submitting constructed authorization requests and checking the resulting decisions.
- naming standardA naming convention is an agreed pattern for assigning identifiers so related entities or policy elements are named consistently.
- scopeA scope is the policy element that identifies the principals, actions, and resources to which a policy applies.
- deployment pipelineA CI/CD pipeline is an automated workflow that builds, tests, and delivers software or configuration changes through continuous integration and continuous delivery.
- schemaA schema is a formal description of the structure, types, and constraints of data stored or exchanged by a system, including Cedar entity types, attributes, actions, and context.
- architecture decision recordAn architectural decision record is a version-controlled document that captures the context, rationale, decision, consequences, and related artifacts for an architectural choice.
- roleA role is an authorization abstraction that groups permissions or access responsibilities for assignment to principals.
- assuranceAssurance is the degree of confidence that an authentication process correctly represents the identity of the entity being authenticated.
- consistencyConsistency is the uniform interpretation and application of authorization requests and decisions across enforcement components.
- governanceA governance framework is a structured system that assigns responsibility, establishes applicable standards, and coordinates work across teams or systems.
- policy deploymentPolicy deployment is the process of delivering authorization policies from managed source repositories to systems that enforce them.
- policy languageA policy language is a formal language whose syntax and semantics allow authorization policies to be represented and processed by software.
- policy managementPolicy management is the lifecycle practice of reviewing, versioning, deploying, and rolling back authorization policies.
- dynamic adaptabilityDynamic authorization is an access-control technique that evaluates whether access is permitted at request time using current context and authorization information.
- policy bundleA policy bundle is a packaged collection of reviewed authorization policies prepared for versioned deployment and runtime evaluation.
- versioningA version control system is a software system that records and manages successive versions of files and supports operations such as rollback and audit.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.