if (subject.hasPermission("case.close") && caseFile.isAssignedTo(subject.userId())) {
    return permit();
}

- multiple services need the same rule
- policy must change faster than application release cycles
- audit teams need visibility into who can do what
- compliance wants reviewable policy diffs
- product teams need fine-grained entitlements
- platform teams need consistent enforcement across Java, Node, Go, data, and infrastructure
- security needs deny-by-default and provable coverage

- versioned
- reviewed
- tested
- deployed
- rolled back
- audited
- diffed
- promoted across environments
- evaluated consistently by a policy engine

package authz.case

default allow := false

allow if {
  input.action == "case.close"
  input.subject.tenant_id == input.resource.tenant_id
  input.subject.permissions[_] == "case.close"
  input.resource.status == "IN_REVIEW"
  input.resource.assignee_id == input.subject.id
}

permit(
  principal,
  action == CaseAction::"close",
  resource
)
when {
  principal.tenant == resource.tenant &&
  principal has permission &&
  principal.permission.contains("case.close") &&
  resource.status == "IN_REVIEW" &&
  resource.assignee == principal
};

Policy becomes an artifact, not just imperative application code.

- replacing application authorization entirely
- removing the need for object-level authorization
- letting security team write all domain rules alone
- passing entire domain entities to a policy engine
- moving every if-statement into Rego/Cedar
- adding a central PDP and assuming the system is secure
- a reason to skip tests

- enforcement point
- safe request construction
- resource loading/scoping
- attribute projection
- error handling
- audit emission
- fallback behavior
- policy version awareness

- system is small or single-service
- policies change rarely
- domain rules are highly coupled to aggregate behavior
- policy is simple and easy to test in Java
- latency budget is extremely tight
- security/compliance does not require central policy governance
- team lacks operational maturity for external PDP

public AuthorizationDecision canEditOwnDraft(SubjectContext subject, Draft draft) {
    if (!subject.userId().equals(draft.createdBy())) {
        return deny("NOT_OWNER");
    }
    if (draft.status() != DraftStatus.DRAFT) {
        return deny("NOT_EDITABLE_STATE");
    }
    return permit();
}

1. Multiple services need the same policy semantics.
2. Policy changes are more frequent than service deployments.
3. Non-application teams must review or approve policy changes.
4. You need consistent decision logging across services.
5. You need dry-run/shadow evaluation.
6. Authorization is fine-grained and cross-cutting.
7. Tenant-specific or customer-specific policy is required.
8. You need formal policy diff and approval workflow.
9. You need to combine RBAC, ABAC, and relationship data.
10. You need regulatory defensibility: who changed policy, when, why, and what effect.

- enterprise SaaS authorization
- regulatory case management
- document sharing
- healthcare record access
- financial approval flows
- cloud control plane authorization
- internal platform entitlement systems
- multi-tenant admin consoles

AuthorizationDecision decision = authorizationPort.decide(request);

auditSink.record(decision.toAuditEvent());

decision.requirePermit();

- low latency
- fewer network failure modes
- easier local testing
- service autonomy

- policy bundle distribution required
- memory footprint per service
- language/runtime support may vary
- central decision logging requires extra work

- low-latency local network call
- policy engine isolated from app process
- common in Kubernetes/service mesh environments
- easy to update policy independently

- sidecar lifecycle management
- local network still can fail
- version skew between app and sidecar
- more deployment complexity

- central governance
- central decision logging
- consistent runtime behavior
- easier policy administration

- network latency
- shared dependency blast radius
- availability engineering required
- requires strict API compatibility

- local PDP for low-latency common decisions
- remote PDP for admin/governed decisions
- cached policy bundle
- central audit pipeline
- fail-closed for sensitive actions

{
  "subject": {
    "id": "user-123",
    "type": "USER",
    "tenantId": "tenant-a",
    "permissions": ["case.close"],
    "groups": ["unit:enforcement-west"],
    "attributes": {
      "clearance": "CONFIDENTIAL"
    }
  },
  "action": "case.close",
  "resource": {
    "type": "case_file",
    "id": "case-456",
    "tenantId": "tenant-a",
    "attributes": {
      "status": "IN_REVIEW",
      "classification": "CONFIDENTIAL",
      "assigneeId": "user-123",
      "legalHold": false
    }
  },
  "environment": {
    "time": "2026-07-03T10:00:00Z",
    "channel": "HTTP",
    "ipRisk": "LOW"
  },
  "metadata": {
    "requestId": "req-789",
    "service": "case-service",
    "schemaVersion": "authz-request-v1"
  }
}

