apim-policy-authoring

# APIM Policy Authoring Skill Generates production-ready Azure API Management policy XML with authentication, rate limiting, CORS, error handling, correlation IDs, and security headers. ## When to Use This Skill Activate this skill when users need: - **Authentication policies**: OAuth 2.0, JWT validation, hybrid auth with subscription keys - **Rate limiting**: Per-user or per-subscription throttling - **CORS configuration**: Cross-origin access for browser-based clients - **Error handling**: Standardized error responses with correlation IDs - **Request/response transformation**: Header manipulation, body transformations - **Security headers**: X-Content-Type-Options, X-Frame-Options, etc. --- ## Policy Templates **See [references/POLICY_TEMPLATES.md](references/POLICY_TEMPLATES.md) for complete production-ready XML templates:** 1. **Hybrid Authentication** - OAuth + subscription key fallback for public APIs 2. **OAuth Only** - Internal corporate APIs with Entra ID 3. **Subscription Key Only** - Simple public read-only APIs --- ## Policy Execution Flow ``` INBOUND → BACKEND → OUTBOUND → ON-ERROR 1. INBOUND: Authentication, rate limiting, CORS, headers 2. BACKEND: Forwarding, retry, circuit breaker 3. OUTBOUND: Response transform, security headers, cleanup 4. ON-ERROR: Structured errors, logging, correlation ID ``` --- ## Important: MCP Tools (ALWAYS Use Before Writing Policies) ### 1. Call Best Practices FIRST **Before ANY policy generation**, call: ``` Tool: mcp_azure_mcp_get_azure_bestpractices Intent: "Azure API Management policy best practices for [authentication|rate-limiting|CORS|error-handling]" ``` ### 2. Search Documentation For specific policy elements: ``` Tool: mcp_azure_mcp_documentation search Query: "APIM validate-jwt policy reference" ``` ### 1. JWT Validation with Entra ID ```xml <validate-jwt header-name="Authorization"> <openid-config url="https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration" /> <audiences> <audience>api://{client-id}</audience> </audiences> </validate-jwt> ``` ### 2. Per-User Rate Limiting ```xml <set-variable name="userId" value="@(context.Request.Headers.GetValueOrDefault('Authorization','').AsJwt()?.Subject)" /> <rate-limit-by-key calls="1000" renewal-period="3600" counter-key="@((string)context.Variables['userId'])" /> ``` ### 3. Correlation ID Generation ```xml <set-variable name="correlationId" value="@(Guid.NewGuid().ToString())" /> <set-header name="X-Correlation-ID" exists-action="override"> <value>@((string)context.Variables["correlationId"])</value> </set-header> ``` ### 4. Standardized Error Response ```xml <on-error> <set-body>@{ return new JObject( new JProperty("error", new JObject( new JProperty("code", context.LastError.Source), new JProperty("message", context.LastError.Message), new JProperty("correlationId", context.Variables["correlationId"]), new JProperty("timestamp", DateTime.UtcNow.ToString("o")) )) ).ToString(); }</set-body> </on-error> ``` ### 5. Security Headers ```xml <set-header name="X-Content-Type-Options" exists-action="override"> <value>nosniff</value> </set-header> <set-header name="X-Frame-Options" exists-action="override"> <value>DENY</value> </set-header> <set-header name="Strict-Transport-Security" exists-action="override"> <value>max-age=31536000; includeSubDomains</value> </set-header> ``` --- ## Authentication Decision Matrix | API Type | Authentication | Rate Limit | Use Case | |----------|----------------|------------|----------| | **Public Read-Only** | Subscription Keys | 500 req/hour | Weather API, Public Holidays | | **Internal Corporate** | OAuth (Entra ID) | 10,000 req/hour | Employee Directory, HR Systems | | **Sensitive Public** | OAuth (Entra External ID) | 1,000 req/hour | Payment, Health Records | | **Hybrid** | OAuth + Keys Fallback | 1,000/500 req/hour | APIs with free/premium tiers | --- ## Policy Validation Checklist Before deploying, verify: - **Correlation ID**: Generated in `<inbound>`, included in response + error - **Authentication**: JWT validation or subscription key check - **Rate limiting**: Configured with appropriate limits - **Error handling**: `<on-error>` block with structured JSON - **Security headers**: X-Content-Type-Options, X-Frame-Options, HSTS - **Backend cleanup**: Remove `X-Powered-By`, `Server` in `<outbound>` - **XML validity**: Well-formed, no unclosed tags - **Testing**: Valid/invalid tokens, rate limit exceeded --- ## Related Skills - **azure-apim-architecture** - Understand architecture before policy authoring - **api-security-review** - Validate security after policy creation --- ## Microsoft Documentation - [Policy Reference](https://learn.microsoft.com/azure/api-management/api-management-policies) - [validate-jwt](https://learn.microsoft.com/azure/api-management/validate-jwt-policy) - [rate-limit-by-key](https://learn.microsoft.com/azure/api-management/rate-limit-by-key-policy) - [CORS](https://learn.microsoft.com/azure/api-management/cors-policy) - [Policy Expressions](https://learn.microsoft.com/azure/api-management/api-management-policy-expressions) --- **Skill Version**: 1.0 **Last Updated**: 29 January 2026 **Primary Knowledge**: APIM_PLATFORM_BASELINE_POLICIES.md, [references/POLICY_TEMPLATES.md](references/POLICY_TEMPLATES.md)