Open Policy Agent (OPA) Integration

This page describes how to integrate Apache Polaris (Incubating) with Open Policy Agent (OPA) for external authorization.

Overview

Open Policy Agent (OPA) is a general-purpose policy engine that enables unified, context-aware policy enforcement across your stack. OPA provides a high-level declarative language (Rego) for authoring policies and APIs to offload policy decision-making from your software.

Key benefits of using OPA with Polaris:

• Flexible policy language: Write authorization logic in Rego, a powerful declarative language
• Centralized policy management: Manage all policies in a single location
• Policy testing: Write unit tests for your authorization policies
• Rich ecosystem: Integrate with policy bundles, decision logs, and management tools
• Attribute-based access control: Make decisions based on user attributes, resource properties, and environmental context

Prerequisites

Before configuring OPA integration:

1. OPA Server: Deploy and configure an OPA server accessible from Polaris
2. Policy Definition: Write and deploy authorization policies to OPA
3. Network Access: Ensure Polaris can reach the OPA server

Quick Start

1. Deploy OPA

Deploy OPA server with your policies. For example, using Docker:

docker run -d \
  --name opa \
  -p 8181:8181 \
  -v $(pwd)/policies:/policies \
  openpolicyagent/opa:latest \
  run --server --addr :8181 /policies

2. Create a Policy

Create a policy file (e.g., policies/polaris.rego):

package polaris.authz

import future.keywords.if

# Default deny
default allow := false

# Allow admins to do everything
allow if {
    "ADMIN" in input.actor.roles
}

# Allow read operations on tables in analytics catalogs
allow if {
    input.action == "LOAD_TABLE_WITH_READ_DELEGATION"
    some target in input.resource.targets
    some parent in target.parents
    parent.type == "CATALOG"
    startswith(parent.name, "analytics_")
}

3. Configure Polaris

Add the following to your Polaris configuration:

# Enable OPA authorization
polaris.authorization.type=opa

# OPA server endpoint
polaris.authorization.opa.policy-uri=http://localhost:8181/v1/data/polaris/authz/allow

4. Restart Polaris

Restart the Polaris service to apply the configuration.

Configuration Reference

Basic Configuration

HTTP Configuration

Authentication Configuration

OPA integration supports two authentication modes:

No Authentication (default)

No authentication configuration needed if OPA server doesn’t require authentication:

polaris.authorization.opa.auth.type=none

Bearer Token Authentication

Static Bearer Token:

Use a static bearer token:

polaris.authorization.opa.auth.type=bearer
polaris.authorization.opa.auth.bearer.static-token.value=your-secret-token

File-Based Bearer Token with Auto-Refresh:

Use a bearer token from a file with automatic refresh (ideal for JWT tokens):

polaris.authorization.opa.auth.type=bearer
polaris.authorization.opa.auth.bearer.file-based.path=/var/secrets/token.txt
polaris.authorization.opa.auth.bearer.file-based.refresh-interval=PT5M
polaris.authorization.opa.auth.bearer.file-based.jwt-expiration-refresh=true
polaris.authorization.opa.auth.bearer.file-based.jwt-expiration-buffer=PT1M

JWT Auto-Refresh: When jwt-expiration-refresh is enabled (default), if the token file contains a valid JWT with an exp claim, Polaris will automatically refresh the token shortly before it expires based on the jwt-expiration-buffer setting.

Policy Development

Input Document Structure

Polaris sends the following input structure to OPA:

{
  "actor": {
    "principal": "user@example.com",
    "roles": ["role1", "role2"]
  },
  "action": "LOAD_TABLE_WITH_READ_DELEGATION",
  "resource": {
    "targets": [
      {
        "type": "TABLE",
        "name": "my_table",
        "parents": [
          {
            "type": "CATALOG",
            "name": "my_catalog"
          },
          {
            "type": "NAMESPACE",
            "name": "schema1"
          }
        ]
      }
    ],
    "secondaries": []
  },
  "context": {
    "request_id": "uuid"
  }
}

Actor Object

Action Field

The action field contains the operation being attempted as a string value from the PolarisAuthorizableOperation enum.

For the complete list of available operations, see the PolarisAuthorizableOperation enum in the source code.

Common examples include:

• Table operations: LOAD_TABLE_WITH_READ_DELEGATION, LOAD_TABLE_WITH_WRITE_DELEGATION, CREATE_TABLE_DIRECT, UPDATE_TABLE, DROP_TABLE_WITHOUT_PURGE
• Catalog operations: CREATE_CATALOG, UPDATE_CATALOG, DELETE_CATALOG
• Namespace operations: CREATE_NAMESPACE, UPDATE_NAMESPACE_PROPERTIES, DROP_NAMESPACE

Resource Object

Each resource object in targets or secondaries has:

Each parent object has:

Context Object

Policy Example

