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 トークン。ユーザー名とパスワードしかない場合は、まず urn:api:access-management API の createLogin（POST /accounts/login）を、{"username":"...","password":"..."} のボディで呼び出して Bearer トークンを取得します。
   • API Manager の権限：View APIs Configuration および Manage Policies スコープ

2. 組織 ID

   • urn:api:access-management の listMe（GET /accounts/api/me）を呼び出して、組織 ID を取得します。
   • レスポンスの $.user.organization.id から organizationId を抽出します。
   • これは、環境の一覧表示、ポリシーカタログの閲覧、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、バージョン

操作： API 仕様を使用して Exchange に新しいアセットを作成します。

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 インスタンスの作成後、PATCH によってデプロイ設定を行うため、作成前にターゲット ID とゲートウェイのバージョンが必要です。

必要なもの：

• 組織 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 設定が作成されます。Omni Gateway へのデプロイはステップ 5 で行います。

重要： 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 のデプロイエンドポイントを使用し、フラットなトップレベルフィールドを指定します。セルフ管理型 Omni Gateway のデプロイでは不要な追加フィールドが必要になるため、ネストされた target オブジェクトは使用しないでください。

必要なもの：

• ステップ 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"：ステップ 3 の getGatewayTargets レスポンスに含まれるバージョンを使用してください。誤ったバージョンを使用すると、ポリシーの実装エラーが発生します。
• "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）と、各テンプレートのゲートウェイ互換設定を返します。ポリシーの適用時にこれらが必要です。

重要： 汎用の listPolicyTemplates エンドポイントではなく、api-portal-xapi エンドポイント（getExchangePolicyTemplates）を使用してください。汎用エンドポイントは、適用手順で必要となる 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 がありません：適用エンドポイントには、テンプレート ID だけでなく、完全な Exchange 座標が必要です。これらの値を取得するには、getExchangePolicyTemplates（ステップ 6）を使用してください。
• 400 Bad Request — configurationData が無効です：設定プロパティ名はゲートウェイの種類によって異なります。汎用テンプレートエンドポイントではなく、ステップ 6 の policyConfiguration 出力に記載されたプロパティ名を使用してください。たとえば、Omni Gateway では credentialsOriginHasHttpBasicAuthenticationHeader を使用しますが、汎用テンプレートでは credentialsOrigin を使用します。
• 409 Conflict：この種類のポリシーは、すでに API インスタンスに適用されている可能性があります。まず既存のポリシーを一覧表示して確認するか、リクエスト URL に ?allowDuplicated=true を追加して、同じ種類のポリシーを 2 つ目のインスタンスとして適用してください。
• 403 Forbidden：対象環境で Manage Policies 権限が必要です。

完了チェックリスト

すべてのステップを完了したら、次の項目を確認します。

• API インスタンスが Omni Gateway ターゲットにバインドされている（API Manager にデプロイ情報が表示されている）
• API インスタンスのポリシー一覧にポリシーが表示されている
• ポリシーのステータスが「Active」と表示されている
• API リクエストがポリシールールに照らして評価されている
• ポリシーの設定が要件を満たしている

構築したもの

API は次の内容で保護されています。

✅ ポリシーの適用

• 選択したポリシーが API インスタンスで有効になっています
• すべての受信トラフィックがポリシールールに照らして評価されます

✅ Omni Gateway へのバインド

• セルフマネージドの Omni Gateway を対象とするデプロイ設定で API インスタンスが作成されています
• Omni Gateway が設定を自動的に取得します

✅ 設定の管理

• ポリシー設定は API Manager でバージョン管理されます
• API を再デプロイせずに設定を更新できます

次のステップ

1. ポリシーをテストする

   • テストリクエストを送信して、ポリシーが正しく適用されていることを確認します
   • 認証済みのリクエストが許可され、未認証のリクエストがブロックされることを確認します

2. ポリシーを追加する

   • このスキルを再度実行して、追加のポリシー（レート制限 + OAuth2 など）を重ねて適用します
   • ポリシーの順序は重要です。必要に応じて API Manager で優先度を調整してください

3. ポリシーのアクティビティを監視する

   • API Manager の分析機能で、ポリシー適用のメトリクスを確認します
   • 通常と異なる拒否パターンに対するアラートを設定します

ヒントとベストプラクティス

ポリシーの選択

• レート制限：クライアントごとのトラフィック量を制御する必要がある場合に使用します
• OAuth 2.0：トークンベースの認証と認可に使用します
• IP 許可リスト／拒否リスト：ネットワークの接続元に基づいてアクセスを制限する場合に使用します
• クライアント ID の強制：登録済みクライアントアプリケーションを必須にする場合に使用します

ポリシーの順序

• 認証ポリシーは最初に適用してください（順序番号を最小にします）
• レート制限は認証の後に適用してください
• 変換ポリシーは最後に適用してください

ゲートウェイとの互換性

• ゲートウェイと互換性のあるテンプレートを取得するには、常に apiInstanceId を指定して getExchangePolicyTemplates を使用してください
• 設定プロパティ名とデフォルト値は、ゲートウェイの種類（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'."

考えられる原因：

• Exchange の座標を返さない汎用の listPolicyTemplates エンドポイントを使用しました

解決策：

• 代わりに api-portal-xapi の getExchangePolicyTemplates を使用してください。適用エンドポイントで必要な Exchange の座標一式が返されます

関連ジョブ

• apply-policy-to-api-instance：API インスタンスがすでにある場合にポリシーを適用します（より簡単なフロー）
• deploy-api-with-rate-limiting：レート制限のティアを事前設定して API をデプロイします