Règle AccessControl

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Quoi

La règle AccessControl vous permet d'autoriser ou de refuser l'accès à vos API à des adresses IP spécifiques.

Bien que vous puissiez installer cette règle n'importe où dans le flux de proxy API, vous souhaiterez probablement vérifier les adresses IP au début du flux (Requête /ProxyEndpoint / PreFlow), avant même l'authentification ou la vérification du quota.

Exemples

Les valeurs de masque des exemples IPv4 ci-dessous permettent d'identifier parmi quatre octets (8, 16, 24, 32 bits) celui que la règle de correspondance prend en compte lors de l'autorisation ou du refus d'accès. La valeur par défaut est 32. Pour en savoir plus, consultez la section concernant l'attribut mask dans la documentation de référence sur les éléments.

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

Remarques sur l'utilisation

En plus de protéger vos API contre les adresses IP malveillantes, la règle AccessControl vous permet également de contrôler l'accès des adresses IP légitimes. Par exemple, si vous souhaitez que les ordinateurs sous contrôle de votre entreprise puissent accéder aux API exposées dans votre environnement de test, vous pouvez autoriser la plage d'adresses IP de votre réseau interne. Les développeurs travaillant à domicile peuvent accéder à ces API à l'aide d'un VPN.

La configuration et l'exécution d'une règle AccessControl impliquent les opérations suivantes :

• Définissez un ensemble de règles de correspondance associées chacune à l'une de ces deux actions (AUTORISER ou REFUSER).
• Pour chaque règle de correspondance, spécifiez l'adresse IP (élément sourceAddress).
  • Consultez la section Comment la règle choisit l'adresse IP à évaluer pour déterminer quelles adresses IP sont traitées par la règle que vous configurez.
  • Configurez un masque pour chaque adresse IP. Vous autorisez ou refusez l'accès en fonction d'une valeur de masque associée à l'adresse IP. Consultez la section À propos des masques d'adresses IP avec la notation CIDR.
