Criterio di AccessControl

Stai visualizzando la documentazione di Apigee X.
Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Il criterio AccessControl consente di consentire o negare l'accesso alle API da parte di indirizzi IP specifici.

Video: guarda un breve video per scoprire di più su come consentire o negare l'accesso alle tue API da indirizzi IP specifici.

Sebbene sia possibile collegare questo criterio in qualsiasi punto del flusso proxy dell'API, molto probabilmente vuoi controllare gli indirizzi IP all'inizio del flusso ( Richiesta / ProxyEndpoint / PreFlow), anche prima dell'autenticazione o del controllo della quota.

Esempi

I valori delle maschere nei seguenti esempi di IPv4 identificano quale dei quattro ottetti (8, 16, 24, 32 bit) la regola di corrispondenza prende in considerazione quando si consente o nega l'accesso. Il valore predefinito è 32. Per ulteriori informazioni, consulta l'attributo mask nel riferimento elemento.

Nega 198.51.100.1

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

Nega tutte le richieste dall'indirizzo client: 198.51.100.1

Consenti le richieste da qualsiasi altro indirizzo client.

Impedire l'utilizzo delle variabili

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

Supponi di utilizzare una mappa chiave-valore (KVM) per archiviare i valori per il mascheramento e gli indirizzi IP. Questo è un approccio pratico alla modifica degli IP e al mascheramento durante il runtime, senza dover aggiornare ed eseguire nuovamente il deployment del proxy API. Puoi utilizzare il criterio KeyValueMapOperations per recuperare le variabili contenenti i valori per kvm.mask.value e kvm.ip.value (supponendo che siano state denominate le variabili nel criterio KVM che contengono i valori della maschera e i valori IP della KVM). Se i valori recuperati sono stati 24 per la maschera e 198.51.100.1 per l'indirizzo IP, il criterio AccessControl negherebbe tutte le richieste da 198.51.100.*

Tutti gli altri indirizzi client sarebbero consentiti.

Nega 198.51.100.*

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

Nega tutte le richieste dall'indirizzo client: 198.51.100.*

Consenti le richieste da qualsiasi altro indirizzo client.

198,51.*

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

Nega tutte le richieste dall'indirizzo client: 198.51.*.*

Consenti le richieste da qualsiasi altro indirizzo client.

Nega 198.51.100.*, consenti 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>

Nega tutte le richieste dall'indirizzo client: 198.51.100.*, ma consenti 192.0.2.1.

Consenti le richieste da qualsiasi altro indirizzo client.

Consenti 198.51.*.*

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

Consenti tutte le richieste dall'indirizzo: 198.51.*.*

Rifiutare le richieste da qualsiasi altro indirizzo client.

Consenti più 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>

Consenti richieste da indirizzi client: 198.51.100.* 192.0.2.* 203.0.113.*

Nega tutti gli altri indirizzi.

Rifiuta più 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>

Nega richieste dagli indirizzi client: 198.51.100.* 192.0.2.* 203.0.113.*

Consenti tutti gli altri indirizzi.

Consenti più IP, nega più 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>

Consenti: 198.51.*.* 192,0.* 203,0.*

Nega un sottoinsieme della lista consentita: 198.51.100.* 192.0.2.* 203.0.113.*

Note sull'utilizzo

Oltre a proteggere le tue API dagli IP dannosi, il criterio AccessControl ti consente anche di controllare gli accessi IP legittimi. Ad esempio, se vuoi che i computer sotto il controllo della tua azienda accedano alle API esposte nel tuo ambiente di test, puoi consentire l'intervallo di indirizzi IP per la tua rete interna. Gli sviluppatori che lavorano da casa possono accedere a queste API tramite la VPN.

La configurazione e l'esecuzione di un criterio AccessControl implica quanto segue:

  • Definisci un insieme di regole di corrispondenza a cui è associata una delle due azioni (ALLOW o DENY) di appartenenza.
  • Per ogni regola di corrispondenza, specifica l'indirizzo IP (elemento SourceAddress).
  • Specifica l'ordine di test delle regole.
  • Tutte le regole di corrispondenza vengono eseguite nell'ordine specificato. Quando una regola corrisponde, viene eseguita l'azione corrispondente e vengono ignorate le regole di corrispondenza seguenti.
    • Se la stessa regola è configurata con entrambe le azioni ALLOW e DENY, la regola definita per prima nell'ordine viene attivata e la regola successiva (con l'altra azione) viene ignorata.

