Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di
Apigee Edge.
Cosa
Il criterio AccessControl ti consente di consentire o negare l'accesso alle tue API in base a indirizzi IP specifici.
Questo criterio è un criterio standard e può essere implementato in qualsiasi tipo di ambiente. Per informazioni sui tipi di criteri e sulla loro disponibilità in base a ciascun tipo di ambiente, consulta Tipi di criteri.
Video: guarda un breve video per scoprire di più su come consentire o negare l'accesso alle tue API in base a indirizzi IP specifici.
Sebbene tu possa applicare questo criterio in qualsiasi punto del flusso del proxy API, molto probabilmente vorrai controllare gli indirizzi IP all'inizio del flusso ( Request / ProxyEndpoint / PreFlow), anche prima dell'autenticazione o del controllo delle quote.
Ti consigliamo inoltre di utilizzare Google Cloud Armor con Apigee come metodo alternativo per proteggere le tue API.
Esempi
I valori della maschera nei seguenti esempi di IPv4 identificano quale dei quattro ottetti (8, 16, 24, 32
bit) viene preso in considerazione dalla regola di corrispondenza quando consente o nega l'accesso. Il valore predefinito è 32. Per ulteriori informazioni, consulta l'attributo mask nella sezione di riferimento Element.
Rifiuta 198.51.100.1
<AccessControl name="ACL">
<IPRules noRuleMatchAction = "ALLOW">
<MatchRule action = "DENY">
<SourceAddress mask="32">198.51.100.1</SourceAddress>
</MatchRule>
</IPRules>
</AccessControl>Rifiuta tutte le richieste dall'indirizzo del client: 198.51.100.1
Consenti le richieste da qualsiasi altro indirizzo client.
Negare 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>Supponiamo che tu stia utilizzando una mappa chiave/valore (KVM) per memorizzare i valori per il mascheramento e gli IP.
Si tratta di un approccio pratico per modificare gli IP e il mascheramento durante l'esecuzione senza dover aggiornare
e rieseguire il deployment del proxy API. Puoi utilizzare il criterio KeyValueMapOperations per recuperare
le variabili contenenti i valori di kvm.mask.value e
kvm.ip.value (supponendo che siano questi i nomi delle variabili nel criterio KVM
che contengono i valori della maschera e dell'IP del KVM).
Se i valori che hai recuperato fossero 24 per la maschera e 198.51.100.1
per l'indirizzo IP, il criterio AccessControl rifiuterebbe tutte le richieste provenienti da: 198.51.100.*
Tutti gli altri indirizzi client saranno consentiti.
Rifiuta 198.51.100.*
<AccessControl name="ACL">
<IPRules noRuleMatchAction = "ALLOW">
<MatchRule action = "DENY">
<SourceAddress mask="24">198.51.100.1</SourceAddress>
</MatchRule>
</IPRules>
</AccessControl>Rifiuta 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>Rifiuta tutte le richieste dall'indirizzo del client: 198.51.*.*
Consenti le richieste da qualsiasi altro indirizzo client.
Rifiuta 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>Rifiuta 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 provenienti 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 le richieste dagli indirizzi client: 198.51.100.* 192.0.2.* 203.0.113.*
Nega tutti gli altri indirizzi.
Negare 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>Rifiuta le 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 dell'elenco consentiti: 198.51.100.* 192.0.2.* 203.0.113.*
Note sull'utilizzo
Oltre a proteggere le tue API da IP dannosi, il criterio AccessControl ti consente anche di controllare l'accesso degli IP legittimi. Ad esempio, se vuoi che solo i computer sotto il controllo della tua azienda accedano alle API esposte nell'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 VPN.
La configurazione e l'esecuzione di un criterio AccessControl comportano quanto segue:
- Definisci un insieme di regole di corrispondenza con una delle due azioni (ALLOW o DENY) associate a ciascuna.
- Per ogni regola di corrispondenza, specifica l'indirizzo IP (elemento SourceAddress).
- Consulta la sezione In che modo il criterio sceglie l'indirizzo IP da valutare per determinare gli indirizzi IP nel messaggio per i quali stai configurando le regole da gestire.
- Configura una maschera per ogni indirizzo IP. Consenti o neghi l'accesso in base a un valore della maschera sull'indirizzo IP. Consulta Informazioni sul mascheramento IP con notazione CIDR.
- Specifica l'ordine in cui le regole vengono testate.
- Tutte le regole di corrispondenza vengono eseguite nell'ordine specificato. Quando una regola trova una corrispondenza, viene eseguita l'azione corrispondente e le regole di corrispondenza successive vengono ignorate.
- Se la stessa regola è configurata sia con azioni ALLOW che DENY, viene attivata la regola definita per prima nell'ordine 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 che vuoi valutare.
Di seguito è riportata la logica utilizzata dal criterio AccessControl per decidere quale indirizzo IP valutare:
1. Intestazione True-Client-IP
Il criterio controlla innanzitutto 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
<IgnoreTrueClientIPHeader> 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 del client o
del router). Se nell'intestazione sono presenti più indirizzi IP, è probabile che questi indirizzi rappresentino la catena di server che ha elaborato una richiesta. Tuttavia, l'elenco di indirizzi potrebbe anche contenere un indirizzo IP contraffatto. In che modo il criterio sa 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 del client che ha effettuato
la richiesta ad Apigee, utilizza i valori nella
dimensione ax_resolved_client_ip, ma escludi ax_true_client_ip,
che non è supportato dal criterio AccessControl. Consulta
Riferimento per metriche, dimensioni e filtri di analisi.
Informazioni sul mascheramento IP con 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 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 il seguente aspetto in binario:
11000110.00110011.01100100.00000001
Si tratta di 4 gruppi di 8 bit, ovvero 32 bit totali. Con il CIDR, puoi indicare un intervallo aggiungendo un /numero (1-32) all'indirizzo IP, ad esempio:
198.51.100.1/24
In questo caso, 24 è il numero da utilizzare per il valore dell'attributo mask in questo criterio.
Questa notazione significa "Mantieni invariati i primi 24 bit, mentre i bit rimanenti possono assumere qualsiasi valore compreso tra 0 e 255". Ad esempio:
| Mantieni questi dati esattamente come sono | Valori possibili per l'ultimo gruppo |
|---|---|
| 198.51.100. | 0 - 255 |
Tieni presente che la maschera viene applicata alla fine del terzo gruppo. In questo modo, le cose sono belle e ordinate, in quanto viene creata una maschera come 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, che prevede un piccolo calcolo in base al sistema numerico binario. Ecco un esempio che utilizza una maschera di 30, come in 198.51.100.1/30, dove l'ultimo 1 è 00000001 in binario:
| Mantieni questi dati esattamente come sono | 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>, i seguenti IP sarebbero consentiti (o vietati, a seconda delle regole):
- 198.51.100.0
- 198.51.100.1
- 198.51.100.2
- 198.51.100.3
Riferimento elemento
Il riferimento all'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>Attributi <AccessControl>
<AccessControl async="false" continueOnError="false" enabled="true" name="Access-Control-1">
Elemento <ClientIPVariable>
Specifica una variabile di flusso contenente un indirizzo IP che il criterio controlla rispetto alle regole IP. Se la variabile di flusso non contiene un indirizzo IP valido (IPv4 o IPv6), il criterio genera un errore.
Supponiamo che la variabile di flusso sia impostata su 12.31.34.52. Nel seguente esempio,
l'accesso viene negato. Se la variabile è impostata su 10.11.12.13, l'accesso viene concesso.
<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/D |
|---|---|
| Presenza | Facoltativo |
| Tipo | Variabile di flusso |
Elemento <IgnoreTrueClientIPHeader>
Se imposti questo valore su true, 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 |
Elemento <IPRules>
L'elemento principale contenente le regole che consentono o negano gli indirizzi IP. L'attributo noRuleMatchAction consente di definire la modalità di gestione degli indirizzi IP non coperti dalle regole di corrispondenza.
<IPRules noRuleMatchAction = "ALLOW">
| Predefinito | N/D |
|---|---|
| Presenza | Facoltativo |
| Tipo | N/D |
Attributi
| Attributo | Descrizione | Tipo | Predefinito | Presenza |
|---|---|---|---|---|
| noRuleMatchAction |
L'azione da eseguire (consenti o nega l'accesso) se la regola di corrispondenza specificata non viene risolta
(non corrispondente).
Valore valido: ALLOW o DENY
|
Stringa | CONSENTI | Obbligatorio |
Elemento <IPRules>/<MatchRule>
L'azione da intraprendere (consentire o negare l'accesso) se l'indirizzo IP corrisponde agli indirizzi SourceAddress che hai definito.
<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/D |
|---|---|
| Presenza | Facoltativo |
| Tipo | N/D |
Attributi
| Attributo | Descrizione | Tipo | Predefinito | Presenza |
|---|---|---|---|---|
| azione |
L'azione da eseguire (consenti o nega l'accesso) se la regola di corrispondenza specificata non viene risolta (non corrisponde). Valore valido: ALLOW o DENY |
Stringa | CONSENTI | Obbligatorio |
Elemento <IPRules>/<MatchRule>/<SourceAddress>
L'intervallo di indirizzi IP di un client.
Valore valido: indirizzo IP valido (notazione decimale puntata). Per il comportamento dei 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 mask o l'indirizzo IP, il che significa che puoi impostare i valori utilizzando le variabili attualmente disponibili nel flusso dell'proxy API.
Ad esempio, puoi memorizzare un indirizzo IP in una mappa di valori chiave (KVM) e utilizzare il
criterio KeyValueMapOperations per recuperare l'indirizzo IP e assegnarlo a una variabile (ad esempio
kvm.ip.value). Puoi quindi utilizzare questa variabile per l'indirizzo IP:
<SourceAddress mask="24">{kvm.ip.value}</SourceAddress>
L'impostazione della maschera e/o dell'indirizzo IP con una variabile ti offre la flessibilità di modificare i valori in fase di esecuzione senza dover modificare e rieseguire il deployment del proxy API.
| Predefinito | N/D |
|---|---|
| Presenza | Facoltativo |
| Tipo | Stringa (solo indirizzo IP singolo) |
Attributi
| Attributo | Descrizione | Tipo | Predefinito | Presenza |
|---|---|---|---|---|
| maschera |
L'attributo
è equivalente 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 l'IP 0.0.0.0, quindi non è pratico. Impostare la maschera con una variabile L'attributo
|
Numero intero | N/D | Obbligatorio |
Elemento <ValidateBasedOn>
Quando 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 hai la certezza della loro validità. Ad esempio, se scegli di valutare tutti gli indirizzi IP nell'intestazione X-Forwarded-For, devi essere in grado di garantire la validità di questi indirizzi e/o configurare regole DENY o ALLOW complete per consentire solo agli indirizzi IP attendibili di chiamare il tuo proxy API.
L'indirizzo IP più a sinistra nell'intestazione appartiene al client, mentre quello più a destra è il server che ha inoltrato la richiesta al servizio corrente. L'indirizzo IP più a destra, ovvero l'ultimo, è quello che Apigee ha ricevuto dall'ultimo handshake TCP esterno.
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.
<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 |
|
Schemi
Ogni tipo di criterio è definito da uno schema XML (.xsd). Come riferimento, su GitHub sono disponibili gli schemi di criteri.
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. |
build |
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>