Azure API Management Security Policies

Azure API Management (APIM) is a fully managed service that enables you to publish, secure, transform, maintain, and monitor APIs. It acts as a facade between your backend APIs and external consumers. Security policies in APIM are XML-based rules that are executed in a defined order as requests and responses flow through the gateway. These policies allow you to enforce authentication, authorization, rate limiting, IP filtering, CORS, and more without modifying your backend code. The AZ-500 exam focuses on how to implement these policies to protect APIs from unauthorized access, abuse, and attacks.

APIM policies are defined in XML and consist of a collection of statements that are executed sequentially. Policies can be applied at three scopes: global (all APIs), product (a group of APIs), or API/operation (individual API or specific operation). The policy execution order is: inbound (on request), backend (to backend service), outbound (on response), and on-error (if an error occurs). Each policy element performs a specific action, such as validating a JWT token, checking IP address, or transforming XML to JSON.

When a request arrives at the APIM gateway, the following sequence occurs: 1. The gateway processes inbound policies (e.g., authentication, rate limiting, IP filtering). 2. If the request passes all inbound policies, it is forwarded to the backend service (with optional backend policies). 3. The backend response is processed by outbound policies (e.g., caching, response transformation). 4. If any policy fails, the on-error section executes, returning an error response.

Authentication Policies: - validate-jwt: Validates a JWT token. Key attributes: issuer, audiences, roles, openid-configuration. Default: token must be present unless require-expiration-time is false. Common exam trap: forgetting to specify require-expiration-time (default true). - basic-authentication: Validates HTTP Basic authentication. Typically used for legacy systems. - client-certificate: Validates client certificate thumbprint or subject.

Authorization Policies: - check-header: Checks for the presence and value of a header. - set-header: Modifies or adds headers. - limit-concurrency: Limits number of concurrent requests (default 1). - rate-limit: Limits call rate per key (e.g., per subscription). Default: calls per time period. - quota: Limits total number of calls per key over a period (e.g., per month).

IP Filtering: - ip-filter: Allows or denies requests from specific IP addresses or ranges. Syntax: <ip-filter action="allow|deny"> with <address> or <range>.

CORS: - cors: Enables Cross-Origin Resource Sharing. Must specify allowed origins, methods, and headers. Common mistake: not including Access-Control-Allow-Origin in the response.

Policies are edited in the Azure portal under the API Management instance > APIs > select API > Design tab > Code editor. Example inbound policy to validate JWT:

<policies>
    <inbound>
        <base />
        <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized">
            <openid-config url="https://login.microsoftonline.com/tenant-id/v2.0/.well-known/openid-configuration" />
            <required-claims>
                <claim name="aud" match="any">
                    <value>api://client-id</value>
                </claim>
            </required-claims>
        </validate-jwt>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

To verify policies, use the Test tab in the portal to send requests and inspect the trace (HTTP headers and response). You can also use Azure Monitor logs to audit policy executions.

APIM integrates with: - Azure Active Directory: For OAuth2/JWT validation. - Azure Key Vault: To store client secrets and certificates referenced in policies. - Azure Firewall/NSG: For network-level filtering before APIM. - Azure Front Door: For global load balancing and WAF (Web Application Firewall) capabilities. - Azure Policy: To enforce governance on APIM configurations.

Important: APIM security policies are application-layer; they do not replace network security groups or firewalls. They work in tandem with network controls to provide defense in depth.

The AZ-500 exam tests your ability to choose the correct policy for a given requirement. For example: - "You need to restrict access to an API based on client IP addresses." Answer: ip-filter policy. - "You need to ensure that only requests with a valid JWT from Azure AD are accepted." Answer: validate-jwt policy. - "You need to limit the number of API calls per subscription to 1000 per day." Answer: quota policy. - "You need to allow cross-origin requests from a specific domain." Answer: cors policy.

