Azure API Management Policy Snippets

The examples/ directory contains a collection of XML policy snippets designed to solve common architectural and security patterns in Azure API Management (APIM). These snippets can be used to implement features such as Managed Identity authentication, OAuth2 flows, backend routing, and data transformation.

Key categories of available snippets include:

• Identity & Authentication: Managed Identity for Event Hub, Service Bus, and Storage; OAuth2 (AAD, SAP, SuccessFactors); JWT parsing and validation; Basic Authentication.
• Backend Routing & Load Balancing: Redundancy/Failover, Random Load Balancing, Regional Routing, and Backend for Frontend (BFF) aggregation.
• Azure Service Integration: Triggering Azure Data Factory pipelines, querying CosmosDB, interacting with Azure Storage (Blob CRUD), and Azure Event Grid forwarding.
• Security & Transformation: HMAC SHA256 JWT creation, AES encryption, XML value extraction, and IP filtering.
• Observability & Error Handling: Logging to Stackify, adding correlation IDs, and custom error messages for JWT validation.

The OAuth Proxy functionality is modularized into several fragments. Understanding their purpose and placement is critical for correct implementation:

• oauth-proxy-token-endpoint-fragment: Sets the idpTokenEndpoint variable. Must be placed above oauth-proxy-session-fragment.
• oauth-proxy-session-fragment: The core logic. Checks for a session cookie, fetches/decrypts tokens from Redis, renews tokens if necessary, and appends the Authorization: Bearer {access-token} header to the request.
• oauth-proxy-validate-token-fragment: An optional step to perform additional JWT validation on the access token (e.g., using validate-azure-ad-token or validate-jwt). Place after oauth-proxy-session-fragment.
• oauth-proxy-construct-authorization-redirect-fragment: Constructs the OIDC Authorize request URI and sets the oauth-proxy-redirect variable.
• oauth-proxy-slide-session-fragment: An outbound fragment that issues a new session cookie to extend the session lifetime (sliding expiration).

To protect a Web Application, you must include a specific sequence of policy fragments in your <inbound> and <outbound> sections.

Policy Sequence Requirements

1. Inbound:
   • oauth-proxy-token-endpoint-fragment (Must be first to set required variables).
   • oauth-proxy-session-fragment (Checks for session cookie or initiates sign-in).
   • oauth-proxy-validate-token-fragment (Optional: provides additional JWT validation).
2. Outbound/On-Error:
   • oauth-proxy-slide-session-fragment (Slides the session cookie forward to extend the session).

Implementation Example

<policies>
    <inbound>
        <include-fragment fragment-id="oauth-proxy-token-endpoint-fragment" />
        <include-fragment fragment-id="oauth-proxy-session-fragment" />
        <include-fragment fragment-id="oauth-proxy-validate-token-fragment" />
        
        <!-- Adds the following headers to the downstream request: 
            Authorization: Bearer {access-token}
            x-proxy-id-token: {id-token} 
            x-proxy-id-token-name: {id-token name claim}
            x-proxy-id-token-preferred-username: {id-token preferred-username claim}
            -->
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <include-fragment fragment-id="oauth-proxy-slide-session-fragment" />
        <base />
    </outbound>
    <on-error>
        <include-fragment fragment-id="oauth-proxy-slide-session-fragment" />
        <base />
    </on-error>
</policies>

To implement an OAuth Proxy similar to App Service Authentication, you must configure several Named Values in Azure API Management and include specific policy fragments in your API policies.

1. Configure Required Named Values

You need to define the following Named Values to handle encryption, identity, and session management:

2. Generate Encryption Keys

You can generate the required Base 64 encoded 32-byte strings using:

In dotnet:

Convert.ToBase64String(RandomNumberGenerator.GetBytes(32))

In bash:

openssl rand -base64 32

Use JObject and SelectToken to manipulate JSON payloads in requests or responses.

• Get value from Request body: Cast the body to JObject using .As<JObject>(preserveContent: true) and use SelectToken with a JSONPath. Setting preserveContent: true is critical to ensure the body remains available for downstream processing.
• Get value from Response variable: If a response was stored in a variable, cast the variable to IResponse, access its body as JObject, and use SelectToken.
• Add property to JSON body: Convert the body to a JObject, use .Add(new JProperty(...)) to insert a new field, and return the stringified version.

// Get value from JSON body
(string)context.Request.Body.As<JObject>(preserveContent: true).SelectToken("root.child jsonpath")

// Get value from JSON response variable
(string)((IResponse)context.Variables["response-variable-name"]).Body.As<JObject>().SelectToken("root.child jsonpath")

// Add property to JSON body
JObject body = context.Request.Body.As<JObject>(); 
body.Add(new JProperty("property-name", "property-value"));
return body.ToString(); 

Use context.Request.Certificate to validate and inspect client certificates provided during the TLS handshake.

• Check existence: Verify context.Request.Certificate != null.
• Validation:
  • Use .Verify() for full validation including revocation checks.
  • Use .VerifyNoRevocation() to validate the certificate without checking revocation status.
• Inspect Metadata:
  • Issuer: Compare .Issuer against a trusted string.
  • Subject: Compare .SubjectName.Name against an expected name.
  • Thumbprint: Compare .Thumbprint against an expected uppercase hex string.
• Verify APIM Upload: Check if the client's certificate thumbprint matches any certificate uploaded to the Azure API Management instance using context.Deployment.Certificates.Any(...).

context.Request.Certificate != null

// Check if client certificate is valid, including a certificate revocation check
context.Request.Certificate.Verify() == true

// Check if client certificate is valid, excluding a certificate revocation check
context.Request.Certificate.VerifyNoRevocation() == true

// Check if client certificate issuer has expected value
context.Request.Certificate.Issuer == "trusted-issuer"

// Check if client certificate subject has expected value
context.Request.Certificate.SubjectName.Name == "expected-subject-name"

// Check if client certificate thumbprint has expected value
context.Request.Certificate.Thumbprint == "EXPECTED-THUMBPRINT-IN-UPPER-CASE"

// Check if client certificate is uploaded in API Management, based on thumbprint
context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint) == true

Use the context.Variables collection to manage and retrieve custom variables defined within the policy scope.

• Get variable: Use GetValueOrDefault<T> to retrieve a variable. Note that you must specify the type (e.g., <string>) when using GetValueOrDefault for variables.
• Check existence: Use ContainsKey to verify if a variable has been set.
• Validate value: Use GetValueOrDefault<string> combined with .Equals() for case-insensitive string comparison.

// Get policy variable (assuming type string)
context.Variables.GetValueOrDefault<string>("variable-name","optional-default-value")

// Check policy variable existence
context.Variables.ContainsKey("variable-name") == true

// Check if policy variable has expected value (assuming type string)
context.Variables.GetValueOrDefault<string>("variable-name","").Equals("expected-value", StringComparison.OrdinalIgnoreCase)