Task 4 — Protect sensitive data with PII policies

Part of the Govern AI models and agents through an API gateway lab. New here? Start with Getting started.

Starting here on its own? You need the Citadel hub deployed (azd up) with Azure AI Language and the PII policy fragments in place — all of which azd up provisions — plus a sample spoke. You do not need the access contracts from Task 2; this notebook creates its own PII-specific contracts. From the Labfiles/G-govern-ai-through-a-gateway folder, run python setup/check_env.py --task 4 to confirm you’re ready.

Continuing from a previous task? The PII contracts here are separate from the Sales-Assistant / HR-ChatAgent / Support-Bot contracts in Task 2, so nothing conflicts. Reuse the same deployed hub and Python environment.

Access control and quotas govern who and how much. This task governs what data is allowed to reach a model. You add gateway policies that detect PII in a prompt and either mask it (then restore it on the way back) or block the request entirely — without the workload writing a line of detection code.

Masking versus blocking — when do you use each?

Anonymization (masking) lets the request proceed but replaces detected entities (names, emails, credit cards, IBANs…) with placeholders before the prompt reaches the model, then de-anonymizes the response so the caller sees real values again. Use it when the model doesn’t need the raw PII to do its job but the user still wants a natural answer.

Blocking rejects any request that contains PII outright. Use it for workloads that must never send sensitive data to a model at all.

Both are implemented as APIM policy fragments (pii-anonymization, pii-deanonymization, pii-state-saving) backed by Azure AI Language PII detection — so the control lives in the gateway, not in each app.

Use case 1 — Anonymize and de-anonymize PII

  1. In VS Code, open 5. citadel-pii-processing-tests.ipynb from the workshop folder and select the workshop/.venv kernel.

  2. Run Steps 0–2 to initialize variables, verify your Azure CLI sign-in, and initialize the APIM client.

  3. Work through Section 3 (Use Case 1):

    • 3.1–3.2 define a PII Masking access contract and its product policy (the policy that wires in the anonymization/de-anonymization fragments).
    • 3.3–3.4 deploy the contract and retrieve its API key.
    • 3.5 sends test prompts containing various PII types (names, emails, phone numbers, credit cards, IBANs). Confirm the entities are masked on the way to the model and restored in the response.

Use case 2 — Block PII

  1. Work through Section 4 (Use Case 2):
    • 4.1–4.4 define and deploy a PII Blocking access contract with its own product policy, then retrieve its key.
    • 4.5 sends a mix of prompts with and without PII. Confirm that clean requests succeed and any request containing PII is rejected.

Use case 3 — Analyze PII processing records

  1. Work through Section 5:
    • 5.1 configures the Cosmos DB connection and grants your user data-plane access (this step shells out to Azure CLI, so make sure you’re signed in).
    • 5.2–5.3 query recent PII processing records and render a quantitative report of what was detected and masked.
    • 5.4–5.5 deploy a dedicated PII Analytics access contract (note it has no PII fragments, so the already-anonymized analytics payload passes through unchanged) and hand the summary to a model through that contract.
Why does the analytics contract deliberately have no PII fragments?

The analytics summary already contains anonymized PII samples and entity categories. If you sent it through a contract that runs PII detection again, the gateway would re-detect and double-anonymize that content, corrupting the report. Routing analytics through a separate no-PII-fragment contract keeps the data intact — a nice illustration of choosing the right contract for the job.

Leave the notebook’s optional Cleanup cell set to False if you want to keep the PII contracts around; they don’t interfere with any other task.

✅ Checkpoint: PII is masked and restored for the masking contract, rejected for the blocking contract, and you can report on what the gateway detected. Sensitive data is now governed at the gateway.

Next (optional): Task 5 — Govern agent frameworks and the Unified AI API