secure-api

安全 API

概述

为 API 应用安全或流量管理策略，并将其部署到自托管的 Omni Gateway。此流程将带你从识别目标 API、选择策略、配置策略到部署，走完完整流程。根据用户已有的设置，支持多种起始方式——API Manager 实例、Exchange 资产，或仅有 API URL。

你将构建： 在 API 实例上强制执行的完整配置策略，并将其部署到 Omni Gateway

架构

sequenceDiagram
    participant User
    participant Exchange
    participant API Manager
    participant Omni Gateway
    participant Policy Catalog

    User->>Exchange: Publish API spec
    User->>API Manager: Create Instance
    API Manager-->>User: instanceId
    User->>Omni Gateway: Deploy Instance
    Omni Gateway-->>User: Deployment active
    User->>Policy Catalog: Browse compatible policies
    Policy Catalog-->>User: Policy template + config schema
    User->>API Manager: Apply policy with config
    API Manager-->>Omni Gateway: Policy enforced

先决条件

开始之前，请确保你已准备好：

1. 身份验证

   • Anypoint Platform 的有效 Bearer token。如果你只有用户名和密码，请先使用请求体 {"username":"...","password":"..."}，通过 urn:api:access-management API 调用 createLogin（POST /accounts/login）获取 Bearer token。
   • API Manager 权限：View APIs Configuration 和 Manage Policies 作用域

2. 组织 ID

   • 通过 urn:api:access-management 调用 listMe（GET /accounts/api/me）以获取组织 ID
   • 从响应中的 $.user.organization.id 提取 organizationId
   • 此 ID 用于列出环境、浏览策略目录、检查 Exchange 等。

3. 以下任一项

   • 已在 API Manager 中的 API 实例（跳转至第 6 步）
   • 准备好提升至 API Manager 的 Exchange 资产（跳转至第 2 步）
   • 需要先发布的 API 规范或 URL（从第 1 步开始）

选择路径

flowchart TD
    Start{What do you have?} -->|API spec only| Full[Full Setup]
    Start -->|Asset in Exchange| FromExchange[From Exchange]
    Start -->|API Manager instance| PolicyOnly[Apply Policy Only]

    Full --> S1[Step 1: Publish to Exchange]
    S1 --> S2[Step 2: Select Environment]
    FromExchange --> S2
    S2 --> S3[Step 3: Select Gateway Target]
    S3 --> S4[Step 4: Create API Instance]
    S4 --> S5[Step 5: Deploy to Gateway]

    PolicyOnly --> S2b[Step 2: Select Environment]
    S2b --> S6[Step 6: Browse Policies]

    S5 --> S6
    S6 --> S7[Step 7: Apply Policy]
    S7 --> Done[✓ API Secured]

执行路径

此技能根据你已有的内容提供多种执行路径：

• 完整设置：步骤 1、2、3、4、5、6、7

  • 适用情况：你有 API 规范文件，需要先将其发布到 Exchange
  • 你需要：organizationId、API 规范文件

• 从 Exchange 资产开始：步骤 2、3、4、5、6、7

  • 适用情况：你已有 Exchange 资产，需要创建 API Manager 实例
  • 你需要：organizationId、groupId、assetId、assetVersion

• 仅应用策略：步骤 2、6、7

  • 适用情况：你已有 API Manager 实例，想要应用策略
  • 你需要：organizationId、environmentId、environmentApiId

第 1 步：将 API 发布到 Exchange

将 API 规范作为可重复使用的资产发布到 Exchange。这样，API Manager 就可以基于该资产创建受管实例。

你需要：

• 组织 ID
• API 规范文件（OAS 或 RAML）
• 资产名称、groupId、assetId 和版本

操作： 在 Exchange 中使用 API 规范创建新资产。

api: urn:api:exchange-experience
operationId: uploadAsset
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Your organization's Business Group GUID
  groupId:
    userProvided: true
    description: The group ID for the asset (typically matches your organization ID)
    example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  assetId:
    userProvided: true
    description: A unique identifier for the asset in kebab-case
    example: "inventory-api"
  version:
    userProvided: true
    description: Semantic version for the asset
    example: "1.0.0"
outputs:
  - name: groupId
    path: $.groupId
    description: The group ID of the published asset
  - name: assetId
    path: $.assetId
    description: The asset ID of the published asset
  - name: assetVersion
    path: $.version
    description: The version of the published asset

接下来会发生什么： 你的 API 规范现已在 Exchange 中可用。接下来，你将基于此资产创建 API Manager 实例，以便为其应用策略。

