AccessControl ポリシー

Apigee X のドキュメントを表示中です。
Apigee Edge のドキュメントを表示する。

ポリシー アイコン

概要

AccessControl ポリシーを利用することで、API に対する特定の IP アドレスからのアクセスを許可または拒否できます。

動画: 特定の IP アドレスごとに API へのアクセスを許可または拒否する方法に関する短い動画をご覧ください。

このポリシーは、API プロキシフロー中の任意の場所に接続できます。しかし、フロー(Request / ProxyEndpoint / PreFlow)の最初や、認証の前、または割り当ての確認の前に IP アドレスをチェックする可能性が高いと思われます。

サンプル

次の IPv4 サンプルのマスク値は、照合ルールがアクセスを許可または拒否する際に 4 つのオクテット(8、16、24、32 ビット)のうちのどれを考慮するかを識別しています。デフォルト値は 32 です。詳しくは、要素リファレンスの mask 属性をご覧ください。

198.51.100.1 を拒否する

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

クライアント アドレス「198.51.100.1」からのリクエストがすべて拒否されます。

その他のクライアント アドレスからのリクエストは許可されます。

変数の使用を拒否する

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="{kvm.mask.value}">{kvm.ip.value}</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

マスクと IP の値の保存に Key-Value マップ(KVM)を使用していると仮定します。その場合は、API プロキシの更新と再デプロイが必要なく、ランタイムに IP の変更やマスキングが簡単にできます。KeyValueMapOperations ポリシーを使用して、kvm.mask.valuekvm.ip.value の値を含む変数を取得できます(KVM のマスク値と IP 値を含む KVM ポリシーの変数にそのような名前を付けていると仮定)。取得したマスク値が 24、IP アドレスが 198.51.100.1 である場合、「198.51.100.*」からのすべてのリクエストが、AccessControl ポリシーによって拒否されます。

その他のクライアント アドレスは、すべて許可されます。

198.51.100.* を拒否する

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
    </IPRules>
</AccessControl>

クライアント アドレス 198.51.100.* からのリクエストがすべて拒否されます。

その他のクライアント アドレスからのリクエストは許可されます。

198.51.*.*

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
       <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

クライアント アドレス「198.51.*.*」からのリクエストがすべて拒否されます。

その他のクライアント アドレスからのリクエストは許可されます。

198.51.100.* を拒否および 192.0.2.1 を許可する

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="32">192.0.2.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

クライアント アドレス「198.51.100.*」からのリクエストがすべて拒否されますが、「192.0.2.1」は許可されます。

その他のクライアント アドレスからのリクエストは許可されます。

198.51.*.* を許可する

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

クライアント アドレス「198.51.*.* 」からのリクエストがすべて許可されます。

その他のクライアント アドレスからのリクエストは拒否されます。

複数の IP を許可する

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "ALLOW">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
     </MatchRule>
  </IPRules>
</AccessControl>

次のクライアント アドレスからのリクエストを許可します: 198.51.100.*192.0.2.* 203.0.113.*

その他のアドレスはすべて拒否されます。

複数の IP を拒否する

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

次のクライアント アドレスからのリクエストを拒否します: 198.51.100.*192.0.2.* 203.0.113.*

その他のアドレスはすべて許可されます。

複数の IP を許可し、複数の IP を拒否する

<AccessControl name="ACL">
  <IPRules noRuleMatchAction = "DENY">
    <MatchRule action = "DENY">
      <SourceAddress mask="24">198.51.100.1</SourceAddress>
      <SourceAddress mask="24">192.0.2.1</SourceAddress>
      <SourceAddress mask="24">203.0.113.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "ALLOW">
      <SourceAddress mask="16">198.51.100.1</SourceAddress>
      <SourceAddress mask="16">192.0.2.1</SourceAddress>
      <SourceAddress mask="16">203.0.113.1</SourceAddress>
    </MatchRule>
  </IPRules>
</AccessControl>

次を許可します: 198.51.*.* 192.0.*.* 203.0.*.*

許可リストのサブセットを拒否します: 198.51.100.*192.0.2.* 203.0.113.*


使用上の注意

AccessControl ポリシーでは、悪意のある IP から API を保護できるだけでなく、正当な IP アクセスも制御できます。たとえば、自社の管理下にあるコンピュータに限定して、テスト環境に公開している API にアクセスできるようにする場合、内部ネットワークの IP アドレス範囲を許可します。在宅勤務のデベロッパーは、VPN を使用してこれらの API にアクセスできます。

