Feature/dynamic cors sample (#187)

Author: simonkurtz-MSFT

.github/copilot-instructions.md

@@ -366,6 +366,7 @@ Match the heading emojis, heading levels, and section ordering exactly. If a sec
 
 - Use the `ApimRequests` and `ApimTesting` classes from `apimrequests.py` and `apimtesting.py` for all API testing and traffic generation in notebooks.
 - Do not use the `requests` library directly for calling APIM endpoints.
+- **Favour HTTP connection reuse.** When a notebook makes multiple HTTP calls to the same APIM gateway (e.g. a test matrix), create a single `requests.Session()` early and route all calls through it. This avoids repeated TCP+TLS handshakes, which can add 200-500 ms per request. Configure `session.verify` and `session.headers` once from `utils.get_endpoint()` and pass the session (or use it in helper functions) for OPTIONS, GET, and POST calls alike.
 - Use `utils.get_endpoint(deployment, rg_name, apim_gateway_url)` to determine the correct endpoint URL, headers, and TLS verification flag based on the infrastructure type. `allow_insecure_tls` is returned as `True` only for Application Gateway infrastructures because they use a self-signed certificate; it defaults to `False` everywhere else.
 - Example:
   ```python
@@ -396,6 +397,7 @@ Match the heading emojis, heading levels, and section ordering exactly. If a sec
 - Only use apostrophe (U+0027) and quotes (U+0022), not left or right single or double quotation marks.
 - Do not localize URLs (e.g. no "en-us" in links).
 - Never use emoji variation selectors in Markdown. They are sneaky little things that can cause rendering and Markdown anchor link issues.
+- **Markdown tables must be column-aligned.** Pad cell values with spaces so that every `|` delimiter in a column lines up vertically. Use the separator row (`---`, `:---:`, etc.) to establish column widths and align all subsequent rows to match. This applies to every Markdown file in the repository (READMEs, skills, instructions, etc.).
 
 ## Testing and Edge Cases
 
@@ -485,6 +487,17 @@ Check `docs/README.md` for local preview instructions and styling notes. The pag
   ```
 - When executing KQL via `az rest` or `az monitor log-analytics query`, write the query body to a temporary JSON file and pass it with `--body @tempfile.json` to avoid shell pipe-character interpretation issues on Windows.
 
+### Admin APIs (`/admin/`) Convention
+
+Samples that require administrative or operational endpoints (cache loading, configuration reloads, health checks, etc.) must place them under an **`/admin/`** API path. This establishes a consistent, recognisable pattern across all APIM Samples.
+
+- **API path**: `{api_prefix}admin` (e.g. `cors-admin`, `lb-admin`). The sample's `api_prefix` keeps admin APIs namespaced per sample.
+- **Subscription required**: Always `True`. Admin APIs must never be publicly accessible without a subscription key.
+- **Production security**: Subscription keys are a baseline gate but are shared secrets, not identity-based auth. Production deployments should layer JWT validation (`validate-azure-ad-token` or `validate-jwt`) on top of subscription keys. See the `authX` and `authX-pro` samples for implementation patterns.
+- **Naming**: Use kebab-case operation paths that describe the action (e.g. `/load-cache`, `/clear-cache`, `/refresh-config`).
+- **Tags**: Include the sample's tags so the admin API is grouped with its sibling APIs in the APIM portal.
+- **Documentation**: The admin API's display name should start with the phase or sample context (e.g. `Phase 3 Admin`) so its purpose is clear in the APIM portal.
+
 ### API Management Policy XML Instructions
 
 - Policies should use camelCase for all variable names.

AGENTS.md

@@ -12,7 +12,7 @@ This repository provides resources to deploy Azure API Management infrastructure
 
 ## Repository Structure
 
-```
+```text
 /
 ├── infrastructure/          # Azure infrastructure deployments
 │   ├── afd-apim-pe/         # Azure Front Door + APIM with Private Endpoint
@@ -52,31 +52,31 @@ This repository provides resources to deploy Azure API Management infrastructure
 
 ## Key Files in Each Sample/Infrastructure
 
-| File | Purpose |
-|------|---------|
-| `README.md` | Documentation, objectives, and configuration instructions |
-| `create.ipynb` | Jupyter notebook for deploying the sample |
-| `main.bicep` | Bicep template defining Azure resources |
-| `clean-up.ipynb` | (Infrastructure only) Teardown notebook |
-| `*.xml` | APIM policy files |
+| File              | Purpose                                                        |
+| ----------------- | -------------------------------------------------------------- |
+| `README.md`       | Documentation, objectives, and configuration instructions      |
+| `create.ipynb`    | Jupyter notebook for deploying the sample                      |
+| `main.bicep`      | Bicep template defining Azure resources                        |
+| `clean-up.ipynb`  | (Infrastructure only) Teardown notebook                        |
+| `*.xml`           | APIM policy files                                              |
 
 ## Available Skills
 
 Use these skills for specialized tasks. Skills are located in `.github/skills/`.
 
-| Skill | When to Use |
-|-------|-------------|
-| **sample-creator** | Creating new samples under `samples/` following the `_TEMPLATE` structure |
-| **apim-bicep** | Writing Bicep templates for APIM resources (APIs, backends, policies, products) |
-| **apim-policies** | Creating or modifying APIM XML policies (inbound/outbound, authentication, rate limiting) |
+| Skill               | When to Use                                                                                      |
+| ------------------- | ------------------------------------------------------------------------------------------------ |
+| **sample-creator**  | Creating new samples under `samples/` following the `_TEMPLATE` structure                        |
+| **apim-bicep**      | Writing Bicep templates for APIM resources (APIs, backends, policies, products)                  |
+| **apim-policies**   | Creating or modifying APIM XML policies (inbound/outbound, authentication, rate limiting)        |
 
 ## Available Agents
 
 Use these custom agents for focused repository workflows. Agents are located in `.github/agents/`.
 
-| Agent                   | When to Use                                                                                                                       |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| **APIM Sample Creator** | Adding a new sample, gathering missing sample metadata, scaffolding from `_TEMPLATE`, and updating README, website, slide deck, and compatibility artifacts     |
+| Agent                   | When to Use                                                                                                                                                 |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **APIM Sample Creator** | Adding a new sample, gathering missing sample metadata, scaffolding from `_TEMPLATE`, and updating README, website, slide deck, and compatibility artifacts |
 
 ### How to Use Skills
 
@@ -120,18 +120,19 @@ Skills provide templates, patterns, and step-by-step workflows.
 - **Folder**: kebab-case (e.g., `oauth-validation`, `rate-limiting`)
 - **API prefix**: Short, unique, with trailing hyphen (e.g., `oauth-`, `rl-`)
 - **Policy files**: Descriptive, kebab-case (e.g., `token-validation.xml`)
+- **Admin APIs**: Samples needing admin/operational endpoints use path `{api_prefix}admin` with `subscriptionRequired=True` and kebab-case operation paths (e.g., `/load-cache`)
 
 ### Infrastructure Constants
 
 Available in Python via `from apimtypes import INFRASTRUCTURE`:
 
-| Constant | Description |
-|----------|-------------|
-| `INFRASTRUCTURE.AFD_APIM_PE` | Azure Front Door + APIM with Private Endpoint |
-| `INFRASTRUCTURE.APIM_ACA` | APIM with Azure Container Apps |
-| `INFRASTRUCTURE.APPGW_APIM` | Application Gateway + APIM (VNet injection) |
-| `INFRASTRUCTURE.APPGW_APIM_PE` | Application Gateway + APIM with Private Endpoint |
-| `INFRASTRUCTURE.SIMPLE_APIM` | Basic APIM setup |
+| Constant                            | Description                                           |
+| ----------------------------------- | ----------------------------------------------------- |
+| `INFRASTRUCTURE.AFD_APIM_PE`        | Azure Front Door + APIM with Private Endpoint         |
+| `INFRASTRUCTURE.APIM_ACA`           | APIM with Azure Container Apps                        |
+| `INFRASTRUCTURE.APPGW_APIM`         | Application Gateway + APIM (VNet injection)           |
+| `INFRASTRUCTURE.APPGW_APIM_PE`      | Application Gateway + APIM with Private Endpoint      |
+| `INFRASTRUCTURE.SIMPLE_APIM`        | Basic APIM setup                                      |
 
 ## Working with Existing Samples
 
@@ -177,14 +178,14 @@ apis = [api]
 
 Key modules in `shared/python/`:
 
-| Module | Purpose |
-|--------|---------|
-| `utils.py` | NotebookHelper, policy loading, endpoint helpers |
-| `apimtypes.py` | Type definitions (API, INFRASTRUCTURE, APIM_SKU) |
-| `azure_resources.py` | Azure CLI wrappers for resource management |
-| `console.py` | Formatted console output (print_ok, print_error) |
-| `apimrequests.py` | HTTP request helpers for testing APIs |
-| `apimtesting.py` | Test framework for sample verification |
+| Module               | Purpose                                                     |
+| -------------------- | ----------------------------------------------------------- |
+| `utils.py`           | NotebookHelper, policy loading, endpoint helpers            |
+| `apimtypes.py`       | Type definitions (API, INFRASTRUCTURE, APIM_SKU)            |
+| `azure_resources.py` | Azure CLI wrappers for resource management                  |
+| `console.py`         | Formatted console output (print_ok, print_error)            |
+| `apimrequests.py`    | HTTP request helpers for testing APIs                       |
+| `apimtesting.py`     | Test framework for sample verification                      |
 
 ## Bicep Modules
 
@@ -240,11 +241,11 @@ ruff check shared/python/
 
 ## Common Tasks Reference
 
-| Task | Skill to Use | Key Files |
-|------|--------------|-----------|
-| Create a new sample | sample-creator | `samples/_TEMPLATE/*` |
-| Write APIM policies | apim-policies | `shared/apim-policies/*.xml` |
-| Create Bicep templates | apim-bicep | `shared/bicep/modules/` |
+| Task                   | Skill to Use   | Key Files                    |
+| ---------------------- | -------------- | ---------------------------- |
+| Create a new sample    | sample-creator | `samples/_TEMPLATE/*`        |
+| Write APIM policies    | apim-policies  | `shared/apim-policies/*.xml` |
+| Create Bicep templates | apim-bicep     | `shared/bicep/modules/`      |
 
 ## Additional Resources
 

README.md

@@ -68,6 +68,7 @@ It's quick and easy to get started!
 | [AuthX Pro][sample-authx-pro]                               | Authentication and role-based authorization in a mock product with multiple APIs and policy fragments.              | All infrastructures           |
 | [Azure Maps][sample-azure-maps]                             | Proxying calls to Azure Maps with APIM policies.                                                                    | All infrastructures           |
 | [Costing][sample-costing]                                   | Track and allocate API costs per business unit using APIM subscriptions, Entra ID application tracking, and AI Gateway token/PTU tracking via Log Analytics and Cost Management. | All infrastructures           |
+| [Dynamic CORS][sample-dynamic-cors]                         | Dynamic per-API CORS origin validation using custom policy fragments and a maintainable origin mapping. | All infrastructures           |
 | [Egress Control][sample-egress-control]                     | Control APIM outbound internet traffic by routing it through a Network Virtual Appliance (NVA) in a hub/spoke topology. | appgw-apim, appgw-apim-pe     |
 | [General][sample-general]                                   | Basic demo of APIM sample setup and policy usage.                                                                   | All infrastructures           |
 | [Load Balancing][sample-load-balancing]                     | Priority and weighted load balancing across backends.                                                               | apim-aca, afd-apim-pe         |
@@ -380,6 +381,7 @@ _For much more API Management content, please also check out [APIM Love](https:/
 [sample-authx-pro]: ./samples/authX-pro/README.md
 [sample-azure-maps]: ./samples/azure-maps/README.md
 [sample-costing]: ./samples/costing/README.md
+[sample-dynamic-cors]: ./samples/dynamic-cors/README.md
 [sample-general]: ./samples/general/README.md
 [sample-load-balancing]: ./samples/load-balancing/README.md
 [sample-egress-control]: ./samples/egress-control/README.md

assets/APIM-Samples-Slide-Deck.html

@@ -1015,7 +1015,7 @@ <h3>&#128218; Samples</h3>
         <ul style="list-style: none; padding: 0;">
           <li style="padding: 6px 0; font-size: 15px; color: #444; display: flex; gap: 10px; align-items: flex-start;">
             <div class="bullet" style="flex-shrink:0; width:8px; height:8px; border-radius:50%; background:#0078D4; margin-top:7px;"></div>
-            <div>9 real-world scenarios covering auth, networking, costing, and more</div>
+            <div>10 real-world scenarios covering auth, networking, costing, and more</div>
           </li>
           <li style="padding: 6px 0; font-size: 15px; color: #444; display: flex; gap: 10px; align-items: flex-start;">
             <div class="bullet" style="flex-shrink:0; width:8px; height:8px; border-radius:50%; background:#0078D4; margin-top:7px;"></div>
@@ -1095,7 +1095,7 @@ <h4>App Gateway & APIM (VNet Injection)</h4>
   <div class="slide slide-light">
     <div class="header-bar">
       <div class="accent"></div>
-      <h2>9 Real-World Policy Samples</h2>
+      <h2>10 Real-World Policy Samples</h2>
     </div>
     <p class="subtitle">From authentication &amp; authorization to network routing, cost tracking, and secure access patterns</p>
 
@@ -1120,6 +1120,10 @@ <h4>Azure Maps</h4>
         <h4>Costing &amp; Showback</h4>
         <p>Track API costs per business unit via subscriptions, Entra ID apps &amp; AI Gateway tokens.</p>
       </div>
+      <div class="arch-card">
+        <h4>Dynamic CORS</h4>
+        <p>Per-API CORS origin validation with custom policy fragments &amp; maintainable origin mappings.</p>
+      </div>
       <div class="arch-card">
         <h4>Credential Manager</h4>
         <p>APIM Credential Manager with Spotify's REST API.</p>

docs/index.html

@@ -136,11 +136,12 @@
           { "@type": "ListItem", "position": 7,  "name": "AuthX Pro sample",                              "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/authX-pro" },
           { "@type": "ListItem", "position": 8,  "name": "Azure Maps sample",                             "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/azure-maps" },
           { "@type": "ListItem", "position": 9,  "name": "Costing sample",                                "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/costing" },
-          { "@type": "ListItem", "position": 10, "name": "Egress Control sample",                         "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/egress-control" },
-          { "@type": "ListItem", "position": 11, "name": "General sample",                                "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/general" },
-          { "@type": "ListItem", "position": 12, "name": "Load Balancing sample",                         "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/load-balancing" },
-          { "@type": "ListItem", "position": 13, "name": "OAuth 3rd-Party sample",                        "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/oauth-3rd-party" },
-          { "@type": "ListItem", "position": 14, "name": "Secure Blob Access sample",                     "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/secure-blob-access" }
+          { "@type": "ListItem", "position": 10, "name": "Dynamic CORS sample",                            "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/dynamic-cors" },
+          { "@type": "ListItem", "position": 11, "name": "Egress Control sample",                         "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/egress-control" },
+          { "@type": "ListItem", "position": 12, "name": "General sample",                                "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/general" },
+          { "@type": "ListItem", "position": 13, "name": "Load Balancing sample",                         "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/load-balancing" },
+          { "@type": "ListItem", "position": 14, "name": "OAuth 3rd-Party sample",                        "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/oauth-3rd-party" },
+          { "@type": "ListItem", "position": 15, "name": "Secure Blob Access sample",                     "url": "https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/secure-blob-access" }
         ]
       }
     ]
@@ -450,6 +451,12 @@ <h3>Costing</h3>
             <span class="infra-tag">All infrastructures</span>
           </a>
 
+          <a class="sample-card" href="https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/dynamic-cors" target="_blank" rel="noopener">
+            <h3>Dynamic CORS</h3>
+            <p>Dynamic per-API CORS origin validation using custom policy fragments and a maintainable origin mapping.</p>
+            <span class="infra-tag">All infrastructures</span>
+          </a>
+
           <a class="sample-card" href="https://github.com/Azure-Samples/Apim-Samples/tree/main/samples/egress-control" target="_blank" rel="noopener">
             <h3>Egress Control</h3>
             <p>Control APIM outbound internet traffic by routing it through an Azure Firewall NVA in a hub/spoke topology with user-defined routes.</p>

pyproject.toml

@@ -11,6 +11,7 @@ license = { file = "LICENSE" }
 dependencies = [
   "pillow>=12.1.1",   # Resolves CVE 2021-25289: https://pillow.readthedocs.io/en/stable/releasenotes/12.1.1.html#security
   "ipykernel",
+  "jinja2",
   "matplotlib",
   "pandas",
   "pyjwt>=2.12.0",