Правила AccessControl

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

Что

Правила контроля доступа позволяют разрешать или запрещать доступ к API с определенных IP-адресов.

Вы можете прикрепить это правило к любому месту в потоке прокси-сервера API, но, скорее всего, вам захочется проверять IP-адреса в начале потока ( Request / ProxyEndpoint / PreFlow), даже до аутентификации или проверки квоты.

Примеры

Значения маски в приведенных ниже примерах IPv4 определяют, какие из четырех октетов (8, 16, 24, 32 бита) учитываются правилом соответствия при предоставлении или запрете доступа. Значение по умолчанию: 32. Подробнее об этом атрибуте рассказывается в разделе mask справочника по элементам.

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

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

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

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

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

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

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

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

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

Примечания

Правило контроля доступа не только защищает ваши API от вредоносных IP-адресов, но и позволяет управлять доступом с легитимных IP-адресов. Например, если вы хотите, чтобы доступ к API в вашей тестовой среде имели только компьютеры, контролируемые вашей компанией, вы можете разрешить диапазон IP-адресов для вашей внутренней сети. Разработчики, работающие из дома, могут получить доступ к этим API через VPN.

Настройка и выполнение правил контроля доступа включают следующие этапы:

• Определите набор правил соответствия, с каждым из которых связано одно из двух действий (РАЗРЕШИТЬ или ЗАПРЕТИТЬ).
• Для каждого правила сопоставления укажите IP-адрес (элемент SourceAddress).
  • Чтобы определить, какие IP-адреса в письме будут обрабатываться правилами, ознакомьтесь с разделом Как правило выбирает IP-адрес для оценки.
  • Настройте маску для каждого IP-адреса. Вы разрешаете или запрещаете доступ на основе значения маски в IP-адресе. Подробнее о деидентификации IP-адресов с помощью нотации CIDR…
• Укажите порядок, в котором будут проверяться правила.
• Все правила сопоставления выполняются в заданном порядке. Если правило соответствует, выполняется соответствующее действие, а остальные правила пропускаются.
  • Если одно и то же правило настроено с действиями ALLOW и DENY, будет активировано правило, которое определено первым в порядке, а последующее правило (с другим действием) будет пропущено.

Как правило определяет, какой IP-адрес нужно проверить

IP-адреса могут поступать из разных источников в запросе. Например, заголовок письма True-Client-IP может содержать IP-адрес, а заголовок X-Forwarded-For – один или несколько IP-адресов. В этом разделе рассказывается, как настроить правило AccessControl, чтобы оно оценивало нужные вам IP-адреса.

Ниже описана логика, которую использует правило AccessControl, чтобы определить, какой IP-адрес нужно проверить:

1. Заголовок True-Client-IP

Сначала правило проверяет наличие IP-адреса в заголовке True-Client-IP. Если заголовок содержит действительный IP-адрес, правило оценивает этот адрес.

2. Заголовок X-Forwarded-For

Если заголовок True-Client-IP отсутствует или вы задали для элемента <IgnoreTrueClientIPHeader> значение true, правило оценивает IP-адреса в заголовке X-Forwarded-For.

Edge автоматически заполняет заголовок X-Forwarded-For IP-адресом, полученным в результате последнего внешнего рукопожатия TCP (например, IP-адресом клиента или маршрутизатора). Если в заголовке несколько IP-адресов, скорее всего, это цепочка серверов, которые обработали запрос. Однако список адресов также может содержать поддельный IP-адрес. Как правила определяют, какие адреса нужно проверять?

Конфигурация организации и правила определяют, какие адреса X-Forwarded-For оцениваются правилом.

Сначала проверьте, задано ли для вашей организации свойство feature.enableMultipleXForwardCheckForACL. Вы можете использовать API Получить организацию. Тогда:

• Если вы не видите feature.enableMultipleXForwardCheckForACL в списке ресурсов организации, значит для этого ресурса задано значение false (по умолчанию). Если для этого свойства задано значение false, правило оценивает последний адрес в заголовке (видимый в инструменте трассировки), который представляет собой IP-адрес, полученный Edge от последнего внешнего подтверждения установления TCP-соединения.
• Если для правила feature.enableMultipleXForwardCheckForACL в вашей организации задано значение true, настройте элемент <ValidateBasedOn>, чтобы определить, какие IP-адреса будут оцениваться правилом.

изменили свойство feature.enableMultipleXForwardCheckForACL;

Администраторы организации Edge могут использовать API Update organization properties, чтобы задать свойство feature.enableMultipleXForwardCheckForACL.

В приведенном ниже примере API задается свойство в Edge для частного облака. Если в вашей организации заданы другие свойства, добавьте их тоже. В противном случае они будут удалены.

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