AccessControl ポリシーの構成と実行には、以下が含まれます。

  • 一連の照合ルールを定義し、それぞれに関連付けられた 2 つのアクション(ALLOW または DENY)のいずれかを指定します。
  • 照合ルールごとに、IP アドレスを指定します(SourceAddress 要素)。
  • ルールを試行する順序を指定します。
  • すべての照合ルールが指定された順に実行されます。照合ルールが一致すると、それに対応するアクションが実行され、その後の照合ルールはスキップされます。
    • 同じルールに ALLOW と DENY の両方のアクションが構成されている場合、最初に定義されたルールがトリガーされ、後のルールは(その他のアクションとともに)スキップされます。

評価する IP アドレスの選択方法

IP アドレスは、リクエスト内のさまざまなソースから取得できます。たとえば、True-Client-IP メッセージ ヘッダーには IP アドレス、X-Forwarded-For ヘッダーには 1 つ以上の IP アドレスがそれぞれ含まれます。このセクションでは、AccessControl ポリシーを構成して、AccessControl ポリシーに評価させたい正確な IP アドレスを評価する方法を説明します。

AccessControl ポリシーが評価する IP アドレスの決定に使用されるロジックは次のとおりです。

1. True-Client-IP ヘッダー

このポリシーでは、最初に True-Client-IP ヘッダーの IP アドレスが確認されます。ヘッダーに有効な IP アドレスが含まれている場合、ポリシーはそのアドレスを評価します。

2. X-Forwarded-For ヘッダー

True-Client-IP ヘッダーが存在しない場合、または <IgnoreTrueClientIPHeader> 要素を true に設定した場合、ポリシーは X-Forwarded-For ヘッダーの IP アドレスを評価します。

X-Forwarded-For ヘッダーには、最後の外部 TCP handshake で受信した IP アドレス(クライアント IP やルーターなど)が自動的に入力されます。ヘッダーに複数の IP アドレスがある場合、それらのアドレスはリクエストを処理したサーバーのチェーンにあると考えられます。しかし、アドレスのリストになりすましの IP アドレスが含まれている可能性もあります。では、ポリシーは評価するアドレスをどのように認識するのでしょうか。

Apigee アナリティクスの X-Forwarded-For ディメンション

Apigee Analytics では、X-Forwarded-For ヘッダーの値が x_forwarded_for_ip ディメンションに書き込まれます。Apigee にリクエストを行ったクライアント IP を判断するには、ax_true_client_ip または ax_resolved_client_ip ディメンションの値を使用します。詳細については、アナリティクス指標、ディメンション、フィルタのリファレンスをご覧ください。

CIDR 表記での IP マスキングについて

CIDR(クラスレス ドメイン間ルーティング)表記は、IP アドレスの範囲をマスキングによって示す方法です。これは、IPv4 と IPv6 の両方に適用されます。ここでその仕組みについて説明します。次に示す例では、簡単にするため IPv4 を使用しています。

IP アドレスは、ピリオドで区切られた数字のグループです。バイナリの場合、各グループは特定のビット数(IPv4 では 8、IPv6 では 16)になります。IPv4 アドレス「198.51.100.1」は、バイナリでは次のようになります。

11000110.00110011.01100100.00000001

8 ビットのグループが 4 つあるので、合計 32 ビットになります。CIDR を使用すると、次のように IP アドレスに「/数字(1-32)」を追加して、範囲を指定できます。

198.51.100.1/24

この場合、24 はこのポリシーの mask 属性値に使用する数字です。

この表記は、「最初の 24 ビットをそのまま維持し、残りのビットは 0~255 の任意の値でよい」という意味です。次に例を示します。

この値はそのまま維持 最後のグループの可能値
198.51.100. 0~255

グループ 3 の最後でマスクが発生している点が重要です。これによって整えられた「198.51.100.*」のようなマスクが生成されます。ほとんどの場合、8 の倍数(IPv4 の場合)と 16 の倍数(IPv6 の場合)を使用すると、必要なマスキング レベルが得られます。

IPv4: 8、16、24、32

IPv6: 16、32、48、64、80、96、112、128

ただし、細かいバイナリ計算を含む微調整には、その他の数字も使用できます。たとえば、198.51.100.1/30(最後の 1 はバイナリの 00000001)はマスクとして 30 を設定した例です。

この値はそのまま維持 可能値
11000110.00110011.01100100.000000(最初の 30 ビット) 00000000、00000001、00000010、00000011
198.51.100. 0、1、2、3

