query-orchestration/cmd/auth_related/permit_test/permit.opa.testing/README.md

OPA Local Policy Testing Setup

This setup allows you to test OPA (Open Policy Agent) policies with local policy files and data.

Architecture

• OPA: Policy engine running in server mode
• Data Loader: Automatically loads test data into OPA at startup

Quick Start

1. Start OPA and load data:

   docker compose up
   

   This will:

   • Start OPA server on port 8181
   • Wait for OPA to be healthy
   • Automatically load your test data from policy-data.json

2. Access OPA:

   • OPA API: http://localhost:8181

Modifying Test Data

Updating Policy Data (JSON)

To change the test data that policies use:

1. Edit the data file:

   vi policy-data.json
   

2. Reload the data:

   ./put-policy-data.sh
   

The data will be loaded into OPA at /data/static/.

Example data structure:

{
  "users": [
    {
      "id": 1,
      "name": "alice",
      "role": "admin"
    }
  ],
  "permissions": {
    "admin": ["read", "write", "delete"],
    "user": ["read"]
  }
}

Updating Policy Rules (Rego)

To change the policy logic:

1. Edit the policy file:

   vi policies/policy.rego
   

2. Restart OPA:

   docker compose restart opa
   

OPA will reload policies automatically on restart.

Testing Policies

Query OPA directly

# Test a policy decision
curl -X POST http://localhost:8181/v1/data/example/allow \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "user": {"role": "admin"},
      "action": "read"
    }
  }'

Check loaded data

# View all loaded data
curl http://localhost:8181/v1/data

# View specific data path
curl http://localhost:8181/v1/data/static

Check loaded policies

# View all policies
curl http://localhost:8181/v1/policies

File Structure

.
├── docker-compose.yaml          # Main orchestration file
├── policy-data.json            # Test data (modify this)
├── put-policy-data.sh          # Script to load data into OPA
├── policies/
│   └── policy.rego            # Main policy file (modify this)
└── README.md                  # This file

Common Workflows

Adding New Test Users

1. Edit policy-data.json
2. Add user to users array
3. Run: ./put-policy-data.sh

Adding New Permissions

1. Edit policy-data.json
2. Update permissions object
3. Run: ./put-policy-data.sh

Changing Policy Logic

1. Edit policies/policy.rego
2. Restart OPA: docker compose restart opa

Debugging

View logs:

# OPA logs
docker compose logs -f opa

# Data loader logs
docker compose logs data_loader

Important Notes

• Data changes: Run ./put-policy-data.sh to reload data
• Policy changes: Restart OPA to reload policies
• Data path: JSON data is available in policies at data.static.*
• Port: OPA runs on port 8181

Troubleshooting

OPA not starting

• Check port 8181 is available
• View logs: docker compose logs opa

Data not loading

• Check data file format: cat policy-data.json | jq .
• Check OPA is healthy: curl http://localhost:8181/v1/data
• Run data loader manually: ./put-policy-data.sh

Policy errors

• Validate Rego syntax: opa fmt policies/policy.rego
• Check OPA logs: docker compose logs opa