Business Intelligence

Overview

Formal integrates with Business Intelligence applications to enable end-user identity propagation. This ensures that queries from BI tools are attributed to the actual end-user rather than a shared machine user, enabling accurate auditing and per-user policy enforcement.

How It Works

When you set up a BI integration:

Sync: Formal Control Plane synchronizes with your BI application to fetch user identities
Map: External IDs are automatically assigned to your Formal users
Propagate: When BI tool users execute queries, their identity is passed to the Connector
Enforce: Policies evaluate based on the end-user, not the BI tool’s machine user

The Connector automatically fetches user information from the Control Plane, so no additional configuration is needed in your Connector deployment.

Supported BI Applications

Metabase
Looker
Omni
Tableau
Power BI
Custom applications (via SQL commenter)

Setup

Metabase

Navigate to BI Integrations

Go to BI Integrations in the Formal console

Add Integration

Click Add New App

Select Metabase

Choose Metabase from the list

Enter Credentials

Server Hostname: Your Metabase instance URL
Admin Username: Metabase admin username
Admin Password: Metabase admin password

Allow-list IPs

If your Metabase instance has IP restrictions, allow-list these IPs:

52.18.34.8
52.51.88.92
54.72.150.112

When connecting Metabase, the admin user will receive a “We’ve Noticed a New Metabase Login” email alert from a location in Ireland (where Formal’s workers run).

Terraform

resource "formal_integration_bi" "metabase" {
  name = "production-metabase"
  sync = true

  metabase {
    hostname = "metabase.example.com"
    username = "admin@example.com"
    password = var.metabase_admin_password
  }
}

Looker

Looker supports end-user identity propagation via JDBC connection parameters.

Open Database Connection

Go to Admin → Connections in Looker

Edit Connection

Select your database connection

Add Parameter

In the “Additional Params” section, add:

options=formal_enduser={{ _user_attributes['email'] }}

Save

Save the connection settings

This configuration tells Looker to pass the end-user’s email in the connection string, which Formal extracts and uses for policy evaluation.

Omni

Omni supports connecting to Snowflake through the Formal Connector using a host override. Unlike other BI tools that embed end-user identity in SQL comments, Omni propagates identity at session login time via the QUERY_TAG session parameter containing the omniOrganizationUserId.

Connection Setup

Add a Snowflake Connection

In Omni, go to your connection settings and select Snowflake as the database type.

Choose Host & Port

Select the Host & port connection option instead of the default account identifier method.

Configure Host Override

Set the host override to account.<connector-hostname>, where <connector-hostname> is your Formal connector hostname. For example:

account.my-org.connectors.joinformal.com

The account. prefix is required for the connector to correctly route Snowflake requests.

Set Port

Set the port to match the listener port configured for your Snowflake resource on the connector (e.g., 1443).

Set Database and Warehouse

Specify the Database and Warehouse that match your Snowflake resource configuration.

Configure Authentication

If the native user on your Formal resource uses key-pair authentication (SNOWFLAKE_JWT):

Select Key Pair Authentication as the authentication type
Set the Username to your Formal machine user (e.g., idp:formal:machine:omni)
Add a keypair using the private key available via the Download Private Key button on the machine user details page in the Formal console

If the native user uses password authentication, enter the machine user’s Formal token as the password instead.

Test Connection

Save and test the connection to verify queries are routed through the Formal Connector.

End-User Identity Setup

Create Omni Integration

In the Formal console, go to BI Integrations and create a new Omni integration.

Map External IDs

Open the Formal user → External Connections, click Map External ID, select the Omni integration, and set the external ID to the user’s omniOrganizationUserId in Omni.

Verify

Run a query through Omni and check Logs to confirm the end-user is correctly attributed.

Omni resolves end-user identity once per session at login time. All queries within that session are attributed to the resolved end-user. For more details on how this works at the Snowflake proxy level, see Snowflake End-User Identity Propagation.

Custom Applications

For internal applications or custom BI tools, use the formal-sqlcommenter library to propagate end-user identity.

Python/Django

Install the package:

pip install formal-sqlcommenter

Use in your application:

from formal_sqlcommenter import add_sql_comment
import psycopg2

# Connect as machine user
conn = psycopg2.connect(
    host="connector.joinformal.com",
    port=5432,
    user="idp:formal:machine:my_app",
    password="machine_user_token",
    database="production_db"
)

# Add end-user ID to queries
cursor = conn.cursor()
query = "SELECT * FROM users WHERE id = %s"

# This query will be attributed to the human user
commented_query = add_sql_comment(
    query,
    external_user_id="katie@example.com"  # End-user's Formal external ID
)

cursor.execute(commented_query, (123,))

Configuring External IDs

External IDs map end-users in external systems to Formal users.

Create Formal User

Ensure a Formal user exists for the BI tool user

Map External ID

Open the Formal user → External Connections, then click Map External ID. Choose the BI integration and enter the user’s ID from the BI tool. For example, if Katie’s Looker user ID is 12345, map 12345 to Katie’s Formal user.