この例の場合、構成を <SourceAddress mask="30">198.51.100.1</SourceAddress> に設定すると、次の IP が許可される(ルールによっては拒否される)ことになります。

  • 198.51.100.0
  • 198.51.100.1
  • 198.51.100.2
  • 198.51.100.3

要素リファレンス

この要素リファレンスでは、AccessControl ポリシーの要素と属性について説明します。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "ALLOW">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
        <MatchRule action = "DENY">
            <SourceAddress mask="24">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>

<AccessControl> 属性

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">

<ClientIPVariable> 要素

ポリシーが IPRules に対して確認する IP アドレスを含むフロー変数を指定します。フロー変数に有効な IP アドレス(ipv4 または ipv6)が含まれていない場合、ポリシーはエラーをスローします。

フロー変数が 12.31.34.52 に設定されているとします。次の例では、アクセスが拒否されます。変数が 10.11.12.13 に設定されている場合、アクセス権が付与されます。


<AccessControl name='ACL'>
   <ClientIPVariable>FLOW_VARIABLE</ClientIPVariable>
   <IPRules noRuleMatchAction = 'DENY'>
     <MatchRule action = 'ALLOW'>
       <SourceAddress mask='32'>10.11.12.13</SourceAddress>
     </MatchRule>
   </IPRules>
</AccessControl>

デフォルト なし
要否 省略可
フロー変数

<IgnoreTrueClientIPHeader> 要素

true に設定すると、ポリシーは True-Client-IP ヘッダーを無視し、構成した X-Forwarded-For 評価動作に従って X-Forwarded-For ヘッダーの IP アドレスを評価します。


<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control-1</DisplayName>
    <IgnoreTrueClientIPHeader>true</IgnoreTrueClientIPHeader>
    ...
</AccessControl>

デフォルト false
要否 省略可
ブール値

<IPRules> 要素

IP アドレスを許可または拒否するルールを含む、親要素。noRuleMatchAction 属性を使用すると、照合ルールの対象ではない IP アドレスの処理方法を定義できます。

<IPRules noRuleMatchAction = "ALLOW">
デフォルト なし
要否 省略可
なし

属性

属性 説明 デフォルト 要否
noRuleMatchAction
指定した照合ルールが解決されなかった場合(不一致の場合)に実行するアクション(アクセスの許可または拒否)。
有効な値: ALLOW または DENY
文字列 ALLOW 必須

<IPRules>/<MatchRule> 要素

IP アドレスが、定義した SourceAddress に一致した場合に実行するアクション(アクセスの許可または拒否)。

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="32">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">198.51.100.1</SourceAddress>
    </MatchRule>
</IPRules>
デフォルト なし
要否 省略可
なし

属性

属性 説明 デフォルト 要否
アクション

指定した照合ルールが解決されなかった場合(不一致の場合)に実行するアクション(アクセスの許可または拒否)。

有効な値: ALLOW または DENY

文字列 ALLOW 必須

<IPRules> / <MatchRule> / <SourceAddress> 要素

クライアントの IP アドレス範囲。

有効な値: 有効な IP アドレス(ドット区切りの 10 進表記)。ワイルドカード動作には、mask 属性を使用します。

<IPRules noRuleMatchAction = "ALLOW">
    <MatchRule action = "ALLOW">
        <SourceAddress mask="{variable}">198.51.100.1</SourceAddress>
    </MatchRule>
    <MatchRule action = "DENY">
        <SourceAddress mask="24">{variable}</SourceAddress>
    </MatchRule>
</IPRules>

前の例で示したように、SourceAddress 要素は mask 属性または IP アドレスのメッセージ テンプレートもサポートしています。つまり、API プロキシフロー内で現在利用できる変数を使用して値を設定できることを意味します。

たとえば、Key-Value マップ(KVM)に IP アドレスを保存し、KeyValueMapOperations ポリシーを使用して IP アドレスを取得し、変数(kvm.ip.value など)に割り当てることができます。この変数を IP アドレスに使用できます。

<SourceAddress mask="24">{kvm.ip.value}</SourceAddress>

マスクまたは IP アドレスを変数で設定すると、API プロキシを再デプロイすることなく、ランタイムに値を柔軟に変更できるようになります。

デフォルト なし
要否 省略可
文字列(単一 IP アドレスのみ)

属性

属性 説明 デフォルト 要否
マスク

mask 属性は、許可または拒否する IP アドレスの範囲を示す方法です。CIDR(クラスレス ドメイン間ルーティング)表記を使用するマスクと同等です。例:

