AccessControl ポリシー

概要

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

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

サンプル

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

<AccessControl name=">;AC<L"
  IPRules noRuleMatchAction> = &q<uot;ALLOW"
    Match>Rule ac<tion = "DENY">
      Sourc<eAddress mask=>"<;32"1>98.<51.100.1>/<SourceAddress
>    /MatchRule
  /IPRules
/AccessControl

<AccessControl name=">;AC<L"
  IPRules noRuleMatchAction> = &q<uot;ALLOW"
    Match>Rule ac<tion = "DENY"
      SourceA>ddress mask=&q<uot;{kvm.mask.>value<}"{kv>m.ip.<value}/S>o<urceAddress
  >  /MatchRule
    /IPRules
/AccessControl

<AccessControl name=">;AC<L"
  IPRules noRuleMatchAction> = &q<uot;ALLOW"
    Match>Rule ac<tion = "DENY">
      Sourc<eAddress mask=>"<;24"1>98.51<.100.1/S>o<urceAddress
  >  /MatchRule
    /IPRules
/AccessControl

<AccessControl name=">;AC<L"
  IPRules noRuleMatchAction> = &q<uot;ALLOW"
    Match>Rule act<ion = "DENY"
>       Sourc<eAddress mask=>"<;16"1>98.<51.100.1>/<SourceAddress
>    /MatchRule
  /IPRules
/AccessControl

<AccessControl name=">;AC<L"
  IPRules noRuleMatchAction> = &q<uot;ALLOW"
    MatchR>ule act<ion = "ALLOW">
      So<urceAddress ma>sk=&q<uot;32&quo>t;192<.0.2.1/SourceAddress
    >/MatchR<ule
    MatchRule actio>n = "DE<NY"
     > Sour<ceAddress >mas<k=">2<4"198.51.>100.1/SourceAddress
    /MatchRule
  /IPRules
/AccessControl

<AccessControl name=">;AC<L"
  IPRules noRuleMatchActio>n = &<quot;DENY"
    MatchR>ule act<ion = "ALLOW">
      Sourc<eAddress mask=>"<;16"1>98.<51.100.1>/<SourceAddress
>    /MatchRule
  /IPRules
/AccessControl

<AccessControl name=">;AC<L"
  IPRules noRuleMatchActio>n = &<quot;DENY"
    MatchR>ule act<ion = "ALLOW">
      Sourc<eAddress mask=>"2<4"198.51.100.1/Sou>rceAddres<s
      Source>Address< mask="24"192>.0.2.1/Sour<ceAddress
    >  Sour<ceAddress >mas<k=">2<4"203.0.1>13.1/SourceAddress
     /MatchRule
  /IPRules
/AccessControl

<AccessControl name=">;AC<L"
  IPRules noRuleMatchAction> = &q<uot;ALLOW"
    Match>Rule ac<tion = "DENY">
      Sourc<eAddress mask=>"2<4"198.51.100.1/Sou>rceAddres<s
      Source>Address< mask="24"192>.0.2.1/Sour<ceAddress
    >  Sou<rceAddress> ma<sk=">;<24"203.0.>113.1/SourceAddress
    /MatchRule
  /IPRules
/AccessControl

<AccessControl name=">;AC<L"
  IPRules noRuleMatchActio>n = &<quot;DENY"
    Match>Rule ac<tion = "DENY">
      Sourc<eAddress mask=>"2<4"198.51.100.1/Sou>rceAddres<s
      Source>Address< mask="24"192>.0.2.1/Sour<ceAddress
    >  Sou<rceAddress> mask<="24"203.0.113.1>/Source<Address
    /MatchRule
>    MatchRul<e action = &qu>ot;ALLO<W"
      SourceAdd>ress mask<="16">;198.51<.100.1/SourceAddress
  >    SourceA<ddress mask=&q>uot;1<6"192>.0.<2.1/Sour>c<eAddress
     > SourceAddress mask="16"203.0.113.1/SourceAddress
    /MatchRule
  /IPRules
/AccessControl

使用上の注意

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

Access Control ポリシーの構成と実行は、次のとおりです。

• 照合ルールのセットを定義し、それぞれに関連付けられた 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 アドレスを評価します。

Edge によって、最後の外部 TCP handshake（クライアント IP やルーターなど）から受信した IP アドレスが X-Forwarded-For ヘッダーに事前入力されます。ヘッダーに複数の IP アドレスが入力されている場合、それらのアドレスはリクエストを処理した一連のサーバーである可能性があります。しかし、アドレスのリストになりすましの IP アドレスが含まれている可能性もあります。このとき、ポリシーが評価するアドレスは何に基づいて決定されるでしょうか。

ポリシーが評価する X-Forwarded-For アドレスは、組織構成とポリシー構成によって決定されます。

組織に feature.enableMultipleXForwardCheckForACL プロパティが設定されているかどうかを確認します。これは、Get Organization API を使用して確認できます。次に、以下のように指定します。

• 組織のプロパティ リストに feature.enableMultipleXForwardCheckForACL が表示されない場合は、プロパティが false（デフォルト）に設定されていることを表します。このプロパティを false に設定すると、ポリシーは、Edge が最後の外部 TCP handshake から受信した IP アドレスであるヘッダー内の最後のアドレス（Trace ツールに表示）を評価します。
• 組織の feature.enableMultipleXForwardCheckForACL が true に設定されている場合は、ポリシーが評価する IP アドレスが特定されるように <ValidateBasedOn> 要素を構成します。