In che modo il criterio sceglie l'indirizzo IP da valutare

Gli indirizzi IP possono provenire da varie origini in una richiesta. Ad esempio, l'intestazione del messaggio True-Client-IP potrebbe contenere un indirizzo IP e l'intestazione X-Forwarded-For potrebbe contenere uno o più indirizzi IP. Questa sezione descrive come configurare il criterio AccessControl per valutare gli indirizzi IP esatti da valutare.

Di seguito è riportata la logica utilizzata dal criterio AccessControl per decidere quale indirizzo IP valutare:

1. Intestazione True-Client-IP

Innanzitutto, il criterio verifica la presenza di un indirizzo IP nell'intestazione True-Client-IP. Se l'intestazione contiene un indirizzo IP valido, il criterio lo valuta.

2. Intestazione X-Forwarded-For

Se non è presente un'intestazione True-Client-IP o se hai impostato l'elemento <IgnoreTrueIPIPHeader> su true, il criterio valuta gli indirizzi IP nell'intestazione X-Forwarded-For.

Apigee compila automaticamente l'intestazione X-Forwarded-For con l'indirizzo IP ricevuto dall'ultimo handshake TCP esterno (ad esempio, l'IP client o il router). Se nell'intestazione sono presenti più indirizzi IP, è probabile che questi siano la catena di server che hanno elaborato una richiesta. Tuttavia, l'elenco di indirizzi potrebbe contenere anche un indirizzo IP oggetto di spoofing. Quindi, come fa il criterio a sapere quali indirizzi valutare?

Dimensioni X-Forwarded-For in Apigee Analytics

Apigee Analytics scrive il valore dell'intestazione X-Forwarded-For nella dimensione x_forwarded_for_ip. Per determinare l'IP client che ha effettuato la richiesta ad Apigee, utilizza i valori nelle dimensioni ax_true_client_ip o ax_resolved_client_ip. Per ulteriori informazioni, consulta Riferimento per le metriche, le dimensioni e i filtri di Analytics.

Informazioni sul mascheramento IP con la notazione CIDR

La notazione CIDR (Classless Inter-Domain Routing) è un modo per indicare un intervallo di indirizzi IP tramite mascheramento. Si applica sia a IPv4 che a IPv6. Ecco come funziona. Per maggiore semplicità, utilizzeremo IPv4 nei nostri esempi.

Gli indirizzi IP sono gruppi di numeri separati da punti. In termini binari, ogni gruppo è un numero specifico di bit (8 per IPv4 e 16 per IPv6). L'indirizzo IPv4 198.51.100.1 ha un aspetto simile al seguente nel programma binario:

11000110.00110011.01100100.00000001

Sono 4 gruppi di 8 bit o 32 bit in totale. Con CIDR, puoi indicare un intervallo aggiungendo /number (1-32) all'indirizzo IP, come segue:

198.51.100.1/24

In questo caso, il 24 è il numero che useresti per il valore dell'attributo mask in questo criterio.

Questa notazione significa "Mantieni i primi 24 bit esattamente come sono, i bit rimanenti possono essere di qualsiasi valore compreso tra 0 e 255". Ad esempio:

Mantieni queste impostazioni così com'è Valori possibili per l'ultimo gruppo
198.51.100. 0 - 255

Nota che la mascherina si verifica alla fine del gruppo tre. In questo modo le cose sono belle e ordinate, quindi puoi creare una maschera simile a questa: 198.51.100.*. Nella maggior parte dei casi, l'utilizzo di multipli di 8 (IPv4) e 16 (IPv6) ti fornirà il livello di mascheramento che preferisci:

IPv4: 8, 16, 24, 32

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

