AccessControl ポリシー

概要

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

動画: API に対する特定の IP アドレスからのアクセスを許可したり拒否したりする方法の詳細について、短い動画をご覧ください。

このポリシーは 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 だった場合、AccessControl ポリシーによって「198.51.100.*」からのすべてのリクエストが拒否されます。

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

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.*」のサブセットを拒否します。


使用上の注意

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

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

  • 一連のマッチルールを、それぞれに関連付ける 2 つのアクション(ALLOW または DENY)のいずれかで定義します。
  • マッチルールごとに、IP アドレスを指定します(SourceAddress 要素)。
    • IP アドレスごとにマスクを構成します。この IP アドレスのマスク値に基づいて、アクセスが許可または拒否されます。CIDR 表記での IP マスキングについてをご覧ください。
    • X-FORWARDED-FOR ヘッダーが送信元アドレスと見なされます。ヘッダーに複数のアドレスがある場合、<ValidateBasedOn> 要素を使用して評価対象のアドレスを制御します。
  • ルールの試行順序を指定します。
  • マッチルールはすべて指定された順序で実行されます。ルールが一致すると、対応するアクションが実行され、その後のマッチルールはスキップされます。
    • 同じルールに ALLOW と DENY の両方のアクションが構成されている場合、最初に定義されたルールがトリガーとなり、後続のルールは(他のアクションとともに)スキップされます。

HTTP ヘッダー X-Forwarded-For について

Access Control ポリシーは、HTTP ヘッダー X-Forwarded-For の IP アドレスを評価します。このヘッダーに対し、Edge for the Cloud が自動的に、最後の外部 TCP handshake(クライアント IP やルーターなど)から受信した IP アドレスを入力します。ヘッダーに複数のアドレスがある場合、ヘッダーにはリクエストを処理した一連のサーバーの IP アドレスリストが入ります。

ヘッダーの左端の IP アドレスはクライアントに属するもので、右端は現在のサービスにリクエストを転送したサーバーです。たとえば、API プロキシに対するリクエスト(Trace ツールに表示)の X-Forwarded-For ヘッダーには、次のアドレスが含まれています。

    192.0.2.0,192.0.2.128,192.0.2.244
    

X-Forwarded-For ヘッダーは、前回の TCP handshake で受信した IP アドレス Edge となっているヘッダー内の最後のアドレスを除いて、拒否すべき IP アドレスによるなりすましを受ける可能性があります。

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

すべてのバージョンの Edge for Private Cloud で、X-Forwarded-For ヘッダー内のすべての IP を考慮するよう構成できます。X-Forwarded-For 内の IP アドレスを信頼する場合、アーキテクチャでこれを実施できます。Edge で X-Forwarded-For 内の IP アドレスを許可するように構成するには、組織に feature.enableMultipleXForwardCheckForACL プロパティを設定する必要があります。

Private Cloud のお客様は、次の API 呼出しで feature.enableMultipleXForwardCheckForACL プロパティを設定します。他のプロパティが組織に設定されている場合、それも含めます。そのようにしなかった場合は、削除されます。
curl -u email:password -X POST -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \
    "<Organization type="trial" name="MyOrganization">
        <DisplayName>MyOrganization</DisplayName>
        <Properties>
            <Property name="feature.enableMultipleXForwardCheckForACL">true</Property>
            <!-- Include other existing properties as well. -->
        </Properties>
    </Organization>"
    

feature.enableMultipleXForwardCheckForACL プロパティの値の変更後は、個々のコンポーネントの起動、停止、再起動の説明に従って Message Processor を再起動する必要があります。

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

CIDR(Classless Inter-Domain Routing)表記は、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

ただし、細かなバイナリ計算が必要な微調整には、他の数字も使用できます。次に 30 のマスクを使用した例を示します。

この値はそのまま維持 可能値
11000110.00110011.01100100.00000(最初の 30 ビット) 0000000、0000001、0000010、0000011
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

要素リファレンス

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

    <?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">
    

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

属性 説明 デフォルト 要否
name

ポリシーの内部名。name 属性の値には、文字、数字、スペース、ハイフン、アンダースコア、ピリオドを使用できます。255 文字を超える値を指定することはできません。

必要に応じて、管理 UI プロキシ エディタで <DisplayName> 要素を使用してポリシーに別のわかりやすい名前でラベルを付けます。

なし 必須
continueOnError

ポリシーが失敗した場合にエラーを返すには、false に設定します。これはほとんどのポリシーで想定される動作です。

ポリシーが失敗してもフロー実行を続行するには、true に設定します。

false 省略可
enabled

ポリシーを適用するには true に設定します。

ポリシーを無効にするには false に設定します。その場合、ポリシーはフローに接続されていているとしても適用されません。

true 省略可
async

この属性は非推奨となりました。

false 非推奨

<DisplayName> 要素

name 属性に加えて、管理 UI プロキシ エディタのポリシーに別のわかりやすい名前でラベルを付けるために使います。

<DisplayName>Policy Display Name</DisplayName>
デフォルト:

なし

この要素を省略した場合、ポリシーの name 属性の値が使用されます

要否: 省略可
型: 文字列

<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 プロキシフローで現在利用可能な変数を使用して値を設定できます。たとえば、IP アドレスを Key-Value マップ(KVM)に格納し、KeyValueMapOperations ポリシーを使用して IP アドレスを取得し、それを変数(kvm.ip.value など)に割り当てることができます。その変数は IP アドレス用に使用できます。

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

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

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

属性

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

mask 属性は、許可または拒否する IP アドレスの範囲を示す方法です。CIDR(Classless Inter-Domain Routing)表記を使用するマスクと同等です。次に例を示します。

<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> 要素

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

この要素に入力する値によって、ヘッダー内の 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

エラー リファレンス

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

ランタイム エラー

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

障害コード HTTP ステータス 原因
steps.accesscontrol.ClientIpExtractionFailed 500 障害文字列を参照してください。
steps.accesscontrol.IPDeniedAccess 403 障害文字列を参照してください。

デプロイエラー

このポリシーを含むプロキシのデプロイで、次のエラーが発生することがあります。

エラー名 原因
InvalidIPAddress エラー メッセージを参照してください。
InvalidIPv4Address エラー メッセージを参照してください。
InvalidIPv6Address エラー メッセージを参照してください。
InvalidRulePattern エラー メッセージを参照してください。

障害変数

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

変数 説明
fault.name="fault_name" fault_name は障害名です。詳しくは、上のランタイム エラーの表をご覧ください。障害コードの最後の部分が障害名になります。 fault.name Matches "IPDeniedAccess"
acl.policy_name.failed policy_name は、障害が発生したユーザー指定のポリシー名です。 acl.AC-AllowAccess.failed = true

障害レスポンスの例

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

障害ルールの例

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