flyrain commented on code in PR #3030: URL: https://github.com/apache/polaris/pull/3030#discussion_r2524346676
########## site/content/in-dev/unreleased/managing-security/external-pdp/opa.md: ########## @@ -0,0 +1,363 @@ +--- +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# +title: Open Policy Agent (OPA) Integration +linkTitle: OPA +type: docs +weight: 100 +--- + +{{< alert warning "Experimental Feature" >}} +**OPA integration is currently an experimental feature** and may undergo breaking changes in future versions. Use with caution in production environments. +{{< /alert >}} + +This page describes how to integrate Apache Polaris (Incubating) with [Open Policy Agent (OPA)](https://www.openpolicyagent.org/) 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: + +```bash +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`): + +```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: + +```properties +# 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 + +| Property | Required | Default | Description | +|----------|----------|---------|-------------| +| `polaris.authorization.type` | Yes | `internal` | Set to `opa` to enable OPA authorization | +| `polaris.authorization.opa.policy-uri` | Yes | - | Full URI to the OPA policy decision endpoint (must be http or https) | + +### HTTP Configuration + +| Property | Required | Default | Description | +|----------|----------|---------|-------------| +| `polaris.authorization.opa.http.timeout` | No | `PT2S` | HTTP request timeout (ISO-8601 duration format, e.g., `PT2S`, `PT10S`) | +| `polaris.authorization.opa.http.verify-ssl` | No | `true` | Whether to verify SSL certificates | +| `polaris.authorization.opa.http.trust-store-path` | No | - | Path to the trust store containing CA certificates | +| `polaris.authorization.opa.http.trust-store-password` | No | - | Password for the trust store | + +### Authentication Configuration + +OPA integration supports two authentication modes: + +#### No Authentication (default) + +No authentication configuration needed if OPA server doesn't require authentication: + +```properties +polaris.authorization.opa.auth.type=none +``` + +#### Bearer Token Authentication + +**Static Bearer Token:** + +Use a static bearer token: + +```properties +polaris.authorization.opa.auth.type=bearer +polaris.authorization.opa.auth.bearer.static-token.value=your-secret-token +``` + +| Property | Required | Default | Description | +|----------|----------|---------|-------------| +| `polaris.authorization.opa.auth.type` | No | `none` | Set to `bearer` to enable bearer token authentication | +| `polaris.authorization.opa.auth.bearer.static-token.value` | Yes* | - | The bearer token value (*when using static token) | + +**File-Based Bearer Token with Auto-Refresh:** + +Use a bearer token from a file with automatic refresh (ideal for JWT tokens): + +```properties +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 +``` + +| Property | Required | Default | Description | +|----------|----------|---------|-------------| +| `polaris.authorization.opa.auth.type` | No | `none` | Set to `bearer` to enable bearer token authentication | +| `polaris.authorization.opa.auth.bearer.file-based.path` | Yes* | - | Path to file containing the bearer token (*when using file-based token) | +| `polaris.authorization.opa.auth.bearer.file-based.refresh-interval` | No | - | How often to refresh the token (ISO-8601 duration, e.g., `PT5M` for 5 minutes). If not set and JWT refresh is disabled, token won't be refreshed | +| `polaris.authorization.opa.auth.bearer.file-based.jwt-expiration-refresh` | No | `true` | Automatically detect JWT tokens and refresh based on expiration time | +| `polaris.authorization.opa.auth.bearer.file-based.jwt-expiration-buffer` | No | `PT1M` | Buffer time before JWT expiration to trigger refresh (ISO-8601 duration) | + +**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: + +```json +{ + "actor": { + "principal": "[email protected]", + "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 + +| Field | Type | Description | +|-------|------|-------------| +| `principal` | string | The principal identifier (e.g., username, service account) | +| `roles` | array | Array of role names assigned to the principal | + +#### 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](https://github.com/apache/polaris/blob/main/polaris-core/src/main/java/org/apache/polaris/core/auth/PolarisAuthorizableOperation.java) 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` Review Comment: Sorry for the typo. It's NOT a blocker. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
