---
schema_version: "1"
id: cf462e7cf526a0a09de0af00e3a83574f0a154ad81c2f7990345c16c9b94487d
title: Azure Content Safety Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/latest/policies-included-azure-content-safety.md
canonical_url: https://docs.mulesoft.com/gateway/latest/policies-included-azure-content-safety
source_site: docs.mulesoft.com
content_type: documentation
content_hash: e03c70f165d5a09ac74e59d4bbd2a51a010ed611921d01644d095f53b92fac27
description: MuleSoft Documentation Site
release: "1.14"
latest: true
---
---
product: Omni Gateway
version: 1.14
is-latest-version: true
keywords: api gateway, flex gateway, gateway, policy, llm, content safety, azure, guardrails, harm detection
---

# Azure Content Safety Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy Name</strong></p></td><td><p>Azure Content Safety Policy</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Evaluates LLM prompts and responses against Azure AI Content Safety for harmful content, jailbreak attempts, hallucinations, and copyrighted material</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>LLM</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.13.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/azure-content-safety-release-notes">Azure Content Safety Policy</a></p></td></tr><tr><td rowspan="2"><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden: Content violates Azure Content Safety policies</p></td></tr><tr><td><p>503 - Service Unavailable: Azure API call failed (only when fail-open is disabled)</p></td></tr></tbody></table>

## Summary

The Azure Content Safety policy provides comprehensive content moderation for LLM-based APIs by
evaluating prompts and responses against the Azure AI Content Safety service. The policy integrates
with
[Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)
to enforce content safety policies including:

- **Content filters**: Detects and blocks harmful content across four categories (**Hate**,
  **SelfHarm**, **Sexual**, and **Violence**) with configurable severity thresholds (`0`, `2`, `4`,
  `6`).

- **Prompt Shield**: Detects jailbreak attempts and indirect prompt-injection attacks using Azure’s
  advanced detection capabilities.

- **Blocklists**: Blocks content matching Azure-managed custom blocklists you define in Azure
  Content Safety Studio.

- **Groundedness Detection**: Evaluates whether LLM responses are grounded in provided reference
  text (hallucination detection for RAG applications).

- **Protected Material Detection**: Detects known copyrighted text in LLM responses.

The policy operates in two independent phases:

- **Request phase**: Moderates user prompts before they reach the upstream LLM, preventing harmful
  or inappropriate prompts from being processed.

- **Response phase**: Moderates LLM responses before they reach the client, ensuring outputs comply
  with safety policies. Streaming responses (`text/event-stream`) aren’t moderated.

When content violates safety policies, the request is rejected with a `403` error code and never
reaches the LLM (request phase) or the client receives a `403` instead of the LLM response (response
phase).

## Before You Begin

Before configuring this policy, you need:

1.  **Azure Account** with access to Azure AI Content Safety

2.  **Azure Content Safety Resource** created in the Azure Portal

3.  **Subscription Key** from the Azure Portal (Keys and Endpoint section)

4.  **Resource Endpoint URL** from the Azure Portal

## Configuring Policy Parameters

### Omni Gateway Local Mode

The Azure Content Safety policy isn’t supported in Local Mode.

### Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

### Basic Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>Azure Content Safety Endpoint</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety endpoint base URL, for example, <code>https://&lt;resource&gt;.cognitiveservices.azure.com</code>.</p></div></div></td></tr><tr><td><div><div><p>Azure API Key</p></div></div></td><td><div><div><p>Yes</p></div></div></td><td><div><div><p>Azure Content Safety subscription key. The key is passed in the <code>Ocp-Apim-Subscription-Key</code> header.</p></div></div></td></tr><tr><td><div><div><p>Moderate Request</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the user prompt against Azure Content Safety before forwarding to the upstream LLM. Rejected prompts never reach the LLM.</p></div></div></td></tr><tr><td><div><div><p>Moderate Response</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, evaluates the LLM response against Azure Content Safety before returning to the client. Rejected responses return <code>403</code> error code. Streaming responses (<code>text/event-stream</code>) aren’t moderated and pass through unchanged.</p></div></div></td></tr><tr><td><div><div><p>Default Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Severity threshold applied to all four harm categories (Hate, SelfHarm, Sexual, Violence). Content with severity at or above this value is rejected. Supported values are <code>0</code>, <code>2</code> (default), <code>4</code>, and <code>6</code>.</p></div><div><p>For details, see <a href="#severity-thresholds">Severity Thresholds</a>.</p></div></div></td></tr></tbody></table>

