Enforce a partner guardrail with an external service policy

Important

This feature is in Beta. Account admins can control access to this feature from the account console Previews page. See Manage Azure Databricks previews.

An external service policy enforces the decisions of a guardrail vendor you already use, such as an AI security or data-loss-prevention service, on traffic through Unity Gateway. On every governed call, Azure Databricks sends the content under evaluation to your vendor's endpoint. The vendor returns allow or deny, and Azure Databricks enforces that decision, with no changes to your applications.

You attach an external service policy to a Model Service, Model Provider Service, or MCP Service, the same way you attach any service policy.

How external service policies work

An external service policy has three parts:

A Unity Catalog HTTP connection stores your vendor's endpoint URL and its OAuth credentials. Several policies can share one connection.
The external service policy is attached to a service. It names the connection and sets the phase, rank, mode, and an optional policy configuration. Azure Databricks runs it on each request and enforces the result.
Your vendor's guardrail inspects the content and returns a verdict: ALLOW or DENY, with an optional reason.

Your vendor must implement the Azure Databricks external policy API, which defines the request Azure Databricks sends and the verdict it expects back. Ask your vendor whether they support it and for the endpoint details. Azure Databricks doesn't build or maintain integrations for individual vendors.

Before you begin

You need:

An endpoint from your guardrail vendor that implements the Azure Databricks external policy API.
OAuth machine-to-machine (M2M) credentials for that endpoint: a client ID, a client secret, and the vendor's token endpoint URL. OAuth M2M is the only supported authentication method. API keys, basic authentication, and user-to-machine OAuth aren't supported.
Permissions to create the connection: the CREATE CONNECTION privilege, plus USE CATALOG and USE SCHEMA on the catalog and schema where the connection is stored.
Permissions to attach the policy: MANAGE on the service you want to govern, USE CONNECTION on the connection, and USE CATALOG and USE SCHEMA on the connection's catalog and schema.

The two sets of permissions can belong to different people. If the person attaching the policy doesn't have CREATE CONNECTION, the person who manages the vendor credentials can create the connection ahead of time and grant them USE CONNECTION.

Step 1: Create a connection to your vendor

The connection is a Unity Catalog object that stores your vendor's endpoint and credentials. You can create it in either of two ways:

While you attach the policy: in the policy form, select Create new connection. This is the quickest option for a single guardrail.
Ahead of time: create an HTTP connection with OAuth machine-to-machine authentication in Catalog Explorer or with CREATE CONNECTION, then select Use existing connection in the policy form. Use this option when several policies share one endpoint, or when a different team manages the vendor credentials. See Create a connection to the external service.

When you create the connection from the policy form, enter the following:

Field	Description
Connection name	A name for the Unity Catalog connection, for example `external_guardrail`.
Catalog and Schema	Where the connection is stored in Unity Catalog.
Host	Your vendor's host, including the scheme, for example `https://api.example.com`.
API path (optional)	A path on that host, for example `/ai-security/v1`.
Auth type	Always OAuth M2M. This field can't be changed.
Client ID and Client secret	The service account credentials your vendor issued.
Token endpoint	Your vendor's OAuth token URL, for example `https://api.example.com/oidc/v1/token`.
OAuth scope (optional)	Space-separated scopes, if your vendor requires them, for example `guardrail.read guardrail.scan`.

Vendors typically serve many policies from one endpoint and tell them apart with the policy configuration you set in Step 2. You usually create one connection per vendor endpoint, not one per policy.

Step 2: Attach the external service policy

In the workspace sidebar, click AI Gateway.
Select the service to govern: a model service on the Models tab, a model provider service on the Providers tab, or an MCP service on the MCPs tab.
Open the Policies tab, then click New policy.
Enter a Name for the policy.
In Guardrail type, select External.
Set the Rank to control evaluation order relative to other policies on the service. The lowest rank runs first on the request and last on the response, and a DENY stops all later ranks. At the same rank, only a DENY from a blocking LLM-as-a-judge policy skips the call to your vendor. A DENY from a custom SQL policy or another sequential policy at the same rank doesn't, so your vendor still receives the content. To skip the vendor call when that policy denies, put it at a rank that's evaluated before the external service policy's rank. See Order of evaluation.
Under Phase, select Input guardrails (before the service is called), Output guardrails (after it responds), or both. Choose input only if your vendor inspects only requests. Each phase is a separate call to your vendor, so selecting both phases roughly doubles the number of calls.
Select the connection. Choose Use existing connection and select it from the list, or choose Create new connection and complete the fields from Step 1.
(Optional) In Policy configuration, enter a JSON object, for example {"profile": "strict"}. Azure Databricks doesn't read this value. It passes the text to your vendor on every request, exactly as you entered it. Your vendor's documentation lists the keys it accepts. Leave it empty if your vendor doesn't need one.
Expand Advanced options and select a Mode:
- Enforce applies the vendor's decision. A DENY blocks the call.
- Log evaluates the policy and records the would-be verdict without blocking anything. Review the results in the unified trace table, where each evaluation is a policy_evaluated event with the would-be verdict in policy.dry_run_action and policy.dry_run_reason. See Policy evaluation events. If the service has an inference table, results are also recorded there.
Click Create policy.

