HINWEIS: Einige Aspekte dieses Produkts befinden sich in der Betaphase. Die hybriden Installationsoptionen sind allgemein verfügbar. Wenn Sie am Beta-Programm teilnehmen möchten, wenden Sie sich an Ihren Apigee-Vertreter.

AccessControl-Richtlinie

Was

Mit der AccessControl-Richtlinie können Sie den Zugriff auf Ihre APIs über bestimmte IP-Adressen zulassen oder ablehnen.

Video: In einem kurzen Video erfahren Sie, wie Sie den Zugriff auf Ihre APIs über bestimmte IP-Adressen zulassen oder ablehnen.

Sie können diese Richtlinie an einer beliebigen Stelle im API-Proxy-Ablauf anhängen. Es empfiehlt sich aber, die IP-Adressen zu Beginn des Ablaufs ( Anfrage / ProxyEndpoint / PreFlow) zu prüfen, bevor Sie eine Authentifizierung oder Kontingentprüfung durchführen.

Beispiele

Die Maskenwerte in den folgenden IPv4-Beispielen bestimmen, welches der vier Oktett (8, 16, 24, 32 Bit) die Abgleichsregel berücksichtigt, wenn der Zugriff zugelassen oder verweigert wird. Der Standardwert ist 32. Weitere Informationen finden Sie in der Elementreferenz zum Attribut mask.

198.51.100.1 ablehnen

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

Alle Anfragen von Clientadresse ablehnen: 198.51.100.1

Anfragen von anderer Clientadresse zulassen.

Mithilfe von Variablen ablehnen

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

Angenommen, Sie verwenden eine Schlüsselwertzuordnung (KVM), um Werte für die Maskierung und IP-Adressen zu speichern. Dies ist ein praktisches Verfahren, um IP-Adressen zu ändern und während der Laufzeit zu maskieren, ohne den API-Proxy aktualisieren oder neu bereitstellen zu müssen. Auf der SeiteRichtlinie "KeyValueMapOperations" um die Variablen abzurufen, die die Werte fürkvm.mask.value und kvm.ip.value Dabei wird davon ausgegangen, dass Sie die Variablen in Ihrer KVM-Richtlinie benannt haben, die die Werte der Maske und IP-Werte Ihrer KVM enthalten. Wenn die abgerufenen Werte 24 für die Maske und 198.51.100.1 für die IP-Adresse wären, würde die AccessControl-Richtlinie alle Anfragen von 198.51.100 ablehnen.*

Alle anderen Clientadressen wären zulässig.

198.51.100.* ablehnen

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

Alle Anfragen von Clientadresse ablehnen: 198.51.100.*

Anfragen von anderer Clientadresse zulassen.

198.51.*.*

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

Alle Anfragen von Clientadresse ablehnen: 198.51.*.*

Anfragen von anderer Clientadresse zulassen.

198.51.100.* ablehnen, 192.0.2.1 zulassen

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

Alle Anfragen von der Clientadresse ablehnen: 198.51.100.*, jedoch 192.0.2.1 erlauben.

Anfragen von anderer Clientadresse zulassen.

198.51.*.* zulassen

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

Alle Anfragen von Adresse zulassen: 198.51.*.*

Anfragen von anderer Clientadresse ablehnen.

Mehrere IP-Adressen zulassen

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

Anfragen von Clientadressen zulassen: 198.51.100.* 192.0.2.* 203.0.113.*

Alle anderen Adressen ablehnen.

Mehrere IP-Adressen ablehnen

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

Anfragen von Clientadressen zulassen: 198.51.100.* 192.0.2.* 203.0.113.*

Alle anderen Adressen zulassen.

Mehrere IP-Adressen zulassen, mehrere IP-Adressen ablehnen

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

Zulassen: 198.51.*.* 192.0.*.* 203.0.*.*

Lehnen Sie einen Teil der Zulassen-Liste ab: 198.51.100.* 192.0.2.* 203.0.113.*


