Introduction

What are Policies?

Formal’s policy system uses Open Policy Agent (OPA), an open-source policy engine that enables you to express access control rules as code. Policies are evaluated in real-time as users connect to resources and execute queries. Your policies can:

Block connections to resources or specific tables/schemas
Redact query results automatically
Encrypt and decrypt HTTP secrets (for example OAuth tokens) with encrypt / decrypt
Rewrite queries before they reach the database
Filter and limit result sets
Enforce MFA for sensitive operations

How Policies Work

Policies are written in Rego, OPA’s purpose-built language for access control. They are evaluated at three stages:

Session - When a connection is established
Request - Before a query reaches the resource
Response - When data returns from the resource

Each stage has specific actions available based on when the policy is evaluated. See Enforcement for details on available actions.

Policy Structure

Every policy consists of these essential components:

Name

A unique identifier for the policy. No two policies can share the same name.

Description

A clear explanation of the policy’s purpose and scope. This helps other admins understand what the policy does.

Owners

The administrators responsible for maintaining and enforcing the policy. Owners receive notifications when policies are triggered (if configured).

Code

The policy logic, written in Rego, OPA’s purpose-built language for access control.

Policy Status

Policies can be in one of three states:

Status	Description	Use Case
Draft	Under development, not enforced	Writing and testing new policies
Dry-run	Logs violations without enforcing	Testing policies with real traffic before enforcement
Active	Fully enforced and monitoring	Production enforcement

Use dry-run mode to test policies against real traffic without impacting users. Review the logs to ensure the policy works as intended before activating it.

Notifications

Configure notifications for policy triggers:

None: No notifications sent
Consumer: Notify the user who triggered the policy
Owners: Notify policy owners
All: Notify both user and owners

Notifications can be sent via:

Email
Slack (requires integration setup)

Policy Tags

Tags are key/value metadata on a policy, such as team = "data-platform". A policy can have up to 500 tags. Tags don’t change how a policy is evaluated. Set tags with the API or Terraform:

resource "formal_policy" "block_deletes" {
  name   = "block-production-deletes"
  status = "active"
  code   = file("${path.module}/policies/block-deletes.rego")

  tags = {
    team   = "data-platform"
    ticket = "SEC-123"
  }
}

Generated Policies

Product features create policies for you, such as Guardrails and Catalog access controls. Formal marks them with reserved tags:

Tag	Value
`formal:generated`	`true`
`formal:generated-policy:kind`	The feature that owns the policy, such as `guardrails:unknown-mcp`, `guardrails:unknown-skill`, `registry:mcp-access`, or `registry:skill-access`
`formal:generated-policy:key`	The item the policy belongs to, such as an MCP server or a skill

Change generated policies from the feature that owns them. Don’t use the formal:generated prefix for your own tags.

End-User Identity Propagation

Formal can extract end-user identity from applications like Looker, Metabase, or Retool, enabling policies that work for both direct connections and application-mediated access:

Direct connection: Alice uses psql to query a resource → user and end-user are both Alice
Application connection: Katie uses Metabase → user is the machine user, end-user is Katie

This allows you to write policies that consider the actual person behind the query, even when they’re using a BI tool.

Quick Example

Block all connections by default, but allow admins using a specific machine user:

package formal.v2

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

default session := {
  "action": "block",
  "type": "block_with_formal_message"
}

session := {
  "action": "allow",
  "reason": "Admin access via authorized app"
} if {
  "admin" in input.end_user.groups
  input.user.username == "idp:formal:machine:backoffice"
  not input.end_user.email == "john.doe@joinformal.com"
}

Managing Policies

Control Plane
Terraform

Navigate to Policies
Click Create Policy
Fill in name, description, and owners
Write Rego code in the editor
Set status (Draft, Dry-run, or Active)
Configure notifications
Click Create Policy to save

resource "formal_policy" "block_deletes" {
  name        = "block-production-deletes"
  description = "Prevent DELETE statements in production"
  status      = "active"

  code = <<-EOT
    package formal.v2

    import future.keywords.if

    request := {
      "action": "block",
      "type": "block_with_formal_message",
      "reason": "DELETE not allowed in production"
    } if {
      input.resource.environment == "production"
      input.sql_query.statement_type == "DELETE"
    }
  EOT

  owners = ["admin@example.com"]

  notifications = "owners"
}

Best Practices

Start with Dry-Run

Always test new policies in dry-run mode first. Review logs to ensure they work as expected before activating.

Use Groups for User Policies

Instead of writing policies for individual users, use groups. This makes policies scalable and easier to maintain.

Document Your Policies

Write clear descriptions and use meaningful reason fields. Future you (and your team) will thank you during audits.

Leverage External Data

Use Policy Data Loaders to fetch dynamic approval lists, compliance data, or business logic from external systems.

Learn More

Policy Evaluation

Input data, evaluation stages, and available context

Enforcement

Actions including encrypt, decrypt, block, mask, and rewrite

Encrypt MCP OAuth Tokens

Seal Notion MCP OAuth tokens on the Endpoint or Connector

Restrict Anthropic Sign-Ins

Allow Claude sign-ins only for your Anthropic organization ID

Restrict Codex Desktop Egress

Allow Codex Desktop egress only through LLM and named MCP resources

Examples

Real-world policy examples and common use cases

Getting Started

Example Use Cases

AI Governance

Configuring Formal

Integrations

Configuration

What are Policies?

How Policies Work

Policy Structure

Policy Status

Notifications

Policy Tags

Generated Policies

End-User Identity Propagation

Quick Example

Managing Policies

Best Practices

Learn More

Policy Evaluation

Enforcement

Encrypt MCP OAuth Tokens

Restrict Anthropic Sign-Ins

Restrict Codex Desktop Egress

Examples

​What are Policies?

​How Policies Work

​Policy Structure

​Policy Status

​Notifications

​Policy Tags

​Generated Policies

​End-User Identity Propagation

​Quick Example

​Managing Policies

​Best Practices

​Learn More

Policy Evaluation

Enforcement

Encrypt MCP OAuth Tokens

Restrict Anthropic Sign-Ins

Restrict Codex Desktop Egress

Examples

What are Policies?

How Policies Work

Policy Structure

Policy Status

Notifications

Policy Tags

Generated Policies

End-User Identity Propagation

Quick Example

Managing Policies

Best Practices

Learn More