AccessControl-Richtlinie

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Was

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

Diese Richtlinie ist eine Standardrichtlinie, die in jeder Umgebung bereitgestellt werden kann. Informationen zu Richtlinientypen und zur Verfügbarkeit bei jedem Umgebungstyp finden Sie unter Richtlinientypen.

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.

Als alternative Möglichkeit zum Schutz Ihrer APIs sollten Sie auch Google Cloud Armor mit Apigee in Betracht ziehen.

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.

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

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).
  • Lesen Sie So wählt die Richtlinie die zu evaluierende IP-Adresse aus, um zu ermitteln, welche IP-Adresse(n) in der konfigurierten Nachricht verarbeitet werden soll(en).
  • Konfigurieren Sie eine Maske für jede IP-Adresse. Sie können den Zugriff anhand eines Maskenwerts für die IP-Adresse zulassen oder ablehnen. Weitere Informationen finden Sie unter IP-Masken mit CIDR-Notation.
• 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. Um die Client-IP zu ermitteln, die die Anfrage an Apigee gesendet hat, verwenden Sie die Werte in der ax_resolved_client_ip-Dimension, schließen aber ax_true_client_ip aus. Dies wird im Fall dur AccessControl-Richtlinie nicht unterstützt. Siehe Referenz zu Analysemesswerten, -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:

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:

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>

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

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

Attribute

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

Attribute

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

Attribute

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

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.

Fehlervariablen

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

Beispiel für eine Fehlerantwort

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

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>