Verwendungshinweise

Die AccessControl-Richtlinie schützt Ihre APIs nicht nur vor böswilligen IP-Adressen, sondern gibt Ihnen auch die Kontrolle über den legitimen IP-Zugriff. Wenn Sie beispielsweise nur Computer unter der Kontrolle Ihres Unternehmens auf die APIs in Ihrer Testumgebung zugreifen möchten, können Sie den IP-Adressbereich für Ihr internes Netzwerk zulassen. Entwickler, die von zu Hause aus arbeiten, können über VPN auf diese APIs zugreifen.

Die Konfiguration und Ausführung einer AccessControl-Richtlinie umfasst Folgendes:

  • Definieren Sie eine Gruppe von Übereinstimmungsregeln mit einer der beiden Aktionen (ALLOW oder DENY).
  • Geben Sie für jede Übereinstimmungsregel die IP-Adresse an (SourceAddress-Element).
  • Geben Sie die Reihenfolge an, in der die Regeln getestet werden.
  • Alle Übereinstimmungsregeln werden in der angegebenen Reihenfolge ausgeführt. Wenn eine Regel übereinstimmt, wird die entsprechende Aktion ausgeführt und die folgenden Abgleichsregeln werden übersprungen.
    • Wenn dieselbe Regel sowohl mit ALLOW- als auch mit DENY-Aktionen konfiguriert ist, wird die Regel, die zuerst in der Reihenfolge definiert ist, ausgelöst und die nachfolgende Regel (mit der anderen Aktion) wird übersprungen.

So wählt die Richtlinie die zu bewertende IP-Adresse aus

IP-Adressen können aus verschiedenen Quellen in einer Anfrage stammen. Der Nachrichtenheader True-Client-IP könnte beispielsweise eine IP-Adresse enthalten und der Header X-Forwarded-For kann eine oder mehrere IP-Adressen enthalten. In diesem Abschnitt wird beschrieben, wie Sie die AccessControl-Richtlinie konfigurieren, um die genauen IP-Adressen zu bewerten, die bewertet werden sollen.

Im Folgenden ist die Logik aufgeführt, mit der die AccessControl-Richtlinie entscheidet, welche IP-Adresse evaluiert werden soll:

1. True-Client-IP-Header

Die Richtlinie prüft den Header True-Client-IP zuerst auf eine IP-Adresse. Wenn der Header eine gültige IP-Adresse enthält, wird diese Adresse von der Richtlinie evaluiert.

2. X-Forwarded-For-Header

Wenn kein True-Client-IP-Header vorhanden ist oder Sie das <IgnoreTrueClientIPHeader>-Element auf "true" gesetzt haben, wertet die Richtlinie die IP-Adressen im X-Forwarded-For-Header aus.

Apigee fügt den X-Forwarded-For-Header automatisch mit der IP-Adresse ein, die er vom letzten externen TCP-Handshake erhalten hat, z. B. die Client-IP oder den Router. Wenn der Header mehrere IP-Adressen enthält, handelt es sich höchstwahrscheinlich um die Kette von Servern, die eine Anfrage verarbeitet haben. Die Liste der Adressen kann jedoch auch eine gefälschte IP-Adresse enthalten. Woher weiß die Richtlinie, welche Adressen bewertet werden?

X-Forwarded-For-Dimensionen in Apigee Analytics

Apigee Analytics schreibt den Wert des Headers X-Forwarded-For in die Dimension x_forwarded_for_ip. Verwenden Sie die Werte in der Dimension ax_true_client_ip oder ax_resolved_client_ip, um die Client-IP zu ermitteln, die die Anfrage an Apigee gesendet hat. Weitere Informationen finden Sie unter Referenz zu Analytics-Messwerten, -Dimensionen und -Filtern.

IP-Masken mit CIDR-Notation