第 2 步：列出环境

列出组织中的所有环境，以便确认或选择 API 实例所在的环境。

你需要：

• 组织 ID

操作： 列出可用环境并选择目标环境。

api: urn:api:access-management
operationId: listEnvironments
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID from Prerequisites
outputs:
  - name: environmentId
    path: $.data[*].id
    labels: $.data[*].name
    description: Selected environment ID (e.g., Production, Sandbox)

接下来会发生什么： 选定环境后，你可以创建 API 实例或浏览策略。

第 3 步：选择部署目标

列出在该环境中注册的可用网关目标。创建 API 实例之前，你需要目标 ID 和网关版本，因为创建后要通过 PATCH 设置部署配置。

你需要：

• 组织 ID 和环境 ID

操作： 列出网关目标，并选择 API 将要运行的 Omni Gateway。优先选择 status: "RUNNING" 的目标。

api: urn:api:api-portal-xapi
operationId: getGatewayTargets
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2
outputs:
  - name: targetId
    path: $.rows[*].id
    labels: $.rows[*].name
    description: Selected gateway target ID
  - name: targetName
    path: $.rows[*].name
    description: Name of the selected gateway target
  - name: gatewayVersion
    value: "1.0.0"
    description: Gateway version to use for deployment. The targets response may return "-" instead of a real version; use "1.0.0" as the default.

接下来会发生什么： 你已获得部署目标及其网关版本。接下来，创建 API 实例，然后配置其部署目标。

步骤 4：创建 API Manager 实例

根据 Exchange 资产在 API Manager 中创建一个受管 API 实例。此操作会创建 API 配置；在步骤 5 中才会将其部署到 Omni Gateway。

**重要：**对于 Omni Gateway 实例，isCloudHub 必须为 null（而不是 false）。将其设为 false 会导致验证错误。

你需要：

• 组织 ID 和环境 ID
• Exchange 资产坐标（groupId、assetId、version）

**操作：**在目标环境中创建 API 实例。

api: urn:api:api-manager
operationId: createApiInstance
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Your organization's Business Group GUID
  environmentId:
    from:
      variable: environmentId
    description: Target environment ID from Step 2
  groupId:
    from:
      variable: groupId
    description: Exchange asset group ID from Step 1
  assetId:
    from:
      variable: assetId
    description: Exchange asset ID from Step 1
  assetVersion:
    from:
      variable: assetVersion
    description: Exchange asset version from Step 1
  instanceLabel:
    userProvided: true
    description: A human-readable label for this API instance (e.g., "cars-api-v1")
    example: "cars-api-v1"
  technology:
    value: "flexGateway"
    description: Gateway technology — this skill targets Omni Gateway deployments
  endpoint.isCloudHub:
    value: null
    description: "Must be null for flexGateway technology (not false — false causes a validation error)"
  endpoint.proxyUri:
    userProvided: true
    description: "The proxy listener URI. Ask the user which port the Omni Gateway should listen on, then use http://0.0.0.0:<port>/"
    example: "http://0.0.0.0:8081/"
  endpoint.uri:
    userProvided: true
    optional: true
    description: The upstream backend URL for the API. Ask the user if they want to provide it now or configure it later.
    example: "https://backend.example.com/api/v1"
outputs:
  - name: environmentApiId
    path: $.id
    description: The API instance ID in API Manager

**接下来：**API 实例已创建，但尚未部署。接下来，将其部署到步骤 3 中选择的 Omni Gateway 目标。

步骤 5：部署到 Omni Gateway

将 API 实例部署到所选的 Omni Gateway 目标。此操作使用 Proxies API 部署端点，并采用顶层扁平字段——不要使用嵌套的 target 对象，因为该对象需要一些自托管 Omni Gateway 部署并不需要的额外字段。

你需要：

• 步骤 4 中的组织 ID、环境 ID 和 API 实例 ID
• 步骤 3 中的部署目标 ID 和网关版本

**操作：**在所选的 Omni Gateway 上为 API 实例创建部署。

api: urn:api:proxies-xapi
operationId: createProxyDeployment
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2 (used in both the URL path and the request body for HY deployment type)
  environmentApiId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 4
  type:
    value: "HY"
    description: "Deployment type for self-managed Omni Gateway (HY = Hybrid)"
  targetId:
    from:
      variable: targetId
    description: Omni Gateway target ID from Step 3
  targetName:
    from:
      variable: targetName
    description: Omni Gateway target name from Step 3
  gatewayVersion:
    value: "1.0.0"
    description: "Gateway version for deployment. Use \"1.0.0\" as the default."
  overwrite:
    value: false
    description: "Whether to overwrite an existing deployment"
