Skip to main content

Policy Management

Learn how to create, manage, and organize authorization policies in WL-APDP.

Policy Structure​

A policy in WL-APDP consists of:

{
  "id": "unique-policy-id",
  "name": "Human-readable name",
  "code": "permit(...) when { ... };",
  "description": "What this policy does",
  "active": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}
FieldRequiredDescription
idYesUnique identifier (alphanumeric, hyphens)
nameYesHuman-readable name
codeYesCedar policy code
descriptionYesExplains the policy purpose
activeYesWhether the policy is enforced
created_atYesISO 8601 timestamp
updated_atYesISO 8601 timestamp

Creating Policies​

Via API​

curl -X POST http://localhost:8081/policies \
  -H "Content-Type: application/json" \
  -d '{
    "id": "finance-read-policy",
    "name": "Finance Team Document Access",
    "code": "permit(principal in Group::\"finance\", action == Action::\"read\", resource is Document) when { resource.department == \"finance\" };",
    "description": "Allow finance team to read finance documents",
    "active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }'

Via Python SDK​

from wl_apdp import WatchlightClient

client = WatchlightClient("http://localhost:8081")

policy = client.create_policy(
    id="finance-read-policy",
    name="Finance Team Document Access",
    code='permit(principal in Group::"finance", action == Action::"read", resource is Document) when { resource.department == "finance" };',
    description="Allow finance team to read finance documents",
)

Via Dashboard​

  1. Navigate to the Policies section
  2. Click "Create Policy"
  3. Fill in the policy details
  4. Click "Save"

Listing Policies​

curl http://localhost:8081/policies

Response:

{
  "policies": [
    {
      "id": "finance-read-policy",
      "name": "Finance Team Document Access",
      "code": "permit(...);",
      "description": "Allow finance team to read finance documents",
      "active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Updating Policies​

curl -X PUT http://localhost:8081/policies/finance-read-policy \
  -H "Content-Type: application/json" \
  -d '{
    "id": "finance-read-policy",
    "name": "Finance Team Document Access (Updated)",
    "code": "permit(principal in Group::\"finance\", action in [Action::\"read\", Action::\"list\"], resource is Document) when { resource.department == \"finance\" };",
    "description": "Allow finance team to read and list finance documents",
    "active": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-15T00:00:00Z"
  }'

Deleting Policies​

curl -X DELETE http://localhost:8081/policies/finance-read-policy

Validating Policies​

Validate All Policies​

curl http://localhost:8081/policies/validate

Validate a Single Policy​

curl -X POST http://localhost:8081/policies/validate/single \
  -H "Content-Type: application/json" \
  -d '{
    "code": "permit(principal == User::\"alice\", action, resource);"
  }'

Policy Metadata​

WL-APDP extracts metadata from policies for intelligent selection:

curl http://localhost:8081/policies/metadata

Response:

{
  "metadata": [
    {
      "policy_id": "finance-read-policy",
      "principal_pattern": "Group::finance",
      "action_pattern": "Action::read",
      "resource_pattern": "Document",
      "context_requirements": ["resource.department"],
      "complexity_score": 3
    }
  ]
}

Analyzing Policy Application​

See which policies would apply to a request:

curl -X POST http://localhost:8081/policies/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "User::\"alice\"",
    "action": "Action::\"read\"",
    "resource": "Document::\"q4-report\"",
    "context": {
      "department": "finance"
    }
  }'

Response:

{
  "applicable_policies": [
    {
      "id": "finance-read-policy",
      "name": "Finance Team Document Access",
      "would_match": true
    }
  ],
  "total_policies": 15,
  "applicable_count": 1
}

Policy Organization​

Naming Conventions​

Use consistent naming:

{team}-{action}-{resource}-policy

Examples:
- finance-read-documents-policy
- engineering-execute-tools-policy
- admin-manage-users-policy

Grouping by Purpose​

Organize policies by category:

  • Access Control: Basic read/write permissions
  • Tool Execution: Agent tool access
  • Delegation: Agent-to-agent permissions
  • Compliance: Regulatory requirements

Version Control​

Store policies in version control:

policies/
├── access-control/
│   ├── finance-documents.cedar
│   └── engineering-resources.cedar
├── tool-execution/
│   └── agent-tools.cedar
└── compliance/
    └── data-protection.cedar

Active vs Inactive Policies​

  • Active policies (active: true) are evaluated during authorization
  • Inactive policies (active: false) are stored but not evaluated

Use inactive policies for:

  • Testing new policies before deployment
  • Temporarily disabling policies
  • Maintaining policy history

Policy Loading at Startup​

WL-APDP can load policies from files at startup:

wl-apdp --policies-dir /path/to/policies/

Directory structure:

policies/
├── policy1.json
├── policy2.json
└── subdirectory/
    └── policy3.json

Best Practices​

1. Test Before Deploying​

# Validate syntax
curl -X POST http://localhost:8081/policies/validate/single \
  -d '{"code": "..."}'

# Analyze application
curl -X POST http://localhost:8081/policies/analyze \
  -d '{"principal": "...", ...}'

# Test authorization
curl -X POST http://localhost:8081/authorize \
  -d '{"principal": "...", ...}'

2. Use Descriptive Names and Descriptions​

{
  "id": "agent-customer-data-read",
  "name": "AI Agent Customer Data Read Access",
  "description": "Allows AI agents with valid customer support goals to read customer records. Requires delegation from support team member."
}

3. Keep Policies Atomic​

One policy should handle one access pattern. Combine multiple atomic policies rather than creating complex multi-purpose policies.

4. Document Intent and Goal Requirements​

// Policy: agent-execute-search-tool
// Intent: Must be "search_*" or "find_*"
// Goal: Must be in approved list for this tool
permit(
    principal is Agent,
    action == Action::"execute",
    resource == Tool::"web-search"
) when {
    context.intent.startsWith("search_") ||
    context.intent.startsWith("find_")
};

5. Review Policies Regularly​

  • Audit policy usage with the /policies/analyze endpoint
  • Remove unused policies
  • Update policies as requirements change

Next Steps​