Mithilfe der CIDR-Notation (Classless Inter-Domain Routing) können Sie einen Bereich von IP-Adressen durch Maskierung angeben. Dies gilt sowohl für IPv4 als auch für IPv6. Und so gehts. Zur Vereinfachung verwenden wir in unseren Beispielen IPv4.

IP-Adressen sind durch Punkte getrennte Zahlengruppen. In binärer Form ist jede Gruppe eine bestimmte Anzahl von Bits (8 für IPv4 und 16 für IPv6). Die IPv4-Adresse 198.51.100.1 sieht in binärer Form so aus:

11000110.00110011.01100100.00000001

Das sind 4 Gruppen mit 8 Bit bzw. insgesamt 32 Bits. Mit CIDR können Sie einen Bereich angeben, indem Sie der IP-Adresse eine /Nummer (1-32) hinzufügen:

198.51.100.1/24

In diesem Fall ist 24 die Zahl, die Sie für den Attributwert mask in dieser Richtlinie verwenden würden.

Diese Notation bedeutet: "Lassen Sie die ersten 24 Bits genau so, wie sie sind, die restlichen Bits können einen beliebigen Wert von 0 bis 255 haben." Beispiel:

Belassen Sie sie, wie sie sind Mögliche Werte für die letzte Gruppe
198.51.100. 0–255

Beachten Sie, dass die Maske am Ende von Gruppe 3 erfolgt. Damit wird eine Maske wie diese erstellt: 198.51.100.*. In den meisten Fällen erzielen Sie mit Vielfachen von 8 (IPv4) und 16 (IPv6) die gewünschte Maskenebene:

IPv4: 8, 16, 24, 32

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

Sie können aber auch andere Zahlen für die genauere Steuerung verwenden. Dies erfordert eine kleine Binärberechnung. Im Folgenden sehen Sie ein Beispiel mit einer Maske von 30, wie in 198.51.100.1/30, wobei die letzte 1 das Element 00000001 in binärer Form ist:

Belassen Sie sie, wie sie sind Mögliche Werte
11000110.00110011.01100100.000000 (erste 30 Bit) 00000000, 00000001, 00000010, oder 00000011
198.51.100. 0, 1, 2, oder 3

Wenn in diesem Beispiel die Konfiguration auf <SourceAddress mask="30">198.51.100.1</SourceAddress> gesetzt ist, werden je nach Regeln die folgenden IP-Adressen zugelassen oder abgelehnt:

  • 198.51.100.0
  • 198.51.100.1
  • 198.51.100.2
  • 198.51.100.3

Elementverweis

In der Elementreferenz werden die Elemente und Attribute der AccessControl-Richtlinie beschrieben.

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

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

<ClientIPVariable>-Element

Gibt eine Ablaufvariable an, die eine IP-Adresse enthält, die von der Richtlinie mit den IPRules abgeglichen wird. Wenn die Ablaufvariable keine gültige IP-Adresse (ipv4 oder ipv6) enthält, gibt die Richtlinie einen Fehler aus.

Angenommen, die Ablaufvariable ist auf 12.31.34.52 eingestellt. Im folgenden Beispiel wird der Zugriff verweigert. Wenn die Variable auf 10.11.12.13 gesetzt ist, wird der Zugriff gewährt.


<AccessControl name='ACL'>
   <ClientIPVariable>FLOW_VARIABLE</ClientIPVariable>
   <IPRules noRuleMatchAction = 'DENY'>
     <MatchRule action = 'ALLOW'>
       <SourceAddress mask='32'>10.11.12.13</SourceAddress>
     </MatchRule>
   </IPRules>
</AccessControl>

Standard
Präsenz Optional
Typ Ablaufvariable

<IgnoreTrueClientIPHeader>-Element

Wenn Sie dies auf "true" setzen, ignoriert die Richtlinie den Header True-Client-IP und wertet IP-Adressen im Header X-Forwarded-For gemäß dem X-Forwarded-For-Evaluierungsverhalten aus, das Sie konfiguriert haben.


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