Tuttavia, puoi utilizzare altri numeri per un controllo più granulare, il che comporta un piccolo calcolo binario. Ecco un esempio che utilizza una maschera di 30, come in 198.51.100.1/30, dove l'ultimo 1 è 00000001 in codice binario:

Mantieni queste impostazioni così com'è Valori possibili
11000110.00110011.01100100.000000 (primi 30 bit) 00000000, 00000001, 00000010 o 00000011
198.51.100. 0, 1, 2 o 3

In questo esempio, con la configurazione impostata su <SourceAddress mask="30">198.51.100.1</SourceAddress>, sono consentiti (o rifiutati a seconda delle regole) i seguenti IP:

  • 198.51.100.0
  • 198.51.100.1
  • 198.51.100.2
  • 198.51.100.3

Riferimento elemento

Il riferimento elemento descrive gli elementi e gli attributi del criterio 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>

<AccessControl> attributi

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

<ClientIPVariable> elemento

Specifica una variabile di flusso contenente un indirizzo IP che il criterio esegue il confronto con le regole IP. Se la variabile di flusso non contiene un indirizzo IP valido (ipv4 o ipv6), il criterio genera un errore.

Supponi che la variabile di flusso sia impostata su 12.31.34.52. Nell'esempio seguente, l'accesso viene negato. Se la variabile è impostata su 10.11.12.13, viene concesso l'accesso. 

<AccessControl name='ACL'>
   <ClientIPVariable>FLOW_VARIABLE</ClientIPVariable>
   <IPRules noRuleMatchAction = 'DENY'>
     <MatchRule action = 'ALLOW'>
       <SourceAddress mask='32'>10.11.12.13</SourceAddress>
     </MatchRule>
   </IPRules>
</AccessControl>
Predefinito N/A
Presenza Facoltativo
Tipo Variabile di flusso

<IgnoraTrueClientIPHeader>

Se questo criterio viene impostato su vero, il criterio ignora l'intestazione True-Client-IP e valuta gli indirizzi IP nell'intestazione X-Forwarded-For, seguendo il comportamento di valutazione X-Forwarded-For che hai configurato.

<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
    <DisplayName>Access Control-1</DisplayName>
    <IgnoreTrueClientIPHeader>true</IgnoreTrueClientIPHeader>
    ...
</AccessControl>
Predefinito falso
Presenza Facoltativo
Tipo Booleano

<IPRule> elemento

L'elemento principale contenente le regole che consentono o negano gli indirizzi IP. L'attributo noRuleMatchAction consente di definire come gestire gli indirizzi IP che non sono coperti dalle regole di corrispondenza.

<IPRules noRuleMatchAction = "ALLOW">
Predefinito N/A
Presenza Facoltativo
Tipo N/A

Attributi

Attributo Descrizione Tipo Predefinito Presenza
noRuleMatchAction
L'azione da eseguire (consentire o negare l'accesso) se la regola di corrispondenza specificata non è stata risolta (senza corrispondenza).
Valore valido: ALLOW o DENY
Stringa CONSENTI Obbligatorie

<IPRule>/<Regola Corrispondenza>

L'azione da intraprendere (consentire o negare l'accesso) se l'indirizzo IP corrisponde agli indirizzi Source da te definiti.

<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>
Predefinito N/A
Presenza Facoltativo
Tipo N/A

Attributi

Attributo Descrizione Tipo Predefinito Presenza
action

L'azione da eseguire (consentire o negare l'accesso) se la regola di corrispondenza specificata non è stata risolta (senza corrispondenza).

Valore valido: ALLOW o DENY

 Stringa CONSENTI Obbligatorie

<IPRules>/<MatchRule>/<SourceAddress> elemento

L'intervallo di indirizzi IP di un client.

Valore valido: indirizzo IP valido (notazione decimale puntata). Per il comportamento con caratteri jolly, utilizza l'attributo 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>

Come mostrato nell'esempio precedente, l'elemento SourceAddress supporta anche i modelli di messaggio per l'attributo o l'indirizzo IP mask, il che significa che puoi impostare i valori utilizzando variabili attualmente disponibili nel flusso proxy dell'API.