outputs:
  - name: deploymentId
    path: $.id
    description: The ID of the proxy deployment

**请求体结构：**使用顶层扁平字段，而不是嵌套的 target 对象：

{
  "type": "HY",
  "targetId": "<from Step 3>",
  "targetName": "<from Step 3>",
  "gatewayVersion": "1.0.0",
  "environmentId": "<from Step 2>",
  "overwrite": false
}

**接下来：**API 实例现已部署到 Omni Gateway。接下来，浏览策略目录并选择要应用的策略。

常见问题：

• "Field environmentId is required for deployment type HY"：environmentId 必须位于请求体中，不能只放在 URL 路径参数中。
• "Field gatewayVersion is required for deployment type HY"：使用 getGatewayTargets 响应中的版本（步骤 3）。使用错误的版本会导致策略实现错误。
• "Policy implementations cannot be set because runtime version is unknown"：gatewayVersion 值与已知的 Omni Gateway 版本不匹配。请核实步骤 3 中目标的实际运行时版本。
• 409 Conflict：API 可能已部署到此目标。请先使用 GET .../deployments 列出现有部署并进行检查。

步骤 6：浏览 Exchange 策略目录

列出 Exchange 中适用于你组织的所有策略模板。此端点会返回每个模板的完整 Exchange 坐标（groupId、assetId、assetVersion）以及兼容网关的配置——应用策略时需要这些信息。

**重要：**请使用 api-portal-xapi 端点（getExchangePolicyTemplates），而不是通用的 listPolicyTemplates 端点。通用端点不会返回 Exchange 坐标或网关专用的配置属性名称，而这些信息是应用策略时必需的。

你需要：

• 组织 ID
• 环境 ID 和 API 实例 ID（用于筛选兼容的模板）

**操作：**列出 Exchange 策略模板，并选择要应用的模板。传入 apiInstanceId 和 environmentId，以筛选出与 API 网关类型兼容的模板（例如 Omni Gateway、Mule Gateway）。

api: urn:api:api-portal-xapi
operationId: getExchangePolicyTemplates
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID
  apiInstanceId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 4 (filters for compatible templates)
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2
  latest:
    value: "true"
    description: Return only the latest version of each template
  includeConfiguration:
    value: "true"
    description: Include the configuration schema for each template
outputs:
  - name: policyGroupId
    path: $[*].groupId
    labels: $[*].assetId
    description: Exchange group ID of the selected policy template
  - name: policyAssetId
    path: $[*].assetId
    description: Exchange asset ID of the selected policy template
  - name: policyAssetVersion
    path: $[*].version
    description: Exchange version of the selected policy template (gateway-compatible)
  - name: policyConfiguration
    path: $[*].configuration
    description: Configuration schema with gateway-compatible property names and defaults

**接下来：**你已获得策略模板的 Exchange 坐标，以及包含正确网关类型属性名称的配置架构。应用策略前，请查看 policyConfiguration 输出，了解该策略接受哪些设置。

常见问题：

• 列表为空：传入 apiInstanceId 和 environmentId，以获取与网关类型兼容的模板。若不使用这些筛选条件，某些模板可能不会显示。
• 配置属性名称错误：始终使用此端点返回的配置——通用的 listPolicyTemplates 端点可能会返回不同的（不兼容网关的）属性名称和默认值。

步骤 7：将策略应用到 API 实例

使用适当的配置将选定的策略应用到 API 实例。使用步骤 6 中的 Exchange 坐标和配置属性名称。

所需信息：

• 组织 ID、环境 ID 和 API 实例 ID
• 步骤 6 中的策略 Exchange 坐标（groupId、assetId、assetVersion）
• 根据步骤 6 的 policyConfiguration 输出中的架构确定的策略配置

操作： 将策略应用到 API 实例。使用步骤 6 的配置架构中的属性名称构建 configurationData 对象。对于每个配置属性，向用户展示属性名称、描述和默认值，然后询问用户是要保留默认值还是提供自定义值。如果某个属性没有默认值，则始终向用户询问该属性的值。

api: urn:api:api-manager
operationId: applyApiInstancePolicy
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 2
  environmentApiId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 4 (or provided manually)
  groupId:
    from:
      variable: policyGroupId
    description: Policy Exchange group ID from Step 6
  assetId:
    from:
      variable: policyAssetId
    description: Policy Exchange asset ID from Step 6
  assetVersion:
    from:
      variable: policyAssetVersion
    description: Policy Exchange version from Step 6