Standard false
Präsenz Optional
Typ Boolean

<IPRules>-Element

Das übergeordnete Element mit den Regeln, die IP-Adressen zulassen oder ablehnen. Mit dem Attribut noRuleMatchAction können Sie festlegen, wie IP-Adressen behandelt werden sollen, die nicht von Ihren Abgleichsregeln abgedeckt werden.

<IPRules noRuleMatchAction = "ALLOW">
Standard
Präsenz Optional
Typ

Attribute

Attribut Beschreibung Typ Default Präsenz
noRuleMatchAction
Die erforderliche Aktion (Zugriff erlauben oder ablehnen), wenn die angegebene Regel nicht aufgelöst wird (keine Übereinstimmung).
Gültiger Wert: ALLOW oder DENY
String ZULASSEN Erforderlich

<IPRules>/<MatchRule>-Element

Die auszuführende Aktion (zulassen oder ablehnen), wenn die IP-Adresse mit den von Ihnen definierten Quelladresse(n) übereinstimmt

<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>
Standard
Präsenz Optional
Typ

Attribute

Attribut Beschreibung Typ Default Präsenz
Aktion

Die erforderliche Aktion (Zugriff erlauben oder ablehnen), wenn die angegebene Regel nicht aufgelöst wird (keine Übereinstimmung).

Gültiger Wert: ALLOW oder DENY

String ZULASSEN Erforderlich

<IPRules>/<MatchRule>/<SourceAddress>-Element

Der IP-Adressbereich eines Clients.

Gültiger Wert: Gültige IP-Adresse (Dezimalformat mit Punkten) Für Platzhalterverhalten verwenden Sie das Attribut 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>

Wie im vorherigen Beispiel gezeigt, unterstützt das Element SourceAddress auch Nachrichtenvorlagen für das Attribut mask oder die IP-Adresse. Das bedeutet, dass Sie die Werte mit Hilfe von Variablen einstellen können, die derzeit im API-Proxy-Ablauf verfügbar sind.

Sie können beispielsweise eine IP-Adresse in einer Schlüssel/Wert-Paarzuordnung (KVM) speichern und die KeyValueMapOperations-Richtlinie verwenden, um die IP-Adresse abzurufen und einer Variablen zuzuweisen (z. B. kvm.ip.value). Sie können diese Variable dann für die IP-Adresse verwenden:

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

Wenn Sie eine Maske und/oder IP-Adresse mit einer Variablen festlegen, können Sie Werte zur Laufzeit ändern, ohne den API-Proxy ändern oder neu bereitstellen zu müssen.

Standard
Präsenz Optional
Typ String (nur eine einzelne IP-Adresse)

Attribute

Attribut Beschreibung Typ Default Präsenz
maskieren

Mit dem Attribut mask geben Sie den zulässigen IP-Adressbereich an. Maske ist das Äquivalent zur Verwendung von CIDR-Notation (Classless Inter-Domain Routing). Beispiel:

<SourceAddress mask="24">198.51.100.1</SourceAddress>

entspricht der folgenden CIDR-Notation:

198.51.100.1/24

Zulässige Werte:

IPv4: 1–32

IPv6: 1–128

Ein Wert von null (0) ist nur für die IP-Adresse 0.0.0.0 gültig, und daher unpraktisch.

Maske mit einer Variablen festlegen

Das Attribut mask unterstützt auch Nachrichtenvorlagen. Das bedeutet, dass Sie den Wert mit einer Variablen festlegen können, die derzeit im API-Proxy-Flow verfügbar ist. Sie können beispielsweise einen Maskenwert in einer KVM speichern und die KeyValueMapOperations-Richtlinie verwenden, um die Maske abzurufen und einer Variablen zuzuweisen. Um die IP-Maske mit der Variablen festzulegen, verwenden Sie das folgende Format unter der Annahme, dass die Variable den Namen kvm.mask.value hat:

