Chapter 11: Authorization for APIs

Introduction

The introduction distinguishes internal API enforcement from external delegation and explains why ACME adopted complementary strategies for each.

• Internal API authorization: Explain why ACME needed consistent, fine-grained authorization across its growing number of internal APIs and why it integrated Cedar with its API infrastructure.
  Why it matters: Adding more APIs makes scattered access rules harder to enforce consistently.
• External API delegation: Explain why customers needed a way to give third-party applications limited API access without handing over their ACME credentials, and identify OAuth as ACME’s strategy.
  Why it matters: Third-party integrations need access on a customer’s behalf without inheriting everything that customer can access.

Key terms: internal enforcement, runtime policy evaluation, Cedar, centralized, fine-grained decision point, external delegation, OAuth, specific capabilities, third-party applications

11.1 Authorization in a microservices world

This section explains why microservices made ACME’s API authorization fragmented and frames enforcement-point placement as the architectural decision, with Cedar remaining the decision maker.

• Fragmented microservice authorization: Explain why splitting ACME’s monolith into services made consistent authorization harder: each service exposed an API, and a single user request could cross many APIs with different levels of checking.
  Why it matters: The authorization problem is no longer confined to one application boundary.
• Enforcement placement decision: Describe ACME’s architectural question: with Cedar making the final authorization decision, it needed to choose where enforcement sits, what context it can gather, and which request paths it covers. State that the candidate patterns send normalized authorization requests to Cedar, without attributing unintroduced mechanics to those patterns.
  Why it matters: Enforcement placement determines where policy checks can be applied reliably across distributed APIs.

Key terms: microservices, API surface, authorization, service boundary, policy enforcement point, Cedar, normalized authorization request, PDP

11.1.1 Pattern 1: API gateway as enforcement point

The section explains how ACME uses an API gateway to enforce Cedar policies on API requests, why decisions must reflect the person behind a service call, and where gateway coverage ends.

• Gateway authorization request flow: Trace how the gateway turns Carol’s salary request into a Cedar decision and enforces the result before the HR API receives the call.
  Why it matters: The decision is enforced before an unauthorized call can reach sensitive HR data.
• Confused deputy prevention: Explain why the dashboard’s permission to call the HR API is insufficient, and how ACME bases the decision on Carol’s authority instead.
  Why it matters: Checking the person behind a service call prevents internal service access from becoming a path to unauthorized data.
• Gateway coverage boundaries: Distinguish north–south from east–west traffic and explain why gateway enforcement alone cannot cover every API call.
  Why it matters: A central gateway does not secure calls it never sees.
• Centralized enforcement advantages: Describe why ACME chose the gateway as an initial enforcement point and how it reduces duplicated checks and UI-dependent security.
  Why it matters: Central enforcement keeps access checks consistent without relying on every application interface to get them right.

Key terms: API gateway, policy enforcement point, PARC, Cedar, confused deputy, principal, calling_service, north–south traffic, east–west traffic, central policy enforcement point

11.1.2 Pattern 2: Service mesh with sidecar enforcement

This section explains how service-mesh sidecars enforce Cedar authorization on internal API calls, using workload identity and request context to stop unauthorized traffic before it reaches downstream services.

• Internal hop enforcement: Explain why an API gateway alone leaves internal service calls unprotected and how service-mesh sidecars enforce authorization at each hop.
  Why it matters: Checks at internal hops cover requests that gateway-only enforcement cannot see.
• Docs indexing decision flow: Trace how the Docs sidecar uses Cedar's decision to forward ordinary documents to Search but block documents labeled Legal.
  Why it matters: Blocking at the sender keeps prohibited documents out of Search without duplicating the same document-level check there.
• Delegated request context: Explain why a service-to-service authorization request may need the initiating person and other context as well as the calling workload's identity.
  Why it matters: Preserving who initiated a call and what it concerns prevents a legitimate service identity from masking an unauthorized request.
• SPIFFE and Cedar responsibilities: Distinguish how SPIFFE-backed workload authentication supplies identity to a PARC request from Cedar's authorization decision.
  Why it matters: Proving which service called and deciding what that service may do are separate requirements.
• Mesh benefits and tradeoffs: Describe the security and development benefits of sidecar enforcement alongside its operational costs.
  Why it matters: A mesh can scale enforcement with internal traffic, but the operational burden is part of the design choice.

Key terms: east–west traffic, service mesh, sidecar proxy, PEP, PDP, PARC, Docs service, Search service, Legal, doc:index