<SourceAddress mask="24">198.51.100.1</SourceAddress>

は次の CIDR 表記と同等です。

198.51.100.1/24

有効な値:

IPv4: 1~32

IPv6: 1~128

値をゼロ(0)とするのは IP「0.0.0.0」に対してのみ有効になるため、実際的ではありません。

マスクを変数で設定する

mask 属性は、メッセージ テンプレートもサポートしているため、API プロキシフローで現在利用可能な変数を使用して値を設定できます。たとえば、マスク値を KVM に格納し、KeyValueMapOperations ポリシーを使用してそれを変数に割り当てることができます。変数で IP マスクを設定するには、次の形式を使用します(変数の名前が kvm.mask.value であると仮定)。

mask="{kvm.mask.value}"

整数 なし 必須

<ValidateBasedOn> 要素

X-Forwarded-For HTTP ヘッダーに複数の IP アドレスが含まれている場合、この ValidateBasedOn 要素を使用して評価する IP アドレスを制御します。

この方法は、評価する IP アドレスの有効性が確実な場合にのみ、IP アドレスを評価するために使用します。たとえば、X-Forwarded-For ヘッダーのすべての IP アドレスを評価する場合は、それらのアドレスの有効性を信頼できるか、信頼できる IP だけが API プロキシを呼び出せるように包括的 DENY ルールまたは ALLOW ルールを設定する必要があります(両方が必要な場合もあります)。

ヘッダーの左端の IP アドレスはクライアントに属し、右端は現在のサービスにリクエストを転送したサーバーです。右端(つまり最後の IP アドレス)は、Apigee が最後の外部 TCP handshake から受信したアドレスです。

この要素に入力する値により、ヘッダー内のすべての IP アドレス(デフォルト)をチェックするか、最初の IP アドレスだけをチェックするか、最後の IP アドレスのみをチェックするかが決まります。

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control 1</DisplayName>
    <IPRules noRuleMatchAction = "ALLOW">
        <MatchRule action = "DENY">
            <SourceAddress mask="32">198.51.100.1</SourceAddress>
        </MatchRule>
    </IPRules>
    <ValidateBasedOn>X_FORWARDED_FOR_ALL_IP</ValidateBasedOn>
</AccessControl>
デフォルト X_FORWARDED_FOR_ALL_IP
要否 省略可
有効な値

X_FORWARDED_FOR_ALL_IP(デフォルト)

X_FORWARDED_FOR_FIRST_IP

X_FORWARDED_FOR_LAST_IP

スキーマ

各ポリシータイプは XML スキーマ(.xsd)によって定義されます。GitHub に参照用のポリシー スキーマが用意されています。

エラー リファレンス

このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードおよびエラー メッセージと、Apigee によって設定される障害変数について説明します。この情報は、障害に対処する障害ルールを作成するうえで重要です。詳細については、ポリシーエラーについて知っておくべきこと障害の処理をご覧ください。

ランタイム エラー

これらのエラーは、ポリシーの実行時に発生することがあります。

障害コード HTTP ステータス 原因 修正
accesscontrol.IPDeniedAccess 403 クライアント IP アドレス、または API リクエストで渡された IP アドレスが、Access Control ポリシーの <MatchRule> 要素内の <SourceAddress> 要素で指定された IP アドレスと一致し、<MatchRule> 要素の action 属性が DENY に設定されます。
accesscontrol.InvalidIPAddressInVariable 500 <ClientIPVariable> のフロー変数に無効な IP アドレスが含まれています。

障害変数

ランタイム エラーが発生すると、次の変数が設定されます。詳細については、ポリシーエラーに固有の変数をご覧ください。

変数 ここで
fault.name="fault_name" fault_name は、上記のランタイム エラーの表に記載されている障害の名前です。障害名は、障害コードの最後の部分です。 fault.name Matches "IPDeniedAccess"
acl.policy_name.failed policy_name は、障害が発生したポリシーのユーザー指定の名前です。 acl.AC-AllowAccess.failed = true

障害レスポンスの例

{
   "fault":{
     "faultstring":"Access Denied for client ip : 52.211.243.3"
      "detail":{
         "errorcode":"steps.accesscontrol.IPDeniedAccess"
      }
   }
}

障害ルールの例

<FaultRule name="IPDeniedAccess">
    <Step>
        <Name>AM-IPDeniedAccess</Name>
        <Condition>(fault.name Matches "IPDeniedAccess") </Condition>
    </Step>
    <Condition>(acl.failed = true) </Condition>
</FaultRule>