このページの内容は Apigee と Apigee ハイブリッドに該当します。
Apigee Edge のドキュメントを表示する。
内容
AccessControl ポリシーを利用することで、API に対する特定の IP アドレスからのアクセスを許可または拒否できます。
このポリシーは標準ポリシーであり、任意の環境タイプにデプロイできます。ポリシーのタイプと、各ポリシータイプを使用できる環境タイプについては、ポリシータイプをご覧ください。
動画: 特定の IP アドレスごとに API へのアクセスを許可または拒否する方法を説明する短い動画をご覧ください。
このポリシーは、API プロキシフロー中の任意の場所に接続できますが、フロー(Request / ProxyEndpoint / PreFlow)の先頭、認証前、割り当ての確認の前に IP アドレスのチェックを行うのが一般的です。
API を保護する別の方法として、Apigee で Google Cloud Armor を使用することも検討してください。
サンプル
次の 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.value
と kvm.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 要素)。
- 構成しているルールでメッセージ内のどの IP アドレスを処理するのかを決める方法については、ポリシーで評価する IP アドレスを選択する方法をご覧ください。
- IP アドレスごとにマスクを構成します。この IP アドレスのマスク値に基づいて、アクセスが許可または拒否されます。CIDR 表記による IP マスキングについてをご覧ください。
- ルールの試行順序を指定します。
- すべての照合ルールが指定された順に実行されます。照合ルールが一致すると、それに対応するアクションが実行され、その後の照合ルールはスキップされます。
- 同じルールに 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_resolved_client_ip
ディメンションの値を使用しますが、AccessControl ポリシーでサポートされていない ax_true_client_ip
は除外します。分析の指標、ディメンション、フィルタのリファレンスをご覧ください。
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 アドレスのみ) |
属性
属性 | 説明 | 型 | デフォルト | 要否 |
---|---|---|---|---|
マスク |
同等の CIDR 表記: 198.51.100.1/24 有効な値: IPv4: 1~32 IPv6: 1~128 値をゼロ(0)とすると IP 0.0.0.0 に対してのみ有効になるため、実際的ではありません。 マスクを変数で設定する
|
整数 | なし | 必須 |
<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 |
---|---|
要否 | 任意 |
有効な値 |
|
スキーマ
各ポリシータイプは XML スキーマ(.xsd)によって定義されます。GitHub に参照用のポリシー スキーマが用意されています。
エラー リファレンス
このセクションでは、このポリシーによってエラーがトリガーされたときに返される障害コードとエラー メッセージ、Apigee によって設定される障害変数について説明します。これは、障害に対処する障害ルールを作成するうえで重要な情報です。詳細については、ポリシーエラーについて知っておくべきことと障害の処理をご覧ください。
ランタイム エラー
このエラーは、ポリシーの実行時に発生することがあります。
障害コード | HTTP ステータス | 原因 | 修正 |
---|---|---|---|
accesscontrol.IPDeniedAccess |
403 |
クライアント IP アドレス、または API リクエストで渡された IP アドレスが、Access Control ポリシーの <MatchRule> 要素内の <SourceAddress> 要素で指定された IP アドレスと一致し、<MatchRule> 要素の action 属性が DENY に設定されています。 |
build |
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>