package polaris.authz

import future.keywords.if
import future.keywords.in

default allow := false

# Admin role can perform all catalog, namespace, and table operations
allow if {
    "ADMIN" in input.actor.roles
    input.action in [
        # Catalog operations
        "CREATE_CATALOG",
        "UPDATE_CATALOG",
        "DELETE_CATALOG",
        "LIST_CATALOGS",
        
        # Namespace operations
        "CREATE_NAMESPACE",
        "UPDATE_NAMESPACE_PROPERTIES",
        "DROP_NAMESPACE",
        "LIST_NAMESPACES",
        
        # Table operations
        "CREATE_TABLE_DIRECT",
        "LOAD_TABLE_WITH_READ_DELEGATION",
        "LOAD_TABLE_WITH_WRITE_DELEGATION",
        "UPDATE_TABLE",
        "DROP_TABLE_WITHOUT_PURGE",
        # Add other data operations as needed
    ]
}

# Data engineers can create/read/update tables and namespaces
allow if {
    "DATA_ENGINEER" in input.actor.roles
    input.action in [
        # Table operations
        "CREATE_TABLE_DIRECT",
        "LOAD_TABLE_WITH_READ_DELEGATION",
        "LOAD_TABLE_WITH_WRITE_DELEGATION",
        "UPDATE_TABLE",
        
        # Namespace operations
        "CREATE_NAMESPACE",
        "UPDATE_NAMESPACE_PROPERTIES",
        "LIST_NAMESPACES"
    ]
}

# Analysts can only read tables
allow if {
    "ANALYST" in input.actor.roles
    input.action == "LOAD_TABLE_WITH_READ_DELEGATION"
    some target in input.resource.targets
    target.type == "TABLE"
}

Testing Policies

OPA supports policy testing using opa test. Create a test file (e.g., polaris_test.rego):

package polaris.authz

import future.keywords.if

test_admin_can_create_catalog if {
    allow with input as {
        "actor": {"principal": "admin", "roles": ["ADMIN"]},
        "action": "CREATE_CATALOG",
        "resource": {
            "targets": [{
                "type": "CATALOG",
                "name": "new_catalog",
                "parents": []
            }],
            "secondaries": []
        },
        "context": {"request_id": "test"}
    }
}

test_admin_cannot_grant_privileges if {
    not allow with input as {
        "actor": {"principal": "admin", "roles": ["ADMIN"]},
        "action": "ADD_PRINCIPAL_GRANT_TO_PRINCIPAL_ROLE",
        "resource": {
            "targets": [{
                "type": "PRINCIPAL_ROLE",
                "name": "some_role",
                "parents": []
            }],
            "secondaries": []
        },
        "context": {"request_id": "test"}
    }
}

test_data_engineer_can_create_table if {
    allow with input as {
        "actor": {"principal": "engineer", "roles": ["DATA_ENGINEER"]},
        "action": "CREATE_TABLE_DIRECT",
        "resource": {
            "targets": [{
                "type": "TABLE",
                "name": "new_table",
                "parents": [
                    {"type": "CATALOG", "name": "prod"},
                    {"type": "NAMESPACE", "name": "schema1"}
                ]
            }],
            "secondaries": []
        },
        "context": {"request_id": "test"}
    }
}

test_data_engineer_cannot_delete_catalog if {
    not allow with input as {
        "actor": {"principal": "engineer", "roles": ["DATA_ENGINEER"]},
        "action": "DELETE_CATALOG",
        "resource": {
            "targets": [{
                "type": "CATALOG",
                "name": "prod",
                "parents": []
            }],
            "secondaries": []
        },
        "context": {"request_id": "test"}
    }
}

test_analyst_can_read_table if {
    allow with input as {
        "actor": {"principal": "analyst", "roles": ["ANALYST"]},
        "action": "LOAD_TABLE_WITH_READ_DELEGATION",
        "resource": {
            "targets": [{
                "type": "TABLE",
                "name": "data_table",
                "parents": [
                    {"type": "CATALOG", "name": "prod"},
                    {"type": "NAMESPACE", "name": "schema1"}
                ]
            }],
            "secondaries": []
        },
        "context": {"request_id": "test"}
    }
}

test_analyst_cannot_update_table if {
    not allow with input as {
        "actor": {"principal": "analyst", "roles": ["ANALYST"]},
        "action": "UPDATE_TABLE",
        "resource": {
            "targets": [{
                "type": "TABLE",
                "name": "data_table",
                "parents": [
                    {"type": "CATALOG", "name": "prod"},
                    {"type": "NAMESPACE", "name": "schema1"}
                ]
            }],
            "secondaries": []
        },
        "context": {"request_id": "test"}
    }
}

Run tests:

opa test policies/

Additional Resources

• OPA Documentation
• Rego Language Guide
• OPA Policy Testing
• OPA Bundles