• Spécifiez l'ordre dans lequel les règles sont testées.
• Toutes les règles de correspondance sont exécutées dans l'ordre indiqué. Lorsqu'une règle correspond, l'action correspondante est exécutée et les règles de correspondance suivantes sont ignorées.
  • Si la même règle est configurée avec les actions AUTORISER et REFUSER, la règle définie en premier est déclenchée et la règle suivante (l'autre action) est ignorée.

Comment la règle choisit-elle l'adresse IP à évaluer ?

Les adresses IP peuvent provenir de différentes sources dans une requête. Par exemple, l'en-tête du message True-Client-IP peut contenir une adresse IP, et l'en-tête X-Forwarded-For peut contenir une ou plusieurs adresses IP. Cette section explique comment configurer la règle AccessControl pour évaluer précisément les adresses IP que vous souhaitez.

Voici la logique que la règle AccessControl utilise pour déterminer l'adresse IP à évaluer :

1. En-tête "True-Client-IP"

La règle recherche d'abord une adresse IP dans l'en-tête True-Client-IP. Si l'en-tête contient une adresse IP valide, la règle l'évalue.

2. En-tête "X-Forwarded-For"

S'il n'y a pas de True-Client-IP ou si vous avez défini l'élément <IgnoreTrueClientIPHeader> sur "true", la règle évalue les adresses IP dans les en-têtes X-Forwarded-For.

Edge remplit automatiquement l'en-tête X-Forwarded-For par l'adresse IP reçue lors du dernier handshake TCP externe (tel que l'adresse IP du client ou (routeur, par exemple). Si l'en-tête contient plusieurs adresses IP, il s'agit probablement de la chaîne de serveurs qui ont traité une requête. Cependant, la liste d'adresses peut également contenir une adresse IP usurpée. Comment la règle sait-elle quelles adresses évaluer ?

La configuration de votre organisation et de vos règles détermine les adresses X-Forwarded-For que la règle doit évaluer.

Commencez par vérifier si la propriété feature.enableMultipleXForwardCheckForACL est définie sur votre organisation. Vous pouvez utiliser <ph type="x-smartling-placeholder"></ph> Obtenir l'API Organization à vérifier. Ensuite :

• Si vous ne voyez pas feature.enableMultipleXForwardCheckForACL dans la liste des propriétés de votre organisation, cela signifie que cette propriété est définie sur false (valeur par défaut). Si cette propriété est définie sur "false", la règle évalue la dernière adresse dans l'en-tête (visible dans Outil Trace), qui correspond à l'adresse IP Périphérique reçu de la dernière poignée de main TCP externe.
• Si feature.enableMultipleXForwardCheckForACL est défini sur "true", configurez l'élément <ValidateBasedOn> pour déterminer les adresses IP évaluées par la règle.

Modifier la propriété feature.enableMultipleXForwardCheckForACL

Les administrateurs d'organisation Edge peuvent utiliser <ph type="x-smartling-placeholder"></ph> de mise à jour des propriétés de l'organisation pour définir le feature.enableMultipleXForwardCheckForACL.

L'exemple d'API suivant définit la propriété dans Edge pour Private Cloud. Si d'autres propriétés sont définies pour votre organisation, veillez à les inclure également. Sinon, ils seront supprimés.

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

Dans Edge for Private Cloud, après avoir modifié la valeur du feature.enableMultipleXForwardCheckForACL, vous devez redémarrer vos processeurs de messages, comme décrit dans <ph type="x-smartling-placeholder"></ph> Démarrez/Arrêtez/Redémarrez des composants individuels.

Dimensions de X-Forwarded-For d'Apigee Analytics

Edge Analytics écrit la valeur de l'en-tête X-Forwarded-For dans le Dimension x_forwarded_for_ip. Pour déterminer l'adresse IP du client qui a généré la demande à Edge, utilisez les valeurs du ax_true_client_ip ou ax_resolved_client_ip dimensions. Pour en savoir plus, consultez la documentation de référence des métriques, dimensions et filtres Analytics.

À propos des masques d'adresses IP avec la notation CIDR

La notation CIDR (Classless Inter-Domain Routing) est un moyen d'indiquer une plage d'adresses IP au moyen de masques. Elle s'applique à la fois aux adresses IPv4 et IPv6. Voici comment cela fonctionne. Pour faire simple, nous utiliserons le protocole IPv4.

Les adresses IP sont des groupes de nombres séparés par des points. En notation binaire, chaque groupe est un nombre spécifique de bits (8 pour IPv4 et 16 pour IPv6). L'adresse IPv4 198.51.100.1 équivaut à ceci en notation binaire :

11000110.00110011.01100100.00000001

4 groupes de 8 bits, soit 32 bits au total. Avec CIDR, vous pouvez indiquer une plage en ajoutant un /nombre (de 1 à 32) à l'adresse IP, comme ceci :

198.51.100.1/24

Dans ce cas, 24 est le nombre que vous utiliseriez pour la valeur de l'attribut mask dans cette règle.

Cette notation signifie "Conserver les 24 premiers bits, les bits restants peuvent avoir n'importe quelle valeur comprise entre 0 et 255". Exemple :

Notez que le masque est appliqué à la fin du groupe 3. Cela facilite l'opération de création du masque suivant : 198.51.100*. Dans la plupart des cas, l'utilisation de multiples de 8 (IPv4) et de 16 (IPv6) vous donnera l'étendue de masque souhaitée :

IPv4 : 8, 16, 24, 32

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

Toutefois, vous pouvez appliquer d'autres nombres pour un contrôle plus précis, ce qui nécessite un peu de calcul binaire. Voici un exemple utilisant un masque de 30, comme dans 198.51.100.1/30, le dernier 1 équivalant à 00000001 en binaire :

Dans cet exemple, avec la configuration définie sur <SourceAddress mask="30">198.51.100.1</SourceAddress>, les adresses IP suivantes seraient autorisées (ou refusées, en fonction de vos règles) :

• 198.51.100.0
• 198.51.100.1
• 198.51.100.2
• 198.51.100.3

Documentation de référence des éléments

La documentation de référence des éléments décrit les éléments et les attributs de la règle AccessControl.

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

Attributs <AccessControl>

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

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>

Élément <IgnoreTrueClientIPHeader>

Lorsque cette règle est définie sur "true", la règle ignore l'en-tête True-Client-IP et évalue les adresses IP dans l'en-tête X-Forwarded-For, en suivant le comportement de l'évaluation X-Forwarded-For. que vous avez configuré.

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

Élément <IPRules>

Élément parent contenant les règles qui autorisent ou refusent les adresses IP. L'attribut noRuleMatchAction vous permet de définir comment gérer toutes les adresses IP non couvertes par vos règles de correspondance.

<IPRules noRuleMatchAction = "ALLOW">

Attributs

Élément <IPRules>/<MatchRule>

Action à effectuer (autoriser ou refuser l'accès) si l'adresse IP correspond aux adresses sources que vous avez définies.

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

Attributs

Élément <IPRules>/<MatchRule>/<SourceAddress>

Plage d'adresses IP d'un client.

Valeur valide : adresse IP valide (format décimal à point). Pour un comportement générique, utilisez l'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>

Comme indiqué dans l'exemple précédent, l'élément SourceAddress accepte également les modèles de message pour l'attribut ou l'adresse IP mask, ce qui signifie que vous pouvez définir les valeurs à l'aide des variables actuellement disponibles dans le flux du proxy d'API.

Par exemple, vous pouvez stocker une adresse IP dans un mappage clés-valeurs (KVM) et utiliser la règle KeyValueMapOperations pour récupérer l'adresse IP et l'attribuer à une variable (telle que kvm.ip.value). Vous pouvez ensuite utiliser cette variable comme adresse IP :

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

Définir un masque et/ou une adresse IP avec une variable vous permet de modifier les valeurs au moment de l'exécution sans avoir à modifier et redéployer votre proxy d'API.

Attributs

Élément <ValidateBasedOn>

Lorsque l'en-tête HTTP X-Forwarded-For contient plusieurs adresses IP, utilisez cet élément ValidateBasedOn pour contrôler les adresses IP à évaluer.

Utilisez cette approche pour évaluer une adresse IP uniquement si vous êtes certain de la validité des adresses IP que vous souhaitez évaluer. Par exemple, si vous choisissez d'évaluer toutes les adresses IP dans l'en-tête X-Forwarded-For, vous devez pouvoir approuver leur validité et/ou configurer des règles DENY ou ALLOW complètes pour autoriser uniquement les adresses IP approuvées à appeler votre proxy d'API.

L'adresse IP la plus à gauche de l'en-tête appartient au client et la plus à droite est celle du serveur qui a transféré la requête au service en cours. La plus à droite, ou dernière adresse IP, est l'adresse Edge reçue de la dernière poignée de main TCP externe.

La valeur que vous saisissez dans cet élément vous permet de déterminer si vous souhaitez vérifier toutes les adresses IP de l'en-tête (par défaut), uniquement la première, ou uniquement la dernière.

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

Schémas

Chaque type de règle est défini par un schéma XML (.xsd). À titre indicatif, les schémas de règles sont disponibles sur GitHub.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur qui sont renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Variables de panne

Ces variables sont définies lorsqu'une erreur d'exécution se produit. Pour plus d'informations, consultez la section Variables spécifiques aux erreurs liées aux règles.

Exemple de réponse aux pannes

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

Exemple de règle de défaillance

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