Azure APIM Integration

git clone https://github.com/aforoai/SDKs.git
cd SDKs/aforo-gateway-plugins/azure-apim

<!--
  Aforo Inbound Policy Fragment
  Purpose: Check tenant entitlement + margin status before forwarding to backend.
  Place in: API inbound policy via <include-fragment fragment-id="aforo-entitlement" />
-->
<fragment>
  <set-variable name="aforo-tenant-id" value="@(context.Request.Headers.GetValueOrDefault("X-Tenant-Id", ""))" />

  <!-- Skip check if no tenant ID (public endpoints) -->
  <choose>
    <when condition="@(string.IsNullOrEmpty((string)context.Variables["aforo-tenant-id"]))">
      <set-variable name="aforo-allowed" value="true" />
    </when>
    <otherwise>
      <!-- Call the Aforo usage-ingestor quota-check endpoint (from the aforo-preflight-url Named Value) -->
      <send-request mode="new" response-variable-name="aforo-entitlement-response" timeout="5" ignore-error="true">
        <set-url>@(context.Variables.GetValueOrDefault<string>("aforo-preflight-url"))</set-url>
        <set-method>GET</set-method>
        <set-header name="X-API-Key" exists-action="override">
          <value>@((string)context.Variables["aforo-api-key"])</value>
        </set-header>
        <set-header name="X-Product-Id" exists-action="override">
          <value>@(context.Api.Id)</value>
        </set-header>
      </send-request>

      <!-- Parse entitlement response -->
      <choose>
        <when condition="@(context.Variables.GetValueOrDefault<IResponse>("aforo-entitlement-response")?.StatusCode == 200)">
          <set-variable name="aforo-allowed" value="@{
            var body = ((IResponse)context.Variables["aforo-entitlement-response"]).Body.As<JObject>();
            return body["allowed"]?.Value<bool>() ?? true;
          }" />
          <set-header name="X-Aforo-Remaining" exists-action="override">
            <value>@{
              var body = ((IResponse)context.Variables["aforo-entitlement-response"]).Body.As<JObject>();
              return body["remaining_quota"]?.ToString() ?? "-1";
            }</value>
          </set-header>
        </when>
        <!-- On error: fail-open (allow traffic, don't block on Aforo outage) -->
        <otherwise>
          <set-variable name="aforo-allowed" value="true" />
        </otherwise>
      </choose>

      <!-- Margin Guard L3: Block if allowed=false -->
      <choose>
        <when condition="@(!(bool)context.Variables["aforo-allowed"])">
          <return-response>
            <set-status code="429" reason="Margin Limit Exceeded" />
            <set-header name="Content-Type" exists-action="override">
              <value>application/json</value>
            </set-header>
            <set-body>{
              "error": "margin_limit_exceeded",
              "message": "API usage has been suspended. Please contact support.",
              "docs": "https://docs.aforo.ai/docs/margin-guards"
            }</set-body>
          </return-response>
        </when>
      </choose>
    </otherwise>
  </choose>
</fragment>

# Set your variables
RESOURCE_GROUP="your-rg"
APIM_NAME="your-apim-instance"
SUBSCRIPTION_ID="$(az account show --query id -o tsv)"
APIM="https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.ApiManagement/service/$APIM_NAME"

# put_fragment <fragment-id> <xml-file>   (needs jq)
put_fragment() {
  jq -n --rawfile v "$2" '{properties: {format: "rawxml", value: $v}}' > fragment-body.json
  az rest --method put \
    --url "$APIM/policyFragments/$1?api-version=2022-08-01" \
    --body @fragment-body.json
}

# Create the inbound entitlement fragment
put_fragment aforo-entitlement aforo-entitlement-fragment.xml

# Verify the fragment was created
az rest --method get \
  --url "$APIM/policyFragments/aforo-entitlement?api-version=2022-08-01" \
  --query "{name: name, state: properties.provisioningState}"

# Everything from the <fragment> line on
sed -n '/^<fragment>/,$p' outbound-policy.xml > aforo-metering.xml
put_fragment aforo-metering aforo-metering.xml

<send-one-way-request mode="new">
  <set-url>{{aforo-endpoint}}</set-url>
  <set-method>POST</set-method>
  <set-header name="X-API-Key" exists-action="override">
    <value>{{aforo-api-key}}</value>
  </set-header>
  <set-header name="X-Tenant-Id" exists-action="override">
    <value>{{aforo-tenant-id}}</value>
  </set-header>
  <set-body>@{
    var eventObj = new JObject(
      // The APIM subscription id is the billed customer
      new JProperty("customerId", context.Subscription != null ? context.Subscription.Id : "unknown"),
      new JProperty("metricName", context.Request.Method + " " + context.Request.Url.Path),
      new JProperty("quantity", 1),
      // context.RequestId, computed once per request, so a resend is deduplicated
      new JProperty("idempotencyKey", context.Variables.GetValueOrDefault("aforo-idempotency-key-base", "")),
      new JProperty("occurredAt", DateTime.UtcNow.ToString("o")),
      new JProperty("statusCode", context.Response.StatusCode)
      /* ...endpointPath, httpMethod, responseTimeMs, trace, metadata... */
    );
    // Set from the response status; omitted when it can't be determined
    var outcome = (string)context.Variables.GetValueOrDefault("aforo-execution-status", "");
    if (!String.IsNullOrEmpty(outcome)) { eventObj.Add("executionStatus", outcome); }
    return new JObject(new JProperty("events", new JArray(eventObj))).ToString();
  }</set-body>
</send-one-way-request>

<policies>
  <inbound>
    <base />
    <!-- Load the Aforo API key from Named Value (backed by Key Vault) -->
    <set-variable name="aforo-api-key" value="{{aforo-api-key}}" />
    <!-- Aforo entitlement check + Margin Guard -->
    <include-fragment fragment-id="aforo-entitlement" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <!-- Aforo async usage metering -->
    <include-fragment fragment-id="aforo-metering" />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

<outbound>
    <base />
    <set-variable name="aforo-status-outcomes" value="404=SUCCESS,429=ERROR" />
    <include-fragment fragment-id="aforo-metering" />
</outbound>

<outbound>
    <base />
    <!-- also skip 404s and everything under /internal -->
    <set-variable name="aforo-exclude-status-codes" value="401,403,429,404" />
    <set-variable name="aforo-exclude-paths" value="/health,/ready,/metrics,/internal" />
    <include-fragment fragment-id="aforo-metering" />
</outbound>

# Create the app registration for APIM → Aforo service identity
APP_ID=$(az ad app create \
  --display-name "Aforo APIM Integration" \
  --sign-in-audience AzureADMyOrg \
  --query appId -o tsv)

echo "App (client) ID: $APP_ID"

# Create a client secret (90-day expiry; rotate before expiry)
CLIENT_SECRET=$(az ad app credential reset \
  --id "$APP_ID" \
  --years 1 \
  --display-name "aforo-apim-secret" \
  --query password -o tsv)

echo "Client secret created. Store this in Key Vault immediately."

# Store client ID and secret in Key Vault
az keyvault secret set \
  --vault-name "your-keyvault" \
  --name "aforo-client-id" \
  --value "$APP_ID"

az keyvault secret set \
  --vault-name "your-keyvault" \
  --name "aforo-client-secret" \
  --value "$CLIENT_SECRET"

# Get your Azure AD tenant ID
TENANT_ID=$(az account show --query tenantId -o tsv)
echo "Tenant ID: $TENANT_ID"

RESOURCE_GROUP="your-rg"
APIM_NAME="your-apim-instance"
VAULT_NAME="your-keyvault"
SUBSCRIPTION_ID="$(az account show --query id -o tsv)"
APIM="https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.ApiManagement/service/$APIM_NAME"

# 1. Enable the APIM managed identity and let it read the vault
az apim update \
  --resource-group "$RESOURCE_GROUP" \
  --name "$APIM_NAME" \
  --enable-managed-identity true

APIM_IDENTITY=$(az apim show --resource-group "$RESOURCE_GROUP" --name "$APIM_NAME" \
  --query identity.principalId -o tsv)

az keyvault set-policy \
  --name "$VAULT_NAME" \
  --object-id "$APIM_IDENTITY" \
  --secret-permissions get list

# 2. Key Vault-backed Named Values: kv_named_value <name> <vault secret name>
kv_named_value() {
  az rest --method put \
    --url "$APIM/namedValues/$1?api-version=2022-08-01" \
    --body "{\"properties\": {\"displayName\": \"$1\", \"secret\": true, \"keyVault\": {\"secretIdentifier\": \"https://$VAULT_NAME.vault.azure.net/secrets/$2\"}}}"
}
kv_named_value aforo-api-key aforo-api-key
kv_named_value aforo-client-secret aforo-client-secret

# 3. Plain Named Values
az apim nv create \
  --resource-group "$RESOURCE_GROUP" \
  --service-name "$APIM_NAME" \
  --named-value-id "aforo-client-id" \
  --display-name "aforo-client-id" \
  --secret false \
  --value "$APP_ID"

RESOURCE_GROUP="your-rg"
APIM_NAME="your-apim-instance"
API_ID="your-api-id"
SUBSCRIPTION_ID="$(az account show --query id -o tsv)"
APIM="https://management.azure.com/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.ApiManagement/service/$APIM_NAME"

# Apply the combined inbound+outbound policy to your API
jq -n --rawfile v api-policy.xml '{properties: {format: "rawxml", value: $v}}' > api-policy-body.json
az rest --method put \
  --url "$APIM/apis/$API_ID/policies/policy?api-version=2022-08-01" \
  --body @api-policy-body.json

# Verify the policy was applied
az rest --method get \
  --url "$APIM/apis/$API_ID/policies/policy?api-version=2022-08-01&format=rawxml" \
  --query properties.value -o tsv | grep -o "include-fragment[^/]*"

# Expected output:
# include-fragment fragment-id="aforo-entitlement"
# include-fragment fragment-id="aforo-metering"

# Get your APIM gateway URL
GATEWAY_URL=$(az apim show \
  --resource-group "$RESOURCE_GROUP" \
  --name "$APIM_NAME" \
  --query gatewayUrl -o tsv)

# Make a test request (replace with a real subscription key)
curl -v "$GATEWAY_URL/your-api/endpoint" \
  -H "Ocp-Apim-Subscription-Key: your_subscription_key" \
  -H "X-Tenant-Id: test_tenant_123"

# Check for Aforo response headers:
# X-Aforo-Remaining: 8420   ← quota remaining for this tenant
# X-Aforo-Plan: enterprise   ← plan tier

# Then confirm it arrived: in Aforo, open Intelligence → Usage Ingestion.
# The event shows up once the plugin has sent it (batching plugins flush every few seconds).

Enable APIM tracing with Ocp-Apim-Trace: true and Ocp-Apim-Subscription-Key on your request. The trace response includes the policy execution timeline — look for the aforo-entitlement fragment in the inbound section and the aforo-metering fragment in the outbound section. Each step shows duration, variables set, and any errors. Available in the Azure Portal under APIM → APIs → Test → Trace.