11.1.3 Pattern 3: Per-service proxies

This section explains how a proxy in front of an individual API enforces authorization when gateway or service-mesh enforcement is unavailable, using Finance as an example and weighing the operational tradeoff.

• Per-service proxy decision flow: Trace how a per-service proxy enforces authorization before a call reaches an API: it validates the caller, gathers request context, constructs a PARC request, queries Cedar, and enforces the decision.
  Why it matters: The service gets a policy decision before handling the request, without embedding Cedar in its application code.
• Finance API protection without migration: Explain why ACME used a per-service proxy for Finance’s cost-center API and how it preserved the existing application while applying the managers’ department-based access rule.
  Why it matters: This pattern lets a sensitive existing API receive consistent protection without a broader platform migration.
• Operational cost and failure scope: Describe the tradeoff of deploying a proxy for each service: additional deployment and maintenance work, but a failure confined to that service rather than the gateway or mesh.
  Why it matters: The choice trades more per-service upkeep for more localized failures.

Key terms: per-service proxy, policy enforcement point, PARC request, Cedar, Finance API, cost-center data, service mesh, PEP, operational overhead, blast radius

11.1.4 Comparing enforcement patterns

The section compares where ACME enforces authorization across its APIs and identifies the common decision process shared by all three patterns.

• Enforcement pattern coverage: Describe where ACME used the API gateway, service mesh, and per-service proxies, and how the three patterns covered different parts of its API ecosystem.
  Why it matters: Different enforcement locations let ACME protect APIs across incoming, internal, and transitional traffic.
• Common authorization process: Explain what remained consistent across the three patterns despite differences in enforcement location and deployment.
  Why it matters: Consistent handling keeps authorization coherent even when APIs use different enforcement patterns.

Key terms: API gateway, service mesh, east–west calls, per-service proxies, policy enforcement point, normalized, evaluated, enforced, logged, consistent authorization decision

11.1.5 Other API authorization enforcement patterns

The section compares four additional API authorization enforcement patterns and explains why mixed architectures must maintain coverage and consistent policy decisions.

• In-process enforcement tradeoff: Explain how a service can evaluate Cedar authorization locally instead of routing through a proxy, and why the latency benefit creates a consistency burden across services.
  Why it matters: Lower latency helps only if local enforcement remains consistent.
• Network guardrails and limits: Distinguish service-to-service controls based on mTLS identity or network rules from fine-grained resource authorization.
  Why it matters: A permitted service connection does not mean every operation over that connection is permitted.
• Broker and message checks: Explain where coarse-grained and fine-grained enforcement occur in an asynchronous message flow.
  Why it matters: Topic permissions alone do not establish that every message is safe for a consumer to use.
• Direct token exchange tradeoff: Trace how direct token exchange authorizes a service call and identify its consistency tradeoff.
  Why it matters: Direct calls simplify some smaller systems but distribute security responsibilities to individual services.
• Coverage across mixed patterns: Justify why every protected operation needs an enforcement point and consistent authorization inputs when an architecture mixes patterns.
  Why it matters: A centralized-looking policy cannot protect operations that never reach an effective check.

Key terms: in-process enforcement, Cedar library, local Cedar agent, mTLS, workload identity, network controls, coarse-grained controls, fine-grained authorization, event or broker enforcement, message broker

11.2 Authorization for external access to APIs

This section explains why sharing passwords for third-party API access is unsafe and how OAuth provides limited, revocable delegated access instead.

• Password Sharing Risks: Explain why giving a third-party application your password is a poor way to let it access data in another service.
  Why it matters: These risks explain why external API access needs something other than shared credentials.
• OAuth Delegated Access: Describe how OAuth lets a person grant an application limited access without sharing a password, and how that access can be withdrawn.
  Why it matters: OAuth lets connected services do an approved task without receiving unrestricted account access.

Key terms: password anti-pattern, authentication factors, OAuth, delegated access, scopes

11.2.1 The OAuth protocol and roles

The section uses Kate’s connection to an external reporting tool to explain OAuth’s four roles, how consent produces an access token, and why a valid token does not replace fine-grained policy checks.

• Four OAuth roles: Describe the four OAuth roles and identify each one in Kate’s use of BI Explorer.
  Why it matters: The roles make clear who grants access, who requests it, and which ACME services issue and receive the token.
• Consent without shared credentials: Trace how ACME confirms Kate’s approval and gives BI Explorer access without giving it her password.
  Why it matters: This lets Kate use an external tool without trusting it with her ACME credentials or its unsupported claim that she approved access.