public record PolicyDecisionRequest(
    PolicySubject subject,
    String action,
    PolicyResource resource,
    PolicyEnvironment environment,
    PolicyRequestMetadata metadata
) {}

public record PolicySubject(
    String id,
    String type,
    String tenantId,
    Set<String> permissions,
    Set<String> groups,
    Map<String, Object> attributes
) {}

public record PolicyResource(
    String type,
    String id,
    String tenantId,
    Map<String, Object> attributes
) {}

public record PolicyEnvironment(
    Instant time,
    String channel,
    Map<String, Object> risk
) {}

public record PolicyDecisionResponse(
    Decision decision,
    List<String> reasonCodes,
    List<Obligation> obligations,
    List<Advice> advice,
    String policyVersion,
    String decisionId,
    CacheDirective cacheDirective
) {
    public boolean permitted() {
        return decision == Decision.PERMIT;
    }
}

allow if input.resource.classification == "PUBLIC"

{"resource":{"attributes":{"classification":"PUBLIC"}}}

subject.id: string required
subject.tenantId: string required
subject.permissions: array[string] required
resource.type: string required
resource.id: string required
resource.tenantId: string required
resource.attributes.status: enum required for case_file
resource.attributes.classification: enum required for case_file
action: enum required
environment.time: timestamp required

- validation before decision
- safer policy authoring
- compatibility checks
- migration path
- contract tests between app and PDP

policy/
  README.md
  schemas/
    authz-request-v1.schema.json
    case-resource-v1.schema.json
  policies/
    common/
      deny-default.rego
      tenant-boundary.rego
    case/
      close-case.rego
      assign-case.rego
      export-case.rego
    evidence/
      upload-evidence.rego
      seal-evidence.rego
  tests/
    case/
      close-case_test.rego
      assign-case_test.rego
  fixtures/
    subjects/
      investigator.json
      supervisor.json
    resources/
      case-in-review.json
      sealed-case.json
  bundles/
  decisions/
    golden/
      close-case-matrix.json

policy/
  schema/
    case.cedarschema
  policies/
    case-close.cedar
    case-export.cedar
    evidence-seal.cedar
  tests/
    case-close-tests.json
  fixtures/
    entities/
      investigator.json
      case-file.json

Security owns policy, application team owns code, nobody owns semantics.

Domain team defines meaning.
Security reviews risk.
Application team implements enforcement.
Platform team operates PDP.
Compliance reviews audit evidence.

admin_policy.rego
case_rules.rego
allow_users.rego

case.closure.request
case.closure.approve
case.assignment.change
case.evidence.upload
case.evidence.seal
case.export.full
case.export.redacted

public enum Action {
    CASE_CLOSURE_REQUEST("case.closure.request"),
    CASE_CLOSURE_APPROVE("case.closure.approve"),
    CASE_ASSIGNMENT_CHANGE("case.assignment.change"),
    CASE_EVIDENCE_UPLOAD("case.evidence.upload"),
    CASE_EVIDENCE_SEAL("case.evidence.seal"),
    CASE_EXPORT_FULL("case.export.full"),
    CASE_EXPORT_REDACTED("case.export.redacted");

    private final String policyName;

    Action(String policyName) {
        this.policyName = policyName;
    }

    public String policyName() {
        return policyName;
    }
}

- closed case cannot be edited
- closure requester cannot approve own closure
- sealed evidence cannot be modified
- legal hold prevents deletion
- invoice total cannot be negative

public void sealEvidence(ActorId actor, Instant now) {
    if (status == EvidenceStatus.SEALED) {
        throw new InvalidEvidenceState("Evidence is already sealed");
    }
    if (hash == null) {
        throw new InvalidEvidenceState("Evidence hash is required before sealing");
    }
    this.status = EvidenceStatus.SEALED;
    this.sealedBy = actor;
    this.sealedAt = now;
}

public final class OpaAuthorizationAdapter implements AuthorizationPort {
    private final HttpClient httpClient;
    private final URI decisionEndpoint;
    private final ObjectMapper mapper;
    private final Duration timeout;

