apim-policy-authoring

name	apim-policy-authoring
description	Creates production-ready Azure API Management policy XML for authentication (OAuth 2.0, JWT validation, subscription keys), rate limiting, CORS configuration, error handling, and API transformations. Use when implementing API security, access control, or request/response processing logic.
license	MIT
metadata	{"author":"Thomas Thornton","version":"1.0.0","last-updated":"2026-05-19","azure-services":"api-management"}

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 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

<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

<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

<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

<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

<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
• validate-jwt
• rate-limit-by-key
• CORS
• Policy Expressions

---

Skill Version: 1.0
Last Updated: 29 January 2026
Primary Knowledge: APIM_PLATFORM_BASELINE_POLICIES.md, references/POLICY_TEMPLATES.md