Règle AccessControl

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Quoi ?

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

Cette règle est une règle standard qui peut être déployée sur n'importe quel type d'environnement. Pour en savoir plus sur les types de règles et la disponibilité avec chaque type d'environnement, consultez la section Types de règles.

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.

Vous pouvez également envisager d'utiliser Google Cloud Armor avec Apigee comme moyen sécurisé de sécuriser vos API.

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.

Apigee renseigne automatiquement l'en-tête X-Forwarded-For avec l'adresse IP reçue du dernier handshake TCP externe (tel que l'adresse IP ou le routeur du client). 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 ?

Dimensions de X-Forwarded-For d'Apigee Analytics

Apigee Analytics écrit la valeur de l'en-tête X-Forwarded-For dans la dimension x_forwarded_for_ip. Pour déterminer l'adresse IP du client qui a effectué la requête sur Apigee, utilisez les valeurs de la dimension ax_resolved_client_ip, mais excluez ax_true_client_ip, qui n'est pas compatible avec la stratégie AccessControl Consultez la documentation de référence sur les métriques, les dimensions et les filtres d'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 utiliser 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">

Élément <ClientIPVariable>

Spécifie une variable de flux contenant une adresse IP que la règle confronte aux règles IP. Si la variable de flux ne contient pas d'adresse IP valide (ipv4 ou ipv6), la règle renvoie une erreur.

Supposons que la variable de flux est définie sur 12.31.34.52. Dans l'exemple suivant, l'accès est refusé. Si la variable est définie sur 10.11.12.13, l'accès est accordé.

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

É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. L'adresse la plus à droite, ou dernière adresse IP, est l'adresse Apigee reçue du dernier handshake 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 renvoyés et les variables d'erreur définies par Apigee lorsque cette règle 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 d'erreur

{
   "fault":{
     "faultstring":"Access Denied for client ip : 52.211.243.3"
      "detail":{
         "errorcode":"steps.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>