    @Override
    public AuthorizationDecision decide(AuthorizationRequest request) {
        PolicyDecisionRequest input = PolicyDecisionRequestMapper.from(request);

        try {
            HttpRequest httpRequest = HttpRequest.newBuilder(decisionEndpoint)
                .timeout(timeout)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(Map.of("input", input))))
                .build();

            HttpResponse<String> response = httpClient.send(httpRequest, HttpResponse.BodyHandlers.ofString());

            if (response.statusCode() != 200) {
                return AuthorizationDecision.indeterminate("PDP_HTTP_" + response.statusCode());
            }

            return OpaDecisionMapper.fromJson(response.body());
        } catch (IOException | InterruptedException e) {
            Thread.currentThread().interrupt();
            return AuthorizationDecision.indeterminate("PDP_UNAVAILABLE");
        }
    }
}

public enum FailureMode {
    FAIL_CLOSED,
    ALLOW_IF_FRESH_CACHED_PERMIT,
    LOCAL_EMERGENCY_POLICY,
    PUBLIC_BYPASS_ONLY
}

public record ActionMetadata(
    Action action,
    Sensitivity sensitivity,
    FailureMode failureMode,
    Duration maxCachedDecisionAge
) {}

userId + action

subjectId
subjectVersion
tenantId
action
resourceType
resourceId
resourceVersion
policyVersion
contextHash

public record DecisionCacheKey(
    String subjectId,
    long subjectAuthzVersion,
    String tenantId,
    String action,
    String resourceType,
    String resourceId,
    long resourceAuthzVersion,
    String policyVersion,
    String contextHash
) {}

- one-time approvals
- rapidly changing risk signals
- emergency access
- legal hold overrides
- very sensitive exports
- time-window decisions unless expiration matches window

AuthorizationDecision primary = primaryPolicy.decide(request);
AuthorizationDecision candidate = candidatePolicy.decide(request);

if (!primary.samePermitDeny(candidate)) {
    shadowDiffSink.record(new PolicyDiff(
        request.metadata().requestId(),
        request.action(),
        request.resource(),
        primary.summary(),
        candidate.summary()
    ));
}

return primary;

- migration from Java policy to OPA/Cedar
- policy refactor
- role model cleanup
- tenant-specific policy rollout
- tightening policy without surprise outage

Which requests would change from permit to deny?
Which requests would change from deny to permit?
Which tenants/users/actions are affected?
Is the change expected?

For this corpus of authorization requests, did decisions change?

[
  {
    "name": "assigned investigator may close in-review case",
    "input": "fixtures/close/assigned-investigator.json",
    "expected": "PERMIT"
  },
  {
    "name": "investigator from other tenant denied",
    "input": "fixtures/close/other-tenant.json",
    "expected": "DENY"
  },
  {
    "name": "requester cannot approve own closure",
    "input": "fixtures/close/maker-checker-violation.json",
    "expected": "DENY"
  }
]

Who owns this attribute?
Where is it sourced from?
How often does it change?
Can it be trusted from token claims?
Does it require database lookup?
Can it be cached?
What is its freshness budget?
What happens if it is missing?

- app knows domain data
- transactionally fresh resource state
- PDP simpler
- fewer PDP integrations

- services may build inconsistent inputs
- more data passed over boundary
- policy cannot query extra data unless included

- central attribute lookup
- app sends minimal request
- consistent policy-side enrichment

- PDP becomes integration-heavy
- latency increases
- harder transaction consistency
- ownership boundaries blur

- tenant configuration controls policy parameters
- tenant can assign roles but not write arbitrary policy
- tenant can enable stricter constraints
- platform owns base deny rules
- customer policy runs inside bounded schema and sandbox

deny if tenant mismatch
forbid if legal hold deletion
forbid if action requires platform-only privilege

require supervisor approval for exports above threshold
restrict access by business hours
require local department membership for sensitive cases

default deny
explicit permit grants access
explicit forbid overrides permit
indeterminate does not permit

public AuthorizationDecision combine(List<AuthorizationDecision> decisions) {
    if (decisions.stream().anyMatch(AuthorizationDecision::isForbid)) {
        return AuthorizationDecision.deny("EXPLICIT_FORBID");
    }
    if (decisions.stream().anyMatch(AuthorizationDecision::isIndeterminate)) {
        return AuthorizationDecision.indeterminate("POLICY_INDETERMINATE");
    }
    if (decisions.stream().anyMatch(AuthorizationDecision::isPermit)) {
        return AuthorizationDecision.permit();
    }
    return AuthorizationDecision.deny("DEFAULT_DENY");
}