Azure Databricks recommends starting in Log mode. Let real traffic flow through the policy, review what it would have blocked, and then switch to Enforce.

Note

Log mode doesn't block calls, but every evaluation still calls your vendor and uses whatever quota or per-call charges your vendor contract includes. Set up the unified trace table, or an inference table on the service, before you start, so you can review the evaluations you pay for.

Step 3: Test the policy

After you attach or change a policy, allow time for the change to propagate before you test. Propagation typically takes 60 to 90 seconds.

Then send a request that your vendor's guardrail should catch. In Enforce mode, Azure Databricks blocks the call and returns a successful (HTTP 200) response with a databricks_service_policy object, as for any blocking service policy. See Policy decisions. The block reason is your vendor's explanation. If your vendor doesn't return one, the caller sees the default reason:

Access denied: this request is not permitted by a policy on this service.

What Azure Databricks sends to your vendor

On each evaluation, Azure Databricks sends your vendor the content under evaluation, the name of the governed service, and the policy configuration you set. The content depends on the service and the phase:

Service	Phase	Content sent
MCP Service	Input	The tool name and its arguments.
MCP Service	Output	The tool result, along with the originating tool call.
Model Service or Model Provider Service	Input	The full model request body, such as the messages.
Model Service or Model Provider Service	Output	The full model response body, along with the originating request.

Model request and response bodies are sent in the API format the caller used, such as OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, or Gemini. Azure Databricks doesn't convert them to a common format.

Azure Databricks sends your vendor content only, not the caller's identity. When the request has a trace, Azure Databricks also sends its trace ID, so you can match an evaluation in your vendor's logs to the request.

Review network egress before you attach a policy

An external service policy sends the content under evaluation, which can include raw model requests and responses or MCP tool arguments and results, to a third-party service. Before you attach the policy, review your vendor's data-handling practices and confirm the connection's target.

A Unity Catalog connection governs credentials and connection configuration. It doesn't restrict which network destinations are reachable. External service policies don't require a restricted network policy, so if your workspace doesn't have one, outbound access is unrestricted, and a policy can send evaluated content to any endpoint reachable through a configured connection.

Azure Databricks recommends applying a restricted-access network policy that allows only approved policy service destinations. See Connections and network policies and Manage network policies for serverless egress control.

Fail-closed behavior

External service policies fail closed. If your vendor's endpoint times out, returns an error, returns a response Azure Databricks can't parse, or returns a verdict other than ALLOW or DENY, Azure Databricks denies the call. You can't configure an external service policy to let traffic through when the vendor is unavailable.

In Enforce mode, this puts your vendor's availability and latency on the critical path of every governed call:

Confirm your vendor's latency and availability before you enforce the policy. Azure Databricks waits about 5 seconds for a response. Slower responses are denied.
Log mode doesn't mask endpoint problems. A failing endpoint still records DENY results, so many unexpected denies in Log mode are a sign to fix the endpoint before you switch to Enforce.

Limitations

The following limitations apply:

Allow and deny only: External service policies return ALLOW or DENY. They can't hold a call for human approval (ASK), and they can't redact or rewrite content.
One service at a time: You attach a policy to a single service. Attaching one policy across many services at once isn't available.
UI only: You attach external service policies through the Unity Gateway UI. Attaching them through the REST API or Terraform isn't available.
OAuth M2M only: The connection must use OAuth machine-to-machine authentication.
Vendor support required: Your vendor must implement the Azure Databricks external policy API. Azure Databricks doesn't provide per-vendor adapters.

Troubleshooting

Symptom	Likely cause
The policy has no effect right after you attach it.	You tested within the propagation window, which typically takes 60 to 90 seconds. Wait, then try again.
Every call is denied.	The endpoint is unreachable, returns errors, or times out, so the policy fails closed. Check the host, path, and credentials on the connection, then check the endpoint's health with your vendor.
Every call is denied, and the reason says the result is unrecognized.	Your vendor returned a verdict other than `ALLOW` or `DENY`. Contact your vendor.
Denied calls show the default reason instead of your vendor's.	Your vendor didn't return a reason, so Azure Databricks shows the default text.
Log mode shows no results.	Neither the unified trace table nor an inference table on the service is set up, so Log mode results aren't recorded anywhere you can query. The policy still calls your vendor.
The connection saves, but calls fail.	The credentials or token endpoint are wrong. Confirm the client ID, client secret, token endpoint, and any required scopes with your vendor.

Next steps

Feedback

Was this page helpful?

Last updated on 2026-10-08