В Edge для частного облака после изменения значения свойства feature.enableMultipleXForwardCheckForACL необходимо перезапустить процессоры сообщений, как описано в разделе Запуск, остановка и перезапуск отдельных компонентов.

Параметры X-Forwarded-For в аналитике Apigee

Edge Analytics записывает значение заголовка X-Forwarded-For в параметр x_forwarded_for_ip. Чтобы определить IP-адрес клиента, отправившего запрос в Edge, используйте значения параметров ax_true_client_ip или ax_resolved_client_ip. Подробнее о показателях, параметрах и фильтрах Аналитики…

Деидентификация IP-адресов с помощью нотации CIDR

Нотация CIDR (бесклассовая междоменная маршрутизация) – это способ указать диапазон IP-адресов с помощью маскировки. Это относится к IPv4 и IPv6. Вот как это работает. В наших примерах для простоты используется IPv4.

IP-адреса представляют собой группы чисел, разделенных точками. В двоичной системе каждая группа представляет собой определенное количество битов (8 для IPv4 и 16 для IPv6). IP-адрес IPv4 198.51.100.1 в двоичном виде выглядит так:

11000110.00110011.01100100.00000001

Это четыре группы по восемь бит, то есть всего 32 бита. В нотации CIDR диапазон можно указать, добавив к IP-адресу косую черту и число от 1 до 32, например:

198.51.100.1/24

В этом случае значением атрибута mask в правиле будет число 24.

Эта запись означает, что первые 24 бита должны быть сохранены без изменений, а оставшиеся биты могут иметь любое значение от 0 до 255. Пример:

Обратите внимание, что маска применяется в конце третьей группы. Таким образом, вы создаете маску, например 198.51.100.*. В большинстве случаев для маскировки достаточно использовать числа, кратные 8 (для IPv4) и 16 (для IPv6):

IPv4: 8, 16, 24, 32

IPv6: 16, 32, 48, 64, 80, 96, 112, 128.

Однако вы можете использовать другие числа для более точного управления, которое включает небольшие вычисления в двоичной системе. Пример с маской 30, как в 198.51.100.1/30, где последняя единица в двоичном коде 00000001:

В этом примере при конфигурации, заданной как <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

Сведения об элементах

В справочнике по элементам описаны элементы и атрибуты правила контроля доступа.

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

The following table describes attributes that are common to all policy parent elements:

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>

Элемент <IgnoreTrueClientIPHeader>

Если задать значение True, правило будет игнорировать заголовок True-Client-IP и оценивать IP-адреса в заголовке X-Forwarded-For в соответствии с настроенным поведением при оценке X-Forwarded-For.

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

Элемент <IPRules>

Родительский элемент, содержащий правила, которые разрешают или запрещают IP-адреса. Атрибут noRuleMatchAction позволяет определить, как обрабатывать IP-адреса, не соответствующие правилам сопоставления.

<IPRules noRuleMatchAction = "ALLOW">

Атрибуты

Элемент <IPRules>/<MatchRule>

Действие, которое нужно выполнить (разрешить или запретить доступ), если IP-адрес соответствует SourceAddress(es), которые вы определили.

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

Атрибуты

Элемент <IPRules>/<MatchRule>/<SourceAddress>

Диапазон IP-адресов клиента.

Допустимое значение: действительный IP-адрес (в десятично-точечной нотации). Чтобы использовать подстановочные знаки, добавьте атрибут 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-адрес в карте "ключ-значение" (KVM) и использовать правило KeyValueMapOperations, чтобы получить IP-адрес и назначить его переменной (например, kvm.ip.value). После этого вы сможете использовать эту переменную для IP-адреса:

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

Установка маски и/или IP-адреса с помощью переменной позволяет изменять значения во время выполнения без необходимости изменять и повторно развертывать прокси API.

Атрибуты

Элемент <ValidateBasedOn>

Если HTTP-заголовок X-Forwarded-For содержит несколько IP-адресов, используйте элемент ValidateBasedOn, чтобы указать, какие из них нужно оценивать.

Используйте этот подход к оценке IP-адресов, только если вы уверены в их действительности. Например, если вы решите оценивать все IP-адреса в заголовке X-Forwarded-For, вам нужно будет доверять действительности этих адресов и/или настроить комплексные правила DENY или ALLOW, чтобы только доверенные IP-адреса могли вызывать ваш прокси-сервер API.

Самый левый IP-адрес в заголовке принадлежит клиенту, а самый правый – серверу, который переслал запрос текущему сервису. Крайний справа или последний IP-адрес – это адрес, полученный Edge в результате последнего внешнего рукопожатия TCP.

Значение, которое вы введете в этом элементе, позволит вам определить, нужно ли проверять все 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>

Схемы

Каждый тип правил определяется 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>