feature.enableMultipleXForwardCheckForACL プロパティの変更

Edge 組織管理者は、組織プロパティ更新 API を使用して、feature.enableMultipleXForwardCheckForACL プロパティを設定できます。

次の API の例では、Edge for Private Cloud でプロパティを設定しています。その他のプロパティが組織に設定されている場合は、それも含めます。含めなかった場合は、削除されます。

curl -u email:password -X POST -H "Content-type:application/xml" http://host:8080/v1/o/my<org -d \
"Organization type="trial&qu>ot; n<ame="M>yOrganization&<quot;
    Di>splay<NameMyOrga>nization/<DisplayName
    Properties
        Property name="fe>atur<e.enableM>ultipleXF<orwardCheckForACL"true/Property
        !-- >Inclu<de other ex>i<sting propert>ies as well. --
    /Properties
/Organization"

Edge for Private Cloud で、feature.enableMultipleXForwardCheckForACL プロパティの値を変更した後、個々のコンポーネントの起動 / 停止 / 再起動の説明に従ってメッセージ プロセッサを再起動します。

Apigee Analytics の X-Forwarded-For ディメンション

Edge Analytics によって、X-Forwarded-For ヘッダーの値が x_forwarded_for_ip ディメンションに書き込まれます。Edge にリクエストを送信したクライアント 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 の任意の値でよい」という意味です。次に例を示します。

グループ 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 を設定した例です。

この例の場合、構成を <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

要素リファレンス

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

<?xml version="1.0" encoding="UTF-8&quo>t<; standalone="yes"?
AccessControl async="false" continueOnError=">false<" enab>led="true&q<uot; name=&q>uot;A<ccess-Control-1"
    DisplayNa>meAccess <Control 1/DisplayName
    >IPRules noRul<eMatchAction = "AL>LOW"
  <      MatchRul>e action <= "AL>LOW"<
            SourceAddres>s mask="<32"198.51.100.1/So>urceAddress
<        /Match>Rule
    <    MatchR>ule a<ction = >"<;DENY"
   >         SourceAddress< mask="24&q>u<ot;198.51.100.>1/SourceAddress
        /MatchRule
    /IPRules
    ValidateBasedOnX_FORWARDED_FOR_ALL_IP/ValidateBasedOn
/AccessControl

<AccessControl> 属性

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

次の表に、すべてのポリシーの親要素に共通する属性を示します。

<DisplayName> 要素

管理 UI プロキシ エディタで name 属性と一緒に使用して、ポリシーのラベルに使用する自然言語名を指定します。

<DisplayName>Policy Display Name</DisplayName>

<IgnoreTrueClientIPHeader> 要素

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

<AccessControl async="false" continueOnError="false" enabled="true>"<; name=&quo>t;Access-Control<-1"
   > Disp<layNameAccess Control-1/>Disp<layName
    IgnoreTrueCli>entIPHead<ertrue/IgnoreT>rueClientIPHeader
    ...
/AccessControl

<IPRules> 要素

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

<IPRules noRuleMatchAction = "A>LLOW"

属性

<IPRules>/<MatchRule> 要素

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

<IPRules noRuleMatchAction = "A>LLOW&<quot;
    MatchRule action> = "<ALLOW"
        Sou>rceAddress m<ask="32&q>uot;1<98.51.100.>1/Sou<rceAddress
    /MatchRule>
    Matc<hRule action = "DE>NY"
   <     SourceAdd>ress <mask=">;<24">198.51.100.1/SourceAddress
    /MatchRule
/IPRules

属性

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

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

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

<IPRules noRuleMatchAction = "A>LLOW&<quot;
    MatchRule action> = "<ALLOW"
        SourceAddre>ss mask=&quo<t;{variable}&q>uot;1<98.51.100.>1/Sou<rceAddress
    /MatchRule>
    Matc<hRule action = "DE>NY"</span>
 <       SourceA>ddres<s mask=&qu>o<t;24&quo>t;{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 プロキシを再デプロイすることなく、ランタイムに値を柔軟に変更できるようになります。

属性

<ValidateBasedOn> 要素

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

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

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

この要素に入力する値によって、ヘッダー内の IP アドレスすべて（デフォルト）、最初の IP アドレスのみ、最後の IP アドレスのみのどれをチェック対象にするかが決まります。

<AccessControl async="false" continueOnError="false" enabled="true>"<; name=&quo>t;Access-Control<-1"
   > Disp<layNameAccess Control 1/DisplayName>
    IPRu<les noRuleMatchAction = &>quot;ALLOW&qu<ot;
        MatchRule a>ction = &quo<t;DENY"
 >         <  SourceAd>dress< mask=&q>uot;3<2"198.51.1>00.1/SourceAddress
   <     /MatchRule
> <   /IPRules
  >  ValidateBasedOnX_FORWARDED_FOR_ALL_IP/ValidateBasedOn
/AccessControl

スキーマ

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

エラー リファレンス

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

ランタイム エラー

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

障害変数

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

障害レスポンスの例

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

障害ルールの例

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