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.

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

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'Ingress, 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 :

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.

Avertissement : Si vous souhaitez utiliser l'en-tête True-Client-IP, assurez-vous que vous que cette adresse provient d'une source de confiance. Si vous ne pouvez pas garantir que l'en-tête contient une adresse de confiance, définissez <IgnoreTrueClientIPHeader>true</IgnoreTrueClientIPHeader> afin que la règle ignore la règle True-Client-IP et évalue les adresses IP de l'en-tête X-Forwarded-For.

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 :

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
Presence	Facultatif
Type	Variable de flux

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

Par défaut	false
Presence	Facultatif
Type	Booléen

É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
Presence	Facultatif
Type	N/A

Attributs

Attribut	Description	Type	Par défaut	Presence
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	AUTORISER	Obligatoire

É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
Presence	Facultatif
Type	N/A

Attributs

Attribut	Description	Type	Par défaut	Presence
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	AUTORISER	Obligatoire

É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
Presence	Facultatif
Type	Chaîne (adresse IP unique uniquement)

Attributs

Attribut	Description	Type	Par défaut	Presence
mask	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	N/A	Obligatoire

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause	Fix
accesscontrol.IPDeniedAccess	403	The client IP address, or an IP address passed in the API request, matches an IP address specified in the <SourceAddress> element within the <MatchRule> element of the Access Control Policy, and the action attribute of the <MatchRule> element is set to DENY.
accesscontrol.InvalidIPAddressInVariable	500	The flow variable in <ClientIPVariable> contains an invalid IP address.

Fault variables

These variables are set when a runtime error occurs. For more information, see Variables specific to policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "IPDeniedAccess"
acl.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	acl.AC-AllowAccess.failed = true

Example fault response

Note: For fault handling, the best practice is to trap the errorcode part of the fault response. Do not rely on the text in the faultstring because it could change.

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

Example fault rule

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