Open Policy Agent

The Open Policy Agent (OPA) connector enables you to distribute your Big ACL authorization rules to OPA instances using the bundle pull model. This integration allows you to manage policies centrally in Big ACL while deploying them to multiple OPA instances across your infrastructure.

Overview

Open Policy Agent is a general-purpose policy engine that uses the Rego policy language. Big ACL automatically translates your rules into Rego policies and packages them into OPA bundles that your OPA instances can pull.

How It Works

Unlike push-based connectors, the OPA connector uses a pull model:

1. Big ACL generates OPA bundles containing your Rego policies
2. OPA instances periodically poll the Big ACL API to fetch bundles
3. OPA automatically applies updates when policies change

---

Getting Started

Prerequisites

Before configuring the connector, ensure you have:

1. OPA installed on your target systems (version 0.40.0 or later recommended)
2. Network connectivity from OPA instances to the Big ACL API
3. HTTPS support for secure bundle downloads

OPA Installation

If you haven’t installed OPA yet, you can download it from the official website:

# Linux (amd64)
curl -L -o opa https://openpolicyagent.org/downloads/latest/opa_linux_amd64
chmod +x opa

# macOS
brew install opa

# Docker
docker pull openpolicyagent/opa:latest

---

Configuration

Step 1: Create the Connector

1. Navigate to Settings > Connectors in the Big ACL console
2. Click Add Connector and select Open Policy Agent
3. Enter a name for your connector (e.g., “Production OPA”)
4. Click Save

Step 2: Generate an Access Token

OPA instances authenticate using a bearer token:

1. In the connector configuration, click Generate Token
2. Copy the token immediately - it will only be shown once
3. Store the token securely (e.g., in a secrets manager)

Token Property	Description
Format	opa_ prefix followed by a random string
Lifetime	Permanent until rotated or revoked
Scope	Access to all bundles of this connector

Step 3: Create Bundles

Bundles define which policies are distributed to OPA:

1. Click Add Bundle
2. Enter a bundle name (alphanumeric, e.g., “main” or “api-policies”)
3. Optionally select Entity Classes to filter which rules are included
4. Click Save

Field	Description
Name	Unique identifier for the bundle (alphanumeric, hyphens allowed)
Entity Classes	Filter rules by entity type. Leave empty to include all rules.

Step 4: Configure OPA

Configure your OPA instance to pull bundles from Big ACL. Add the following to your OPA configuration file:

services:
  bigacl:
    url: https://api.big-acl.com
    credentials:
      bearer:
        token: "opa_xxxxxxxxxxxxx"

bundles:
  authz:
    service: bigacl
    resource: /{tenant-id}/connectors/opa/{connector-id}/bundles/{bundle-id}
    polling:
      min_delay_seconds: 30
      max_delay_seconds: 60

Replace the placeholders:

• {tenant-id}: Your Big ACL tenant ID
• {connector-id}: The connector ID (visible in the connector URL)
• {bundle-id}: The bundle ID (visible in bundle details)
• opa_xxxxxxxxxxxxx: Your generated token

Step 5: Activate the Connector

1. Toggle the connector status to Active
2. OPA instances can now fetch bundles

---

Bundle Management

Bundle Contents

Each bundle is a tar.gz archive containing:

File	Description
.manifest	Bundle metadata including revision
policy.rego	Rego policies translated from your Big ACL rules

Which Rules Are Included?

Only rules with Enforced status are included in bundles:

Status	In Bundle?	Description
Draft	No	Rule is being edited
Proposed	No	Rule is pending review
Approved	Deploying	Rule is being added to bundles
Enforced	Yes	Rule is included and active
Suspended	No	Rule is temporarily disabled
Archived	No	Rule is archived

Filtering by Entity Class

You can create multiple bundles with different subsets of rules:

• All rules: Leave Entity Classes empty
• Specific types: Select one or more entity classes to include only rules that reference those types

This is useful when different OPA instances need different policies (e.g., API gateway vs. backend services).

Bundle Revisions

Each bundle has a revision number that increments when:

• Rules are added, modified, or removed
• The bundle configuration changes

OPA uses the revision to detect changes and only downloads when necessary.

---

Polling and Caching

How OPA Polls

OPA periodically requests bundles using HTTP:

GET /{tenant-id}/connectors/opa/{connector-id}/bundles/{bundle-id}
Authorization: Bearer opa_xxxxxxxxxxxxx
If-None-Match: "{previous-etag}"

ETag Support

Big ACL supports ETags for efficient polling:

Response	Description
200 OK	Bundle has changed, full content returned
304 Not Modified	Bundle unchanged, no content returned

This minimizes bandwidth and processing when policies haven’t changed.

Recommended Polling Interval

Configure a polling interval based on your needs:

Interval	Use Case
10-30 seconds	Development, rapid iteration
30-60 seconds	Production, standard deployments
5-15 minutes	Low-frequency changes, bandwidth constraints

---

Monitoring

Sync History

The bundle detail view shows recent sync activity:

Column	Description
Date	When the request was made
Revision	Bundle revision at time of request
Client IP	IP address of the OPA instance
User Agent	OPA version and identifier
Status	HTTP response code (200 or 304)

Understanding Status Codes

Status	Meaning
200 OK	OPA downloaded a new or updated bundle
304 Not Modified	OPA checked but bundle was unchanged
401 Unauthorized	Token is invalid or missing
403 Forbidden	Connector is not active
404 Not Found	Bundle or connector doesn’t exist

Connector Status

Status	Description
Active	Bundles are available for download
Inactive	Bundles are not served, 403 returned

---

Token Management

Token Rotation

To rotate the token (e.g., for security compliance):

1. Click Rotate Token
2. Copy the new token
3. Update all OPA instances with the new token
4. The old token is immediately invalidated

Important: Plan token rotation carefully to avoid service disruption.

Token Revocation

To permanently disable access:

1. Click Revoke Token
2. Confirm the action
3. The connector becomes inactive
4. All OPA instances will receive 401 errors

Revocation is useful when decommissioning a connector or responding to a security incident.

---

Rego Policy Format

Big ACL translates your rules into Rego policies. You can preview the Rego syntax for any rule in the rule details view.

Example Translation

Big ACL Rule:

“A developer can read a repository if they belong to the repository’s team.”

Rego Policy:

package bigacl

default allow = false

allow {
    input.principal.type == "Developer"
    input.action == "read"
    input.resource.type == "Repository"
    input.principal.team == input.resource.team
}

Policy Package

All Big ACL policies are placed in the bigacl package. Configure your OPA queries accordingly:

# Query example
opa eval -d bundle/ -i input.json "data.bigacl.allow"