Trap: Candidates often confuse rate-limit (per time window, e.g., 10 calls per minute) with quota (absolute limit over a period, e.g., 1000 calls per month). Also, limit-concurrency limits simultaneous connections, not total calls.

APIM policies support C# expressions for dynamic logic. Expressions are enclosed in @(...). Example: @(context.Request.Headers.GetValueOrDefault("Authorization","").AsJwt()?.Claims?.FirstOrDefault(c => c.Type == "role")?.Value). This allows extracting claims from JWT tokens. The exam does not require writing expressions but may test understanding of what expressions can do (e.g., context object properties).

The on-error section is triggered when a policy fails. It can return a custom error response. Example:

<on-error>
    <set-variable name="errorMessage" value="@(context.LastError.Message)" />
    <return-response>
        <set-status code="500" reason="Internal Server Error" />
        <set-body>@{
            return new JObject(new JProperty("error", context.Variables.GetValueOrDefault<string>("errorMessage"))).ToString();
        }</set-body>
    </return-response>
</on-error>

This is important for exam questions about custom error handling.

Policies can also include caching (e.g., cache-store, cache-lookup) to improve performance. Security implications: cached responses might contain sensitive data; ensure cache scope is appropriate (e.g., per user vs. per URL). The cache-lookup-value policy can retrieve cached values like tokens.

Scenario: You have an API that should only be accessible from the corporate VPN (IP range 10.0.0.0/8) and requires a valid JWT from Azure AD. Additionally, each subscription can make 1000 calls per day.

Policy:

<policies>
    <inbound>
        <base />
        <ip-filter action="allow">
            <address-range from="10.0.0.0" to="10.255.255.255" />
        </ip-filter>
        <validate-jwt header-name="Authorization" failed-validation-httpcode="401" require-expiration-time="true" require-scheme="Bearer">
            <openid-config url="https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration" />
            <audiences>
                <audience>api://{client-id}</audience>
            </audiences>
        </validate-jwt>
        <quota calls="1000" renewal-period="86400" />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Note: quota is placed in inbound to limit before backend call. renewal-period is in seconds (86400 = 1 day).

A major bank exposes customer account APIs via APIM. Requirement: only requests from the bank's internal IP range (10.0.0.0/8) and with a valid OAuth2 token from Azure AD are allowed. Additionally, each partner application (identified by subscription key) can make at most 10,000 calls per day. The solution: use ip-filter to allow only corporate IPs, validate-jwt to check Azure AD tokens, and quota to limit daily calls. In production, the bank also enables Azure Monitor alerts for quota exceeded events. Misconfiguration: forgetting to include <base /> in the API-level policy caused the global policy (which enforced IP filtering) to be bypassed, allowing external traffic. The fix: ensure <base /> is present in all policy sections.

An e-commerce company exposes product search APIs to a public web app and a mobile app. The web app runs on https://www.example.com, and the mobile app is untrusted. Requirement: allow CORS from the web app only, and rate-limit mobile app requests to 5 per second. The solution: apply a cors policy at the API scope with allowed origin https://www.example.com. For the mobile app, use a separate subscription key and apply a rate-limit policy of 5 per second. Common pitfall: the cors policy must handle the preflight OPTIONS request; if not, browsers block the request. Also, rate limiting based on IP is unreliable for mobile apps due to NAT; using subscription key is better.

A healthcare provider exposes patient data APIs. Compliance requires that all requests come from a known set of clinic IPs and include a JWT with specific roles (e.g., 'doctor'). The solution: ip-filter with allowed IPs, validate-jwt with required-claims for role claim. Additionally, the API must reject expired tokens; require-expiration-time is set to true (default). The team initially forgot to specify issuer in JWT validation, causing tokens from any issuer to be accepted. The fix: configure openid-config or explicit issuer. Performance consideration: JWT validation fetches keys from the openid-config URL; caching the keys via cache-lookup-value and cache-store-value reduces latency.