mask="{kvm.mask.value}"

Integer Erforderlich

<ValidateBasedOn>-Element

Wenn der HTTP-Header X-Forwarded-For mehrere IP-Adressen enthält, können Sie mit diesem ValidateBasedOn-Element steuern, welche IP-Adressen evaluiert werden.

Verwenden Sie diesen Ansatz zur Auswertung von IP-Adressen nur, wenn Sie sich über die Gültigkeit der IP-Adressen, die Sie auswerten möchten, sicher sind. Wenn Sie sich beispielsweise dafür entscheiden, alle IP-Adressen im Header X-Forwarded-For auszuwerten, müssen Sie in der Lage sein, der Gültigkeit dieser Adressen zu vertrauen und/oder umfassende DENY- oder ALLOW-Regeln aufzustellen, damit nur vertrauenswürdige IPs Ihren API-Proxy aufrufen können.

Die ganz linke IP-Adresse im Header gehört dem Client, und die ganz rechte ist der Server, der die Anfrage an den aktuellen Dienst weitergeleitet hat. Die ganz rechte oder letzte IP-Adresse ist die Adresse, die Apigee vom letzten externen TCP-Handshake erhalten hat.

Mit dem Wert, den Sie in dieses Element eingeben, können Sie festlegen, ob alle IP-Adressen im Header (Standard), nur die erste IP-Adresse oder nur die letzte IP-Adresse geprüft werden soll.

<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>
Standard X_FORWARDED_FOR_ALL_IP
Präsenz Optional
Typ String
Zulässige Werte
  • X_FORWARDED_FOR_ALL_IP (Standard)
  • X_FORWARDED_FOR_FIRST_IP
  • X_FORWARDED_FOR_LAST_IP

Schemas

Jeder Richtlinientyp wird durch ein XML-Schema (.xsd) definiert. Zu Referenzzwecken sind Richtlinienschemas auf GitHub verfügbar.

Fehlerreferenz

In diesem Abschnitt werden die zurückgegebenen Fehlercodes und Fehlermeldungen beschrieben, die von Apigee festgelegt werden, wenn die Richtlinie einen Fehler auslöst. Diese Informationen sind wichtig, wenn Sie Fehlerregeln zur Verarbeitung von Fehlern entwickeln. Weitere Informationen finden Sie unter Was Sie über Richtlinienfehler wissen müssen und Fehler beheben.

Laufzeitfehler

Diese Fehler können bei Ausführung der Richtlinie auftreten.

Fehlercode HTTP-Status Ursache Beheben
steps.accesscontrol.IPDeniedAccess 403 Die Client-IP-Adresse oder eine in der API-Anfrage übergebene IP-Adresse entspricht einer IP-Adresse, die im Element <SourceAddress> des Elements <MatchRule> der Zugriffssteuerungsrichtlinie angegeben ist, und das Attribut action des Elements <MatchRule> ist auf DENY festgelegt.
steps.accesscontrol.InvalidIPAddressInVariable 500 Die Ablaufvariable in <ClientIPVariable> enthält eine ungültige IP-Adresse.

Fehlervariablen

Diese Variablen werden bei Laufzeitfehlern festgelegt. Weitere Informationen finden Sie unter Für Richtlinienfehler spezifische Variablen.

Variablen Wo Beispiel
fault.name="fault_name" fault_name ist der Name des Fehlers, der in der obigen Tabelle Laufzeitfehler aufgeführt ist. Der Fehlername ist der letzte Teil des Fehlercodes. fault.name Matches "IPDeniedAccess"
acl.policy_name.failed policy_name ist der benutzerdefinierte Name der Richtlinie, die den Fehler ausgelöst hat. acl.AC-AllowAccess.failed = true

Beispiel für eine Fehlerantwort

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

Beispiel für eine Fehlerregel

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