Verify

Check Logs to confirm queries are attributed to the correct end-user

Automatic Sync

For Metabase and other integrated BI tools, Formal automatically:

Fetches user lists from the BI application
Matches them to Formal users by email
Assigns external IDs

No manual configuration needed!

Policy Examples

End-User Access Control

package formal.v2

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

# Block if end-user (not machine user) lacks access
session := {
  "action": "block",
  "type": "block_with_formal_message",
  "message": "You do not have permission to access this resource",
  "reason": "End-user not in approved group"
} if {
  # Connection is from BI tool (machine user)
  input.user.type == "machine"

  # End-user is not in analyst group
  not "analyst" in input.end_user.groups
}

Per-User Data Masking

package formal.v2

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

# Mask PII unless end-user has special access
response := {
  "action": "mask",
  "type": "nullify",
  "columns": pii_columns
} if {
  # Identify PII columns
  pii_columns := [col |
    col := input.row[_]
    col["data_label"] in ["email", "ssn", "phone"]
  ]

  count(pii_columns) > 0

  # End-user doesn't have PII access
  not "pii_access" in input.end_user.groups
}

Audit BI Tool Access

package formal.v2

import future.keywords.if

# Log all BI tool queries with end-user context
request := {
  "action": "allow",
  "reason": "BI tool query logged",
  "contextual_data": sprintf(
    "BI User: %s, Tool: %s, Query: %s",
    [input.end_user.email, input.user.username, input.query.query]
  )
} if {
  input.user.type == "machine"
  startswith(input.user.username, "idp:formal:machine:")
}

Monitoring

View End-User Attribution

Navigate to Logs
Filter by machine user (BI tool)
Check “End User” column to see attributed end-users
Verify queries are attributed correctly

Session Details

In Sessions, you’ll see:

User: Machine user (BI tool)
End-User: Actual human user in the BI tool
Queries: Full query history with end-user attribution

Troubleshooting

Queries not attributed to end-users

Possible causes:

BI integration not set up
External IDs not mapped
BI tool not passing end-user information

Solution:

Verify the BI integration is active in the Formal console
On the Formal user → External Connections, confirm the external ID matches the BI tool user ID
For Looker, verify JDBC parameters are configured
Review Connector logs for end-user extraction errors

Metabase sync not working

Possible causes:

Incorrect admin credentials
IP allow-list blocking Formal workers
Metabase instance not reachable

Solution:

Verify admin credentials are correct
Allow-list Formal worker IPs (see above)
Check Metabase logs for authentication attempts
Ensure Metabase instance is publicly accessible or VPN-accessible by Formal

Policies not evaluating for end-users

Possible causes:

Policy references input.user instead of input.end_user
End-user not in expected groups

Solution:

Update policies to use input.end_user for BI tool queries
Verify end-user’s group memberships in Formal console
Test policy in dry-run mode and review logs

Best Practices

Always Use End-User Policies

For BI tools, write policies that evaluate input.end_user attributes, not input.user (which is the machine user).

Implement Row-Level Security

Use end-user attributes to filter results, ensuring each BI user only sees data they’re authorized to access.

Audit BI Access

Regularly review logs to ensure end-user attribution is working and no queries are misattributed.

Sync Regularly

For integrated BI tools, Formal syncs user lists automatically. For custom apps, update external IDs when users are added/removed.

Next Steps

Configure External IDs

Map BI users to Formal users

Write Policies

Create end-user-based policies

View Logs

Monitor end-user queries

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

Overview

How It Works

Supported BI Applications

Setup

Metabase

Terraform

Looker

Omni

Connection Setup

End-User Identity Setup

Custom Applications

Python/Django

Configuring External IDs

Automatic Sync

Policy Examples

End-User Access Control

Per-User Data Masking

Audit BI Tool Access

Monitoring

View End-User Attribution

Session Details

Troubleshooting

Best Practices

Next Steps

Configure External IDs

Write Policies

View Logs

​Overview

​How It Works

​Supported BI Applications

​Setup

​Metabase

​Terraform

​Looker

​Omni

​Connection Setup

​End-User Identity Setup

​Custom Applications

​Python/Django

​Configuring External IDs

​Automatic Sync

​Policy Examples

​End-User Access Control

​Per-User Data Masking

​Audit BI Tool Access

​Monitoring

​View End-User Attribution

​Session Details

​Troubleshooting

​Best Practices

​Next Steps

Configure External IDs

Write Policies

View Logs

Overview

How It Works

Supported BI Applications

Setup

Metabase

Terraform

Looker

Omni

Connection Setup

End-User Identity Setup

Custom Applications

Python/Django

Configuring External IDs

Automatic Sync

Policy Examples

End-User Access Control

Per-User Data Masking

Audit BI Tool Access

Monitoring

View End-User Attribution

Session Details

Troubleshooting

Best Practices

Next Steps