### Advanced Configuration

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p>API Version</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Azure Content Safety API version used for all endpoint calls. Default: <code>2024-09-01</code>.</p></div><div><p>To enable Groundedness Detection, override this to a supported preview version, for example, <code>2024-09-15-preview</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Prompt Shield</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:shieldPrompt</code> alongside <code>text:analyze</code> on the request to detect jailbreak attempts and indirect prompt-injection attacks.</p></div></div></td></tr><tr><td><div><div><p>Hate Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the Hate harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>SelfHarm Severity Threshold</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-category override for the SelfHarm harm category. Leave as <code>default</code> to inherit Default Severity Threshold. See <a href="#severity-thresholds">Severity Thresholds</a> for supported values.</p></div></div></td></tr><tr><td><div><div><p>Blocklist Names</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Names of Azure-managed blocklists (created in Azure Content Safety Studio) to evaluate against the input text.</p></div></div></td></tr><tr><td><div><div><p>Enable Groundedness Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectGroundedness</code> on the LLM response to detect hallucinated statements. Requires Moderate Response enabled and Grounding Source Selector to be set. Only available in Azure regions that support the API, and only on preview API versions (for example, <code>2024-09-15-preview</code>).</p></div></div></td></tr><tr><td><div><div><p>Grounding Source Selector</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>DataWeave expression resolving the grounding source text from the request body. Required when Groundedness Detection is enabled. For example: <code>#[payload.context.documents[0].content]</code>.</p></div></div></td></tr><tr><td><div><div><p>Enable Protected Material Detection</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>When enabled, calls <code>text:detectProtectedMaterial</code> on the LLM response to detect known copyrighted text. Requires Moderate Response enabled.</p></div></div></td></tr><tr><td><div><div><p>API Timeout (ms)</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Per-request timeout for each Azure Content Safety API call in milliseconds. Must be between 1000 and 30000. Default: <code>5000</code></p></div></div></td></tr><tr><td><div><div><p>Fail Open</p></div></div></td><td><div><div><p>No</p></div></div></td><td><div><div><p>Determines behavior when the Azure API call fails or times out:</p></div><div><ul><li><p>Disabled (default): Rejects the request with HTTP <code>503</code></p></li><li><p>Enabled: Allows traffic to proceed without moderation (fail-open mode)</p></li></ul></div></div></td></tr></tbody></table>

## How This Policy Works

The Azure Content Safety policy integrates with Azure AI Content Safety to evaluate LLM prompts and
responses against configurable safety policies.

### Request and Response Moderation

The policy supports independent evaluation for request and response:

1.  **Request Phase** (when `moderateRequest` is enabled):

    1.  The policy extracts the user prompt from the request body.

    2.  The policy sends the prompt to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories (Hate, SelfHarm, Sexual, Violence) and checks
          blocklists

        - `text:shieldPrompt` — Detects jailbreak attempts and indirect injections (when
          `enablePromptShield` is enabled)

    3.  If the prompt violates any policies, the policy blocks the request and returns a `403` error
        code to the client.

    4.  If the prompt passes, the policy forwards the original request to the upstream LLM.

        If grounding source and query selectors are configured, the policy extracts them during
        request processing and stores the values for use in response processing.

2.  **Response Phase** (when `moderateResponse` is enabled):

    1.  The policy intercepts the LLM response.

    2.  The policy sends the completion to Azure Content Safety APIs in parallel:

        - `text:analyze` — Evaluates harm categories and checks blocklists

        - `text:detectGroundedness` — Scores the response against the grounding source (when enabled
          and grounding source is available)

        - `text:detectProtectedMaterial` — Detects known copyrighted text (when enabled)

    3.  If the response violates any policies, the policy returns a `403` error code to the client.

    4.  If the response passes, the policy forwards the original response to the client.

        > [!NOTE] Streaming responses (`text/event-stream`) are skipped and pass through without
        > moderation.

### Groundedness Detection

Groundedness detection helps detect hallucinations by evaluating whether LLM responses are grounded
in the provided reference text. This is particularly useful for RAG (Retrieval-Augmented Generation)
applications.

To enable groundedness detection:

1.  Enable groundedness detection in Advanced Configuration (`enableGroundednessDetection: true`).

2.  Configure the **Grounding Source Selector** to extract the reference text from the request body.

3.  Set the API Version to a preview version that supports the groundedness endpoint (for example,
    `2024-09-15-preview`).

The grounding source selector is a DataWeave expression that extracts the reference text the LLM
response should be based on (typically documents or context provided in the request).

Example Configuration

```yaml
advancedConfiguration:
  apiVersion: "2024-09-15-preview"
  enableGroundednessDetection: true
  groundingSourceSelector: "#[payload.context.documents[0].content]"
```

### Severity Thresholds

Azure AI Content Safety evaluates content across four harm categories and assigns a severity level
to each:

- **0** — Safe (no harmful content detected)

- **2** — Low severity

- **4** — Medium severity