• Scopes and document policy: Distinguish what an approved OAuth scope permits from the per-request decision ACME makes with Cedar.
  Why it matters: A valid delegated token must not become an all-access pass to Kate’s data.

Key terms: resource owner, client, authorization server, resource server, consent, access token, grant, OAuth scopes, collab:doc.read, Cedar

11.2.2 OAuth scopes

This section explains how OAuth scopes limit delegated API access and why ACME still evaluates each protected request with Cedar.

• OAuth scope grants: Explain that API providers define scopes as strings representing bundles of related API capabilities, which a client requests and a resource owner may approve instead of granting full account access. Give an ACME example, such as reading document metadata without reading full content.
  Why it matters: Scopes let an integration request only the kinds of API access it needs.
• Scope information in tokens: Describe the two ways issued token scopes can be made available and how ACME’s API gateway obtains them.
  Why it matters: The gateway needs access to a token’s scopes to recognize the delegated grant.
• Delegation versus request authorization: Distinguish an OAuth token’s delegated grant from a complete decision about a particular resource, and explain how ACME uses OAuth and Cedar together.
  Why it matters: A limited grant must not be mistaken for permission to access every resource within that broad capability.

Key terms: scopes, client, resource owner, API capabilities, access token, JWT, token introspection, API gateway, delegation, OAuth token

11.2.3 Acquiring OAuth tokens

This section explains how interactive applications and unattended integrations obtain OAuth access tokens, and why ACME avoids two older grant types.

• Authorization Code Grant flow: Trace how Kate authorizes BI Explorer: she reviews and approves requested scopes at ACME’s authorization server, her browser returns with a short-lived code, and BI Explorer exchanges that code directly for an access token. Explain how a refresh token can spare her repeated login and consent.
  Why it matters: This flow lets a person approve limited access without repeatedly participating whenever the application needs a new access token.
• Tenant-approved app installation: Explain why CustCo’s admin installs the Task App and approves narrow scopes before it requests tokens, and what ACME’s installation record establishes.
  Why it matters: An app acting without a signed-in user still needs a defined tenant and approved limits on its access.
• Client Credentials token acquisition: Describe why CustCo’s continuously running Task App uses the Client Credentials Grant and how it obtains a token using its own credentials and approved scopes.
  Why it matters: Service-to-service synchronization can continue when no CustCo employee is signed in, while the token still identifies who is acting.
• Legacy grant security drawbacks: Distinguish the security drawbacks of the Implicit Grant and Resource Owner Password Credentials Grant, and state which grants ACME uses for new integrations instead.
  Why it matters: Knowing why older grants are discouraged helps distinguish legacy compatibility from a suitable choice for a new integration.

Key terms: Authorization Code Grant, consent, scopes, authorization code, access token, refresh token, installation record, tenant, narrow scopes, policy

11.2.4 Using OAuth tokens

This section shows how an API request carrying an OAuth token becomes a Cedar authorization decision, using delegated user access and a background integration as examples.

• Token to policy decision flow: Trace how ACME handles an API call carrying an OAuth access token, from gateway validation through PARC construction, Cedar evaluation, and enforcement.
  Why it matters: A valid token is not, by itself, permission to perform every API operation.
• Delegated workspace access limits: Explain how Kate’s BI Explorer token and Cedar policy jointly limit its document-metadata requests.
  Why it matters: User consent to a scope does not replace the application’s resource-level access rules.
• Integration installation constraints: Describe how CustCo’s Task App is authorized for background writes without treating it as an individual user.
  Why it matters: An unattended integration can receive narrowly defined access without borrowing a person’s identity.

Key terms: access token, API gateway, PARC request, Cedar, principal, action, Authorization Code Grant, scopes, workspace membership, BI Explorer

11.3 From microservices to third parties: One policy story

This section brings ACME’s internal microservice and external third-party API authorization approaches together under one policy model.

• One Policy Path for APIs: Explain how ACME applies the same authorization rules to internal microservice calls and external API requests despite their different entry points.
  Why it matters: Different API entry points need not lead to different authorization rules.
• OAuth and Cedar Responsibilities: Distinguish the access boundary set by OAuth tokens and scopes from the resource-specific decisions made by Cedar, and explain why ACME combines them.
  Why it matters: Checking a token alone does not decide every action a caller may take on a resource.

Key terms: PARC request, Cedar policies, API gateway, service mesh, per-service proxies, OAuth tokens, scopes, outer boundary, Cedar, externalizing decision-making

11.4 Summary