OPAL (Open Policy Administration Layer)

Permit OPAL+ is an enterprise software service package provided by Permit Inc. It is designed for enterprise users who require additional capabilities beyond the open-source OPAL project.

Key offerings include:

• Early access to features via a special license for an internal OPAL version.
• Hosted OPAL servers.
• Hosted policy decision points (OPAL-client + OPA / Cedar).
• Direct influence on the project roadmap.
• Dedicated support channels and custom SLAs.
• Professional services and custom data-fetcher providers (including NRE).

OPAL (Open Policy Administration Layer) is a tool designed to supercharge Open Policy Agent (OPA) by providing real-time updates for both policy and data. While OPA decouples policy from code, OPAL ensures that the authorization layer stays in sync with live application state changes (such as user clicks or API calls) using Websocket Pub/Sub.

Key capabilities include:

• Real-time updates: Uses Websocket Pub/Sub to push policy and data changes to policy agents.
• Decoupling: Separates policy (typically git-driven) from data (via distributed data-source fetching engines).
• Cloud-native architecture: Designed for microservices and distributed environments.

OPAL (Open Policy Administration Layer) uses a client-server stateless architecture to keep policy engines (like OPA or AWS Cedar Agent) in sync with real-time changes in policy and data.

How it works:

1. OPAL-Servers detect changes in policy or data sources (APIs, DBs, Git, S3, etc.).
2. OPAL-Servers publish updates over a lightweight WebSocket PubSub channel.
3. OPAL-clients subscribe to specific topics via the PubSub channel.
4. Upon receiving an update, each OPAL-client fetches the data directly from the source to load it into its managed Policy Engine instance.

OPAL clients manage two distinct types of data sources:

1. Policies (and static data): These are policy bundles (similar to OPA native bundles) containing Rego policies and data that rarely changes. The default source is a Git repository, or an API server exposing tar bundles.

2. Dynamic Data: These are DataSourceEntry objects which act as "directives" telling OPAL how to fetch real-time data (e.g., from a database or 3rd party API) and where to place it in the OPA document tree. OPAL_DATA_CONFIG_SOURCES contains these directives.

OPAL manages authorization layers in realtime using a Websocket Pub/Sub channel between OPAL-clients and OPAL-servers.

Key architectural characteristics:

• Realtime Updates: Each OPAL-client (and its associated policy agent) subscribes to a websocket channel to receive instant updates.
• Statelessness: Both OPAL-clients and OPAL-servers are stateless to support scaling. State is maintained in the end components (e.g., the OPA agent acting as an edge cache) and the original data sources (e.g., Git, databases).
• Networking: OPAL uses outgoing websocket connections to establish Pub/Sub channels, which helps bypass most routing and firewall concerns.

OPAL operates using a server-client model to manage policy and data for policy agents (such as OPA, Cedar-agent, or AWS AVP):

1. OPAL Server: Acts as the central orchestrator. It tracks policy changes (from Git or API bundle servers) and data changes (from webhooks or Fetch-Providers).
2. OPAL Clients: Subscribe to the server via pub/sub over websockets. The server sends instructions to clients to load new policies or data.
3. Policy Agents: Managed by the OPAL clients, these agents (e.g., OPA, Cedar-agent) receive the loaded policy and data to perform authorization decisions.

When an OPAL client or policy agent restarts, both policy and data are loaded from scratch.

The fastest way to run a working configuration of both OPAL server and OPAL client on your local machine is to use the provided Docker Compose example. This command downloads the example configuration and starts the services immediately.

curl -L https://raw.githubusercontent.com/permitio/opal/master/docker/docker-compose-example.yml \
> docker-compose.yml && docker compose up

When using an external data source, your API server must perform the following steps:

1. Expose an HTTP GET endpoint matching the path provided in the OPAL configuration.
2. Extract the JWT: Retrieve the OPAL client JWT from the token query parameter.
3. Validate the JWT: Use the OPAL public key to verify the token's authenticity.
4. Determine Configuration: Use custom claims within the validated JWT to decide which DataSourceEntry configuration to return to that specific client.
5. Return JSON: Respond with a JSON object representing the OPAL_DATA_CONFIG_SOURCES (the list of actual data source entries) for that client.

To use the opal-client CLI for publishing data updates, install it within a Python virtual environment using pip.

pyenv virtualenv opaldemo

pyenv activate opaldemo

pip install opal-client