Sensitive Personal Information Detection

This system lets each tenant decide whether sensitive personal information should be detected and masked before a request is sent to a downstream service. The platform gateway sends qualifying requests to a dedicated redaction service, and that service calls the Azure language service to detect sensitive entities such as names, addresses, financial details, and medical information.

Overview

The system uses the Azure language service to identify and redact sensitive information in requests. This machine-learning approach gives broader coverage than a simple list of regular expressions because it can use context, not just text patterns, to decide what should be masked.

Supported Entity Types

The Azure language service can detect and redact a wide range of sensitive personal information types:

• Personal Identifiers: Names, email addresses, phone numbers
• Financial Data: Credit card numbers, bank account numbers
• Government IDs: Social Security Numbers, passport numbers, driver's license numbers
• Location Data: Physical addresses, GPS coordinates
• Medical Information: Medical record numbers, health insurance information

Architecture

Requests first enter the shared API Management gateway, often shortened to APIM in the implementation. Tenant-specific gateway policies then decide whether sensitive-data redaction should run. When redaction is enabled, the pii-anonymization policy fragment sends the full request body to the external PII Redaction Service, which runs as a container app inside the shared internal container app environment. That service makes the Azure language service calls, breaks large content into manageable pieces, checks that every part was processed, and returns the fully redacted body to the gateway. The service address is stored in the API Management named value piiExternalRedactionUrl.

How It Works

1. A tenant request arrives at the API Management gateway.
2. The tenant gateway policy, generated from api_policy.xml.tftpl, routes the request to the correct backend based on the path. Examples include openai, documentintelligence, ai-search, and storage.
3. For OpenAI requests, when sensitive-data redaction is enabled, the tenant policy sets configuration variables from the tenant's apim_policies.pii_redaction settings:
   • piiExcludedCategories - Categories to exclude from detection
   • piiDetectionLanguage - Language code for detection accuracy
   • piiFailClosed - Whether to block requests on failure (fail-closed) or pass through (fail-open)
   • piiScanRoles - JSON array of message roles to scan (default: user, assistant, tool)
   • piiExternalRedactionUrl - Base URL of the PII Redaction Container App
4. The policy includes the pii-anonymization policy fragment.
5. The fragment creates a JSON payload that contains the original request body and the redaction settings, then sends it to the external PII Redaction Service by using <send-request> with a POST /redact call and a 90-second timeout.
6. The PII Redaction Service:
   • Extracts chat messages and chunks long messages into documents (max 5 000 chars each, word-boundary split).
   • Calls /language/:analyze-text in batches of up to 5 documents, with bounded concurrency and a maximum of 15 batches per request.
   • Enforces a per-attempt timeout (10 s), honors Retry-After for 429 responses, applies exponential backoff for 5xx responses, and keeps all retry/backoff activity within an 85-second request deadline.
   • Reassembles the redacted text back into the original message structure.
   • Returns a JSON response with status, full_coverage, redacted_body, and diagnostics.
7. The API Management gateway validates the response by checking for HTTP 200, status == "ok", and full_coverage == true. It then stores the redacted body in piiAnonymizedContent, and the tenant policy replaces the original body by using <set-body>.

Configuration Guide

Shared Configuration (All Environments)

Sensitive-data detection depends on two shared platform components being available: the Azure language service must be enabled through shared_config.language_service.enabled, and the PII Redaction Service container app must be deployed. The redaction service address is passed into API Management through the named value piiExternalRedactionUrl. The language service does not allow public network access. Instead, it is reached through a private endpoint, and the redaction service calls it over the virtual network.

Per-Tenant Configuration

Sensitive-data redaction is controlled separately for each tenant through API Management policy settings at apim_policies.pii_redaction.enabled. The tenant gateway policy only includes the redaction logic when both conditions are true: the tenant has turned redaction on, and the shared language service is enabled for the platform.

# Example tenant policy flags
apim_policies {
  pii_redaction {
    enabled                 = true

    # Optional: Fail-closed mode (default: false)
    # When true: blocks requests with 503 if Language Service fails
    # When false: passes through unredacted content on failure (fail-open)
    fail_closed             = false

    # Optional: Exclude specific PII categories from detection
    excluded_categories     = ["PhoneNumber", "Address"]

    # Optional: Language for detection (default: "en")
    detection_language      = "en"

    # Optional: Message roles to scan (default: ["user", "assistant", "tool"])
    scan_roles              = ["user", "assistant", "tool"]
  }
  rate_limiting {
    enabled = true
    tokens_per_minute = 10000
  }
  usage_logging {
    enabled = true
  }
  streaming_metrics {
    enabled = true
  }
  tracking_dimensions {
    enabled = true
  }
}

PII Redaction Configuration Options

Security Model

APIM routes requests to the PII Redaction Service over VNet-internal ingress. The external service handles all Language Service authentication via its own Managed Identity.

Observability

PII Detection Diagnostics

The pii-anonymization fragment emits rich diagnostic traces to Application Insights at multiple stages of the request lifecycle:

• pii-outbound (verbose): Logged before sending to the PII Redaction Service. Includes the outbound body, service URL, request ID, and subscription ID.
• pii-inbound (verbose): Logged when the PII Redaction Service responds. Includes HTTP status code, response duration (pii-duration-ms), and response size (pii-response-bytes).
• pii-anonymization (information/error): Logged after processing the response.
  • On success: pii-redaction-succeeded=true, pii-content-changed, pii-coverage-full, pii-entity-count, pii-document-count
  • On failure: pii-redaction-succeeded=false, pii-failure-reason (e.g., no-response, payload-too-large, http-500, incomplete-coverage, service-error: ...)
• request-id: Correlation ID for tracing the request across APIM and the PII Redaction Service
• subscription-id: Tenant identifier for per-tenant analytics

These diagnostics enable monitoring of PII detection effectiveness, tracking service health and latency, and understanding failure modes across the APIM → PII Redaction Service → Language Service chain.

OpenAI Usage Logging

For OpenAI requests, the tenant policy template sets routing metadata variables before including the openai-usage-logging fragment:

• backendId: APIM backend identifier (e.g., tenant-openai)
• routeLocation: Azure region for the backend (single-backend for now)
• routeName: Route identifier for future intelligent routing
• deploymentName: Extracted from the URL path (e.g., gpt-4)

These dimensions are logged to Application Insights along with token usage data, enabling detailed cost allocation, chargeback analytics, and deployment-level monitoring even in the current single-backend setup.

Additional Monitoring Fragments

Frequently Asked Questions

pii_redaction {
  enabled     = true
  fail_closed = true  # Block requests if PII service fails
}

pii_redaction {
  enabled = true
  excluded_categories = ["PhoneNumber", "Address"]
}

Troubleshooting