Règle AccessControl

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

Consultez la documentation d'Apigee Edge.

Événement

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. Tous les utilisateurs n'ont pas besoin de connaître les types de règles et d'environnements. 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.

Remarque : La vidéo suivante montre l'éditeur de proxy classique dans l'interface utilisateur d'Apigee. Apigee intègre une nouvelle version de l'éditeur de proxy, dont la conception est différente de celle de la version classique présentée dans la vidéo.

Vidéo : Regardez une courte vidéo pour découvrir comment autoriser ou 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.

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.

Refuser 198.51.100.1

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

Refuser toutes les requêtes provenant de l'adresse cliente : 198.51.100.1

Autoriser les requêtes provenant de toute autre adresse cliente.

Refuser l'utilisation de variables

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

Supposons que vous utilisiez un mappage clés-valeurs (KVM) pour stocker des valeurs de masque et des adresses IP. Il s'agit d'une approche pratique pour modifier les adresses IP et de masque pendant l'exécution, sans avoir à mettre à jour et à redéployer votre proxy d'API. Utilisez la règle KeyValueMapOperations pour récupérer les variables contenant les valeurs de kvm.mask.value et kvm.ip.value (en supposant que vous ayez nommé les variables dans votre règle KVM contenant les valeurs de masque et les valeurs IP de votre KVM). Si les valeurs récupérées étaient 24 pour le masque et 198.51.100.1 pour l'adresse IP, la règle AccessControl refuse toutes les requêtes provenant de : 198.51.100.*

Toutes les autres adresses clientes sont autorisées.

Refuser 198.51.100.*

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

Refuser toutes les requêtes en provenance de l'adresse client : 198.51.100.*

Autoriser les requêtes provenant de toute autre adresse cliente.

198.51.*.*

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

Refuser toutes les requêtes en provenance de l'adresse cliente : 198.51.*.*

Autoriser les requêtes provenant de toute autre adresse cliente.

Refuser 198.51.100.*, autoriser 192.0.2.1

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

Refuser toutes les requêtes en provenance de l'adresse cliente : 198.51.100.*, mais autoriser 192.0.2.1.

Autoriser les requêtes provenant de toute autre adresse cliente.

Autoriser 198.51.*.*

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

Autoriser toutes les requêtes provenant de l'adresse : 198.51.*.*

Refuser les demandes provenant d'une autre adresse cliente.

Autoriser plusieurs adresses IP

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

Autoriser les demandes provenant d'adresses clientes : 198.51.100.* 192.0.2.* 203.0.113.*

Refuser toutes les autres adresses.

Refuser plusieurs adresses IP

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

Refuser les demandes provenant d'adresses clientes : 198.51.100 * 192.0.2.* 203.0.113.*

Autoriser toutes les autres adresses.

Autoriser plusieurs adresses IP, refuser plusieurs adresses IP

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

Allow (Autoriser)

Refuser un sous-ensemble de la liste d'autorisation : 198.51.100.* 192.0.2.* 203.0.113.*

---

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

Pour Apigee hybrid, nous vous recommandons de configurer un équilibreur de charge devant votre cluster Kubernetes. L'équilibreur de charge peut être dédié à la couche 7 (L7, pour le trafic HTTP) ou à la couche 4 (L4, pour le trafic TCP). Les équilibreurs de charge L7 peuvent ajouter l'adresse IP source du client à l'en-tête X-Forwarded-For (XFF). Les équilibreurs de charge L4 doivent être configurés pour utiliser le protocole PROXY. Consultez le manuel de votre équilibreur de charge pour savoir comment activer la compatibilité avec le protocole PROXY. Pour activer le protocole PROXY sur l'entrée, consultez la section Source IP address of the original client dans la documentation d'Istio.

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

En-tête "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 :

Conservez ces valeurs telles quelles	Valeurs possibles pour le dernier groupe
198.51.100.	0 - 255

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 :

