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 アドレス範囲を許可します。在宅勤務のデベロッパーは、これらの API に VPN 経由でアクセスできます。

AccessControl ポリシーを構成して実行するには、以下ことを行います。

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

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

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

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 Analytics の X-Forwarded-For ディメンション

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

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

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

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

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 は 2 進数の 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> 要素

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

<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 に参照用のポリシー スキーマが用意されています。

エラー リファレンス

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
accesscontrol.IPDeniedAccess 403 The client IP address, or an IP address passed in the API request, matches an IP address specified in the <SourceAddress> element within the <MatchRule> element of the Access Control Policy, and the action attribute of the <MatchRule> element is set to DENY.
accesscontrol.InvalidIPAddressInVariable 500 The flow variable in <ClientIPVariable> contains an invalid IP address.

Fault variables

These variables are set when a runtime error occurs. For more information, see Variables specific to policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "IPDeniedAccess"
acl.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. acl.AC-AllowAccess.failed = true

Example fault response

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

Example fault rule

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