将静态Web应用(SWA)后端关联到APIM时如何使用自定义订阅密钥头？

结论 #

Azure静态Web应用完全可以配合使用非默认订阅头（如x-api-key）的APIM后端，通过以下两种方案可解决头不匹配导致的认证失败问题：

方案一：APIM入站策略映射头（无需修改SWA配置） #

在APIM的目标API或产品上添加入站策略，将SWA自动发送的默认头Ocp-Apim-Subscription-Key的值映射到自定义头x-api-key，同时可选择移除默认头避免冲突。

策略代码 #

<inbound>
    <!-- 将默认订阅头的值覆盖到自定义头x-api-key -->
    <set-header name="x-api-key" exists-action="override">
        <value>@{
            return context.Request.Headers.GetValueOrDefault("Ocp-Apim-Subscription-Key", string.Empty);
        }</value>
    </set-header>
    <!-- 可选：移除默认头，减少冗余 -->
    <remove-header name="Ocp-Apim-Subscription-Key" />
</inbound>

注意事项 #

• 确保该策略应用到SWA关联的目标API或对应的产品上，而非全局策略（避免影响其他API）。
• 若之前尝试此策略未生效，检查策略的应用范围是否正确，或是否有其他策略覆盖了头设置。

方案二：手动配置SWA代理路由（自定义请求头） #

放弃SWA与APIM的自动关联，通过staticwebapp.config.json手动配置代理规则，指定发送自定义订阅头x-api-key。

步骤1：解除SWA与APIM的自动关联 #

在Azure门户的SWA实例中，找到API > 后端，移除已关联的APIM实例。

步骤2：配置staticwebapp.config.json #

在SWA的前端代码根目录下创建或修改staticwebapp.config.json，添加路由规则：

{
  "routes": [
    {
      "route": "/api/home/v1/*",
      "backend": {
        "url": "https://your-apim-instance.azure-api.net/home/v1/{rest}"
      },
      "headers": {
        "x-api-key": "{API_SUBSCRIPTION_KEY}"
      }
    }
  ]
}

步骤3：配置SWA应用设置 #

在Azure门户的SWA实例中，进入配置 > 应用设置，添加名为API_SUBSCRIPTION_KEY的设置，值为你的APIM订阅密钥。SWA会自动替换配置文件中的{API_SUBSCRIPTION_KEY}占位符。

问题原因说明 #

你遇到的认证失败核心原因：

• SWA与APIM自动关联时，会硬编码发送默认订阅头Ocp-Apim-Subscription-Key，即使修改了APIM中API的订阅头名称，SWA仍会按默认逻辑发送。
• APIM此时只识别自定义头x-api-key，因此判定请求缺少订阅密钥，返回权限错误。

内容的提问来源于stack exchange，提问作者Stevie