{
  "decision": "PERMIT",
  "obligations": [
    {"type":"REDACT_FIELDS", "fields":["ssn", "medicalHistory"]},
    {"type":"REQUIRE_AUDIT", "level":"SENSITIVE"}
  ],
  "advice": [
    {"type":"DISPLAY_WARNING", "message":"Sensitive case access is monitored"}
  ]
}

for (Obligation obligation : decision.obligations()) {
    obligationHandlerRegistry.handle(obligation, responseContext);
}

if (!obligationHandlerRegistry.canSatisfyAll(decision.obligations())) {
    throw new AccessDeniedException("Unsatisfied authorization obligation");
}

- decision id
- request id / correlation id
- subject id/type/tenant
- action
- resource type/id/tenant
- decision: permit/deny/forbid/indeterminate
- reason codes
- policy version
- policy bundle version
- input schema version
- PDP instance/version
- latency
- obligations
- enforcement outcome
- timestamp

public final class DecisionAuditSanitizer {
    public Map<String, Object> sanitize(PolicyDecisionRequest request) {
        Map<String, Object> safe = new LinkedHashMap<>();
        safe.put("subjectId", request.subject().id());
        safe.put("tenantId", request.subject().tenantId());
        safe.put("action", request.action());
        safe.put("resourceType", request.resource().type());
        safe.put("resourceId", request.resource().id());
        safe.put("resourceTenantId", request.resource().tenantId());
        safe.put("classification", request.resource().attributes().get("classification"));
        return safe;
    }
}

public final class ExistingJavaAuthorizationAdapter implements AuthorizationPort {
    @Override
    public AuthorizationDecision decide(AuthorizationRequest request) {
        return switch (request.action()) {
            case CASE_CLOSE -> closeCasePolicy.evaluate(request);
            case CASE_ASSIGN -> assignCasePolicy.evaluate(request);
            case CASE_EXPORT_FULL -> exportPolicy.evaluate(request);
            default -> AuthorizationDecision.deny("UNKNOWN_ACTION");
        };
    }
}

public final class ShadowingAuthorizationPort implements AuthorizationPort {
    private final AuthorizationPort primary;
    private final AuthorizationPort shadow;
    private final PolicyDiffSink diffSink;

    @Override
    public AuthorizationDecision decide(AuthorizationRequest request) {
        AuthorizationDecision primaryDecision = primary.decide(request);
        AuthorizationDecision shadowDecision = shadow.decide(request);

        if (!primaryDecision.samePermitDeny(shadowDecision)) {
            diffSink.record(request, primaryDecision, shadowDecision);
        }

        return primaryDecision;
    }
}

- test coverage for every sensitive action
- deny-by-default tests
- cross-tenant negative tests
- maker-checker negative tests
- high-sensitivity resource tests
- old-vs-new semantic diff
- emergency rollback
- decision log sampling
- production canary by tenant/action
- dashboards for permit/deny rate changes

authz.decisions.total{decision,action,tenant}
authz.denies.total{reason_code,action}
authz.indeterminate.total{reason_code,pdp}
authz.latency.p95{pdp,action}
authz.policy.version{service}
authz.shadow.diff.total{action,diff_type}
authz.obligation.unsatisfied.total{obligation_type}

assigned investigator closing in-review case -> permit
other tenant investigator closing case -> deny
same requester approving closure -> deny
supervisor exporting sealed evidence without clearance -> deny

@Test
void closeCase_requestContainsCaseStatusAndClassification() {
    PolicyDecisionRequest input = mapper.from(closeCaseAuthorizationRequest(subject, caseFile));

    assertThat(input.resource().attributes())
        .containsEntry("status", "IN_REVIEW")
        .containsEntry("classification", "CONFIDENTIAL");
}

@Test
void closeCase_deniedByPolicyEngineForOtherTenant() {
    assertThatThrownBy(() -> useCase.handle(otherTenantSubject, command))
        .isInstanceOf(AccessDeniedException.class);
}

Do not replay sensitive raw data; replay sanitized decision fixtures.

- policy bundle version
- request schema version
- action catalog version