Conservez ces valeurs telles quelles	Valeurs possibles
11000110.00110011.01100100.000000 (30 premiers bits)	00000000, 00000001, 00000010, ou 00000011
198.51.100.	0, 1, 2, ou 3

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>

Par défaut	N/A
Présence	Facultatif
Type	Variable de flux

Élément <IgnoreTrueClientIPHeader>

Remarque : Cet élément n'est pas disponible pour le moment et n'a aucun effet, qu'il soit activé ou non.

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

Par défaut	N/A
Présence	Facultatif
Type	N/A

Attributs

Attribut	Description	Type	Par défaut	Présence
noRuleMatchAction	Action à effectuer (autoriser ou refuser l'accès) si la règle de correspondance spécifiée n'est pas résolue (sans correspondance). Valeur valide : AUTORISER ou REFUSER	Chaîne	ALLOW (Autoriser)	Valeur

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

Par défaut	N/A
Présence	Facultatif
Type	N/A

Attributs

Attribut	Description	Type	Par défaut	Présence
action	Action à effectuer (autoriser ou refuser l'accès) si la règle de correspondance spécifiée n'est pas résolue (sans correspondance). Valeur valide : AUTORISER ou REFUSER	Chaîne	ALLOW (Autoriser)	Valeur

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

Par défaut	N/A
Présence	Facultatif
Type	Chaîne (adresse IP unique uniquement)

Attributs

Attribut	Description	Type	Par défaut	Présence
masquer	L'attribut mask permet d'indiquer la plage d'adresses IP à autoriser ou à refuser. Le masque équivaut à utiliser le format CIDR (Classless Inter-Domain Routing). Exemple : <SourceAddress mask="24">198.51.100.1</SourceAddress> est équivalent à la notation CIDR suivante : 198.51.100.1/24 Valeurs correctes : IPv4 : de 1 à 32 IPv6 : de 1 à 128 Une valeur de zéro (0) n'est valide que pour l'adresse IP 0.0.0.0, qui est improbable. Définir le masque avec une variable L'attribut mask est également compatible avec les modèles de messages, ce qui signifie que vous pouvez définir la valeur avec une variable actuellement disponible dans le flux de proxy d'API. Par exemple, vous pouvez stocker une valeur de masque dans un KVM, et utiliser la règle KeyValueMapOperations pour récupérer le masque et l'attribuer à une variable. Pour définir le masque IP avec la variable, utilisez le format suivant, en supposant que la variable s'appelle kvm.mask.value : mask="{kvm.mask.value}"	Entier	ND	Valeur

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

Par défaut	X_FORWARDED_FOR_ALL_IP
Présence	Facultatif
Valeurs valides	X_FORWARDED_FOR_ALL_IP (par défaut) X_FORWARDED_FOR_FIRST_IP X_FORWARDED_FOR_LAST_IP

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.

Code d'erreur	État HTTP	Cause	Corriger
accesscontrol.IPDeniedAccess	403	L'adresse IP du client ou une adresse IP transmise dans la requête API correspond à une adresse IP spécifiée dans l'élément <SourceAddress> de l'élément <MatchRule> de la règle de contrôle d'accès AccessControl, et l'attribut action de l'élément <MatchRule> est défini sur DENY.
accesscontrol.InvalidIPAddressInVariable	500	La variable de flux dans <ClientIPVariable> contient une adresse IP non valide.

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.

Variables	Lieu	Exemple
fault.name="fault_name"	fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur.	fault.name Matches "IPDeniedAccess"
acl.policy_name.failed	policy_name est le nom spécifié par l'utilisateur pour la règle qui a généré l'erreur.	acl.AC-AllowAccess.failed = true

Exemple de réponse d'erreur

Remarque : Pour le traitement des erreurs, la bonne pratique consiste à intercepter la partie errorcode de la réponse d'erreur. Ne vous fiez pas au texte dans faultstring, car il pourrait changer.

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