Ad esempio, puoi archiviare un indirizzo IP in una mappa delle coppie chiave-valore (KVM) e utilizzare il criterio KeyValueMapOperations per recuperare l'indirizzo IP e assegnarlo a una variabile (ad esempio kvm.ip.value). Puoi quindi utilizzare tale variabile per l'indirizzo IP:

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

L'impostazione di maschera e/o indirizzo IP con una variabile ti offre la flessibilità necessaria per modificare i valori in tempo di esecuzione senza dover modificare ed eseguire nuovamente il deployment del proxy API.

Predefinito N/A
Presenza Facoltativo
Tipo Stringa (solo indirizzo IP singolo)

Attributi

Attributo Descrizione Tipo Predefinito Presenza
mascherare

L'attributo mask è un modo per indicare l'intervallo di indirizzi IP da consentire o negare. Maschera equivale a utilizzare la notazione CIDR (Classless Inter-Domain Routing). Ad esempio:

<SourceAddress mask="24">198.51.100.1</SourceAddress>

equivale alla seguente notazione CIDR:

198.51.100.1/24

Valori validi:

IPv4: 1-32

IPv6: 1-128

Un valore pari a zero (0) è valido solo per IP 0.0.0.0, quindi impraticabile.

Impostare la maschera con una variabile

L'attributo mask supporta anche i modelli di messaggio, il che significa che puoi impostare il valore con una variabile attualmente disponibile nel flusso proxy dell'API. Ad esempio, puoi archiviare un valore per la maschera in una KVM e utilizzare il criterio KeyValueMapOperations per recuperare la maschera e assegnarla a una variabile. Per impostare la maschera IP con la variabile, utilizza il seguente formato, supponendo che la variabile sia denominata kvm.mask.value:

mask="{kvm.mask.value}"

 Numero intero N/A Obbligatorie

<ValidateBasedIn> elemento

Se l'intestazione HTTP X-Forwarded-For contiene più indirizzi IP, utilizza questo elemento ValidateBasedOn per controllare quali indirizzi IP vengono valutati.

Utilizza questo approccio per valutare gli indirizzi IP solo se sei sicuro della validità degli indirizzi IP che vuoi valutare. Ad esempio, se scegliete di valutare tutti gli indirizzi IP nell'intestazione X-Forwarded-For, dovete essere affidabili per la validità di tali indirizzi e/o configurare regole DENY o ALLOW complete per consentire solo agli IP attendibili di chiamare il vostro proxy API.

L'indirizzo IP più a sinistra nell'intestazione appartiene al client, mentre l'ultimo a destra è il server che ha inoltrato la richiesta al servizio attuale. L'indirizzo IP più a destra o l'ultimo è l'indirizzo ricevuto da Apigee dall'ultimo handshake esterno TCP.

Il valore inserito in questo elemento consente di determinare se controllare tutti gli indirizzi IP nell'intestazione (valore predefinito), solo il primo indirizzo IP o solo l'ultimo indirizzo IP.

<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>
Predefinito X_FORWARDED_FOR_ALL_IP
Presenza Facoltativo
Valori validi

X_FORWARDED_FOR_ALL_IP (valore predefinito)

X_FORWARDED_FOR_FIRST_IP

X_FORWARDED_FOR_LAST_IP

Schemi

Ogni tipo di criterio viene definito da uno schema XML (.xsd). A titolo di riferimento, sono disponibili schemi di criteri su GitHub.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Causa Correggi
accesscontrol.IPDeniedAccess 403 L'indirizzo IP del client o un indirizzo IP passato nella richiesta API, corrisponda a un indirizzo IP specificato nell'elemento <SourceAddress> in l'elemento <MatchRule> del criterio di controllo dell'accesso e l'attributo action del L'elemento <MatchRule> è impostato su DENY.
accesscontrol.InvalidIPAddressInVariable 500 La variabile di flusso in <ClientIPVariable> contiene un indirizzo IP non valido.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, consulta Voci specifiche per gli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. fault.name Matches "IPDeniedAccess"
acl.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. acl.AC-AllowAccess.failed = true

Esempio di risposta all'errore

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

Esempio di regola di errore

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