outputs:
  - name: policyId
    path: $.id
    description: The ID of the applied policy instance

接下来会发生什么： 你的 API 现在已受到所选策略的保护。由于 API 实例已在步骤 5 中配置部署信息，因此该策略已生效，并在 Omni Gateway 上执行策略。

常见问题：

• 400 Bad Request — 缺少 groupId/assetId/assetVersion：应用端点需要完整的 Exchange 坐标，而不只是模板 ID。确保你已使用 getExchangePolicyTemplates（步骤 6）获取这些值。
• 400 Bad Request — configurationData 无效：配置属性名称因网关类型而异。请使用步骤 6 的 policyConfiguration 输出中的属性名称，而不是通用模板端点中的名称。例如，Omni Gateway 使用 credentialsOriginHasHttpBasicAuthenticationHeader，而通用模板使用 credentialsOrigin。
• 409 Conflict：此类型的策略可能已应用到该 API 实例。请先列出现有策略进行检查，或在请求 URL 中添加 ?allowDuplicated=true，以应用同一策略类型的第二个实例。
• 403 Forbidden：你需要在目标环境中拥有 Manage Policies 权限。

完成检查清单

完成所有步骤后，请确认：

• API 实例已绑定到 Omni Gateway 目标（API Manager 中可见部署信息）
• 策略显示在 API 实例的策略列表中
• 策略状态显示为“Active”
• API 请求正在依据策略规则进行评估
• 策略配置符合你的要求

你已完成的配置

你的 API 现在受到以下保护：

✅ 策略执行

• 所选策略已在你的 API 实例上启用
• 所有传入流量都会依据策略规则进行评估

✅ 已绑定到 Omni Gateway

• API 实例已创建，并配置了指向自主管理型 Omni Gateway 的部署设置
• Omni Gateway 会自动获取该配置

✅ 配置受管理

• 策略设置在 API Manager 中进行版本控制
• 无需重新部署 API 即可更新配置

后续步骤

1. 测试策略

   • 发送测试请求，验证策略是否正常执行
   • 检查已授权的请求是否通过，未授权的请求是否被阻止

2. 添加更多策略

   • 再次运行此技能以叠加其他策略（例如，速率限制 + OAuth2）
   • 策略顺序很重要——如有需要，请在 API Manager 中调整优先级

3. 监控策略活动

   • 在 API Manager 分析中查看策略执行指标
   • 为异常拒绝模式设置警报

提示和最佳实践

策略选择

• 速率限制：需要控制每个客户端的流量时使用
• OAuth 2.0：用于基于令牌的身份验证和授权
• IP 允许列表/阻止列表：用于按网络来源限制访问
• 客户端 ID 强制校验：用于要求客户端应用已注册

策略顺序

• 身份验证策略应首先应用（顺序号最低）
• 速率限制应在身份验证之后应用
• 转换策略应最后应用

网关兼容性

• 始终使用 getExchangePolicyTemplates 和 apiInstanceId 获取网关兼容的模板
• 配置属性名称和默认值因网关类型而异（Omni Gateway 与 Mule Gateway）
• Exchange 模板版本可能与通用模板版本不同

故障排查

策略未生效

症状： 请求通过时未经过策略评估

可能原因：

• API 实例尚未部署或处于错误状态
• 策略配置的默认设置过于宽松，允许所有流量
• 策略已应用，但尚未传播（等待 1-2 分钟）

解决方案：

• 在 API Manager 中检查 API 实例状态
• 检查策略配置，确认设置是否过于宽松
• 等待传播后重试

策略阻止所有请求

症状： 所有请求均返回 401 或 403，即使是合法请求也不例外

可能原因：

• 策略配置过于严格
• 未正确发送所需凭据
• 策略要求标头或参数采用特定格式

解决方案：

• 查看策略配置架构中的必填字段
• 检查客户端应用是否按预期格式发送凭据
• 暂时禁用策略以隔离问题

应用策略时出现 400 错误

症状： "The policy to be created is missing at least one of the following properties related to the policy template: 'groupId', 'assetId', 'assetVersion'."

可能原因：

• 使用了通用的 listPolicyTemplates 端点，该端点不会返回 Exchange 坐标

解决方案：

• 改用 api-portal-xapi 中的 getExchangePolicyTemplates——它会返回应用端点所需的完整 Exchange 坐标

相关作业

• apply-policy-to-api-instance：当你已有 API 实例时应用策略（流程更简单）
• deploy-api-with-rate-limiting：部署具有预配置速率限制层级的 API