{
  "decision": "DENY",
  "reasonCodes": ["NOT_ASSIGNED"],
  "policyVersion": "case-authz-2026.07.03-3",
  "schemaVersion": "authz-request-v1",
  "actionCatalogVersion": "case-actions-v4"
}

- revert policy bundle version
- switch PDP route to previous bundle
- disable tenant-specific policy overlay
- switch enforcement to previous primary in shadowing port
- emergency fail-closed for sensitive actions

- PDP unavailable
- PDP slow
- PDP returns malformed decision
- policy bundle missing
- policy bundle incompatible with request schema
- attribute source unavailable
- policy engine memory pressure
- network partition
- stale policy cache
- sidecar version mismatch
- decision log sink unavailable

public AuthorizationDecision enforceFailureMode(
    AuthorizationRequest request,
    AuthorizationDecision decision
) {
    if (!decision.isIndeterminate()) {
        return decision;
    }

    ActionMetadata metadata = actionCatalog.metadata(request.action());

    return switch (metadata.failureMode()) {
        case FAIL_CLOSED -> AuthorizationDecision.deny("PDP_INDETERMINATE_FAIL_CLOSED");
        case ALLOW_IF_FRESH_CACHED_PERMIT -> cachedPermit(request, metadata.maxCachedDecisionAge())
            .orElseGet(() -> AuthorizationDecision.deny("NO_FRESH_CACHED_PERMIT"));
        case LOCAL_EMERGENCY_POLICY -> emergencyPolicy.evaluate(request);
        case PUBLIC_BYPASS_ONLY -> request.action().isPublicRead()
            ? AuthorizationDecision.permit("PUBLIC_BYPASS")
            : AuthorizationDecision.deny("PDP_INDETERMINATE");
    };
}

Total API p95 budget: 200 ms
Authentication/token parsing: 5 ms
Resource load: 30 ms
Authorization decision: 20 ms
Business operation: 80 ms
DB write: 40 ms
Serialization/logging: 25 ms

- sidecar PDP
- local policy engine
- decision caching
- batch decision API
- push attributes to avoid PDP lookups
- precompute relationship/entitlement data
- reduce policy complexity
- move low-risk policies local

for (CaseSummary caseSummary : page.items()) {
    decision = authorizationPort.decide(canViewCase(subject, caseSummary));
}

BatchAuthorizationDecision decisions = authorizationPort.decideBatch(
    page.items().stream()
        .map(caseSummary -> canViewCase(subject, caseSummary))
        .toList()
);

- field-level actions on already scoped rows
- UI action availability
- small object collections
- post-query refinement when policy cannot be expressed as SQL

Map<Action, AuthorizationDecision> availableActions = authorizationPort.decideBatch(
    ActionCatalog.caseActions().stream()
        .map(action -> request(subject, action, caseFile))
        .toList()
).byAction();

{
  "caseId": "case-456",
  "status": "IN_REVIEW",
  "availableActions": {
    "case.closure.request": true,
    "case.closure.approve": false,
    "case.export.full": false,
    "case.export.redacted": true
  }
}

paths:
  /cases/{caseId}/close:
    post:
      operationId: closeCase
      x-authorization:
        action: case.closure.request
        resource: case_file
        objectLevel: true
        fieldPolicy: false
        failureMode: fail_closed

- API review
- documentation
- test generation
- coverage analysis
- gateway coarse rules

1. What problem are we solving: speed, governance, consistency, tenant customization, audit, or scale?
2. What remains in Java after policy externalization?
3. What is the decision request schema?
4. Who owns each attribute?
5. Which attributes must be transactionally fresh?
6. What is the action catalog?
7. What is the policy test strategy?
8. What is the rollout and rollback plan?
9. What happens if PDP is slow or unavailable?
10. Are obligations supported and enforced?
11. How are decisions audited?
12. How are policy changes approved?
13. How are semantic diffs reviewed?
14. How are tenant-specific policies constrained?
15. How do we prevent policy drift from domain model changes?

{"allow": true}

Put all authorization behind AuthorizationPort early.
Start with embedded Java policy if needed.
Externalize later when governance and consistency require it.

- explicit
- versioned
- testable
- reviewable
- observable
- governable
- deployable
- reversible

- domain-specific action catalog
- stable request/decision schema
- safe attribute projection
- tested policy fixtures
- shadow evaluation
- semantic diff
- explicit failure modes
- decision audit
- rollout/rollback process
- clear ownership