- **6** — High severity

The policy rejects content when the severity level is at or above the configured threshold:

<table><colgroup><col> <col></colgroup><thead><tr><th>Threshold Value</th><th>Content Blocked</th></tr></thead><tbody><tr><td><div><div><p>0</p></div></div></td><td><div><div><p>Any flagged content (severity &gt; 0) is blocked. This is the strictest setting.</p></div></div></td></tr><tr><td><div><div><p>2</p></div></div></td><td><div><div><p>Content with low, medium, or high severity is blocked. This is the recommended default.</p></div></div></td></tr><tr><td><div><div><p>4</p></div></div></td><td><div><div><p>Content with medium or high severity is blocked. This allows low-severity content.</p></div></div></td></tr><tr><td><div><div><p>6</p></div></div></td><td><div><div><p>Only high-severity content is blocked. This is the most permissive setting.</p></div></div></td></tr></tbody></table>

You can configure a default threshold that applies to all categories, and optionally override the
threshold for specific categories.

### Response Headers

Every moderated response includes observability headers:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Header</th><th>Values</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>x-llm-proxy-azure-content-safety-action</code></p></div></div></td><td><div><div><p><code>allow</code>, <code>reject</code></p></div></div></td><td><div><div><p>Final moderation decision. <code>reject</code> indicates content violated one or more policies.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-azure-content-safety-phase</code></p></div></div></td><td><div><div><p><code>request</code>, <code>response</code></p></div></div></td><td><div><div><p>Which phase performed the moderation. Useful for understanding whether the prompt or response was blocked.</p></div></div></td></tr><tr><td><div><div><p><code>x-llm-proxy-azure-content-safety-reason</code></p></div></div></td><td><div><div><p><code>severity_hate</code>, <code>severity_self_harm</code>, <code>severity_sexual</code>, <code>severity_violence</code>, <code>blocklist</code>, <code>prompt_shield</code>, <code>groundedness</code>, <code>protected_material</code>, <code>service_unavailable</code></p></div></div></td><td><div><div><p>Why the content was rejected. Multiple reasons are comma-separated if the content violated multiple policies.</p></div></div></td></tr></tbody></table>

## Response on Reject

When the policy blocks content, it returns a `403` response with this structure:

```json
{
  "error": "Content blocked by Azure Content Safety",
  "categories": ["severity_hate", "blocklist"]
}
```

## Error Handling

### Fail Closed (Default)

When **Fail Open** is disabled (the default), any Azure API error or timeout results in rejection:

- Request phase: HTTP `503` with body `{"error":"Azure Content Safety service unavailable"}`

- Response phase: The response is rewritten to HTTP `503` with the same body

- The `x-llm-proxy-azure-content-safety-reason` header is set to `service_unavailable`

### Fail Open

When **Fail Open** is enabled, Azure API errors are logged but traffic continues unmoderated. The
`x-llm-proxy-azure-content-safety-reason` header is still set to `service_unavailable` for
observability, allowing you to detect partial-coverage moderation in monitoring systems.

## Example Configurations

### Minimal Configuration — Request and Response Moderation

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
```

### Strict Threshold with Blocklists

This example blocks any flagged content and applies custom blocklists:

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 0
    advancedConfiguration:
      blocklistNames:
        - competitor-names
        - internal-codenames
```

### Per-Category Thresholds

This example applies different thresholds to different harm categories:

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 2
    advancedConfiguration:
      selfHarmSeverityThreshold: "4" # Allow low-severity SelfHarm discussion
      violenceSeverityThreshold: "0" # Block any flagged Violence
```

### With Groundedness Detection (Hallucination Detection)

```yaml
- policyRef:
    name: azure-content-safety-policy-v1-0-impl
    namespace: default
  config:
    azureEndpoint: https://llmproxy-azure-cs-eastus.cognitiveservices.azure.com
    azureApiKey: "${AZURE_CONTENT_SAFETY_KEY}"
    defaultSeverityThreshold: 4
    advancedConfiguration:
      apiVersion: "2024-09-15-preview"
      enableGroundednessDetection: true
      groundingSourceSelector: "#[payload.context.documents[0].content]"
      enableProtectedMaterialDetection: true
      blocklistNames:
        - my-blocklist
      apiTimeoutMs: 10000
      failOpen: false
```

## See Also

- [Azure AI Content Safety](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/overview)

- [Prompt Shield](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/jailbreak-detection)

- [Groundedness Detection](https://learn.microsoft.com/en-us/azure/ai-services/content-safety/concepts/groundedness)

- [Creating and Managing Model Proxies](https://docs.mulesoft.com/general/model-proxy)

- [Applying Model Proxy Policies](https://docs.mulesoft.com/general/model-proxy-policies)