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 disponibilità con 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 da indirizzi IP specifici.
Anche se puoi collegare questa policy in qualsiasi punto del flusso del proxy API, è più probabile che tu voglia controllare gli indirizzi IP all'inizio del flusso ( Request / ProxyEndpoint / PreFlow), prima ancora dell'autenticazione o del controllo della quota.
Ti consigliamo anche di utilizzare Google Cloud Armor con Apigee come modo 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 nel riferimento agli elementi.
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 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 archiviare i valori per la maschera e gli indirizzi IP.
Si tratta di un approccio pratico per modificare gli IP e il mascheramento durante l'esecuzione senza dover aggiornare
e ridistribuire il proxy API. Puoi utilizzare il criterio KeyValueMapOperations per recuperare
le variabili contenenti i valori per kvm.mask.value e
kvm.ip.value (supponendo che tu abbia chiamato le variabili nel criterio KVM
che contengono i valori della maschera e dell'IP del tuo KVM).
Se i valori recuperati erano 24 per la maschera e 198.51.100.1
per l'indirizzo IP, il criterio AccessControl negherebbe tutte le richieste provenienti 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>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 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>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.*.*
Rifiuta 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 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>Nega 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>Allow: 198.51.*.* 192.0.*.* 203.0.*.*
Negare 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, la policy AccessControl ti consente anche di controllare l'accesso IP legittimo. Ad esempio, se vuoi che solo 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 utilizzando la VPN.
La configurazione e l'esecuzione di un criterio AccessControl prevede quanto segue:
- Definisci un insieme di regole di corrispondenza con una delle due azioni (CONSENTI o NEGA) associate a ciascuna.
- Per ogni regola di corrispondenza, specifica l'indirizzo IP (elemento SourceAddress).
- Consulta Come la policy sceglie quale indirizzo IP valutare per determinare quali indirizzi IP nel messaggio stai configurando per la gestione delle regole.
- Configura una maschera per ogni indirizzo IP. Consenti o neghi l'accesso in base a un valore di maschera sull'indirizzo IP. Consulta la sezione Informazioni sul mascheramento degli indirizzi IP con la notazione CIDR.
- Specifica l'ordine in cui vengono testate le regole.
- Tutte le regole di corrispondenza vengono eseguite nell'ordine specificato. Quando una regola corrisponde, viene eseguita l'azione corrispondente e le regole di corrispondenza successive vengono ignorate.
- Se la stessa regola è configurata con le azioni CONSENTI e NEGA, viene attivata la regola definita per prima nell'ordine e la regola successiva (con l'altra azione) viene ignorata.
Come la policy sceglie l'indirizzo IP da valutare
Gli indirizzi IP possono provenire da varie fonti in una richiesta. Ad esempio, l'intestazione
X-Forwarded-For può contenere uno o più indirizzi IP. Questa sezione
descrive come configurare il criterio AccessControl per valutare gli indirizzi IP esatti che vuoi che valuti.
Di seguito è riportata la logica utilizzata dal criterio AccessControl per decidere quale indirizzo IP valutare:
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, questi indirizzi
corrispondono probabilmente alla catena di server che hanno elaborato una richiesta. Tuttavia, l'elenco di indirizzi
potrebbe contenere anche un indirizzo IP contraffatto. Quindi, 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 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 è supportata con la policy AccessControl. Consulta
Riferimento per metriche, dimensioni e filtri di Analytics.
Informazioni sul mascheramento degli indirizzi 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 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 questo aspetto in formato binario:
11000110.00110011.01100100.00000001
Si tratta di 4 gruppi di 8 bit, per un totale di 32 bit. Con CIDR, puoi indicare un intervallo aggiungendo un /numero (1-32) all'indirizzo IP, in questo modo:
198.51.100.1/24
In questo caso, 24 è il numero che utilizzeresti per il valore dell'attributo mask in questo criterio.
Questa notazione significa: "Mantieni i primi 24 bit esattamente come sono, i bit rimanenti possono assumere qualsiasi valore da 0 a 255". Ad esempio:
| Mantieni questi elementi esattamente così come sono | Valori possibili per l'ultimo gruppo |
|---|---|
| 198.51.100. | 0 - 255 |
Nota che la maschera viene applicata alla fine del gruppo 3. In questo modo, tutto è ordinato e pulito, creando 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 desideri:
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 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 formato binario:
| Mantieni questi elementi esattamente così 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>, gli IP seguenti sarebbero consentiti (o
negati, 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 rispetto al quale la norma esegue il controllo IPRules. 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 è 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>
Elemento <IPRules>
L'elemento principale contenente le regole che consentono o negano gli indirizzi IP. L'attributo
noRuleMatchAction ti consente di definire come gestire gli 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 (consentire o negare l'accesso) se la regola di corrispondenza specificata non viene risolta
(nessuna corrispondenza).
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 a SourceAddress(es) che definisci.
<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 (nessuna corrispondenza). 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 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 del proxy API.
Ad esempio, puoi archiviare un indirizzo IP in una mappa 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 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 runtime senza dover modificare e ridistribuire il proxy API.
| Predefinito | N/D |
|---|---|
| Presenza | Facoltativo |
| Tipo | Stringa (solo un singolo indirizzo IP) |
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 è poco 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 validità
degli indirizzi IP che vuoi valutare. Ad esempio, se scegli di valutare tutti gli indirizzi IP nell'intestazione X-Forwarded-For, devi essere in grado di fidarti della validità di questi indirizzi e/o configurare regole DENY o ALLOW complete per consentire solo agli IP attendibili di chiamare il tuo proxy API.
L'indirizzo IP più a sinistra nell'intestazione appartiene al client, mentre quello più a destra al 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 TCP esterno.
Il valore che inserisci in questo elemento ti consente di determinare se controllare tutti gli indirizzi IP nell'intestazione (impostazione predefinita), 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 |
|
Schemi
Ogni tipo di policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle norme sono disponibili 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 scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.
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 corrisponde a un indirizzo IP specificato nell'elemento <SourceAddress> all'interno
dell'elemento <MatchRule> del criterio di controllo dell'accesso e l'attributo action dell'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>