Proteggi un'API richiedendo chiavi API

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Nota: il seguente video mostra il proxy Editor classico nell'interfaccia utente di Apigee. Apigee sta introducendo una nuova versione dell'Editor proxy, che ha un design diverso dalla versione classica mostrata nel video.

Video: guarda questo breve video per un'introduzione alla protezione dell'API.

Cosa imparerai a fare

Questo tutorial spiega come:

• Crea un proxy API che richiede una chiave API.
• Creare un prodotto API, un'app sviluppatore e un'app per sviluppatori.
• Chiamare l'API con una chiave API.

È importante proteggere l'API da accessi non autorizzati. Un modo per farlo è tramite le chiavi API.

Quando un'app invia una richiesta a un proxy API configurato per verificare una chiave API, l'app deve fornire una chiave valida. In fase di runtime, il criterio Verifica chiave API verifica che la chiave API fornita:

• È valido
• Non è stato revocato
• Corrisponde alla chiave API per il prodotto API che espone le risorse richieste

Se la chiave è valida, la richiesta è consentita. Se la chiave non è valida, la richiesta genera un errore di autorizzazione.

Crea il proxy API

1. Vai all'interfaccia utente di Apigee ed esegui l'accesso.
2. Seleziona la tua organizzazione utilizzando il menu a discesa nell'angolo in alto a sinistra dell'interfaccia utente.

3. Fai clic su Sviluppo > Proxy API per visualizzare l'elenco dei proxy API.

4. Fai clic su Crea nuovo.
   
5. Nella procedura guidata Crea un proxy, seleziona Inverti proxy (più comune).
6. Configura il proxy come segue:
   

   In questo campo	fai questo
   Nome proxy	Inserisci: helloworld_apikey
   Percorso base del progetto	Cambia in: /helloapikey Il percorso di base del progetto fa parte dell'URL utilizzato per effettuare richieste al proxy API.
   Description	Inserisci: hello world protected by API key
   Target (API esistente)	Inserisci: http://mocktarget.apigee.net Questo definisce l'URL di destinazione che Apigee richiama su una richiesta al proxy API. Questo target restituisce solo una risposta semplice: Hello, Guest!.

7. Tocca Avanti.
8. Nella pagina Criteri comuni, seleziona Chiave API. Questa opzione aggiunge automaticamente due criteri al proxy API e crea un prodotto API necessario per generare la chiave API.
9. Tocca Avanti.
10. Nella pagina Riepilogo, assicurati che sia selezionato un ambiente di deployment e fai clic su Crea ed esegui il deployment.
11. Fai clic su Modifica proxy per visualizzare la pagina Panoramica del proxy API.

Visualizza le norme

1. Nell'editor proxy API, fai clic sulla scheda Sviluppo. Vedrai che sono stati aggiunti due criteri al flusso di richiesta del proxy API:
   • Verifica chiave API: controlla la chiamata API per garantire che sia presente una chiave API valida (inviata come parametro di query).
   • Rimuovi apikey parametro di query: un criterio di assegnazione dei messaggi che rimuove la chiave API dopo la verifica, in modo che non venga trasmessa ed esposta inutilmente.

2. Fai clic sull'icona Verifica criterio chiave API nella visualizzazione flusso e controlla la configurazione XML del criterio nella visualizzazione del codice in basso. L'elemento <APIKey> indica al criterio dove deve cercare la chiave API quando viene effettuata la chiamata. Per impostazione predefinita, la chiave viene cercata come parametro di ricerca chiamato apikey nella richiesta HTTP:

   <APIKey ref="request.queryparam.apikey" />
   

   Il nome apikey è arbitrario e può essere qualsiasi proprietà contenente la chiave API.

Prova a chiamare l'API

In questo passaggio, effettuerai una chiamata API riuscita direttamente al servizio di destinazione, quindi effettuerai una chiamata non riuscita al proxy API per verificare come viene protetto dai criteri.

1. Operazione riuscita

   Da un browser web, vai al seguente indirizzo. Questo è il servizio di destinazione a cui è configurato il proxy API per inoltrare la richiesta, ma per il momento lo utilizzerai direttamente:

   http://mocktarget.apigee.net
   

   Dovresti ottenere questa risposta corretta: Hello, Guest!

2. Errore

   Ora prova a chiamare il tuo proxy API:

   curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey

   dove YOUR ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti. Vedi Trovare il nome host del gruppo di ambienti.

   Nota: se hai difficoltà a chiamare il proxy, potresti dover aggiungere l'intestazione Host, come descritto in Eseguire il deployment di un proxy di esempio.

   Senza il criterio di verifica della chiave API, questa chiamata ti restituirebbe la stessa risposta della chiamata precedente. In questo caso, invece, dovresti ricevere la seguente risposta di errore:

   {"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
   

   il che significa, correttamente, che non hai trasmesso una chiave API valida (come parametro di query).

Nei passaggi successivi, otterrai la chiave API richiesta.

Aggiunta di un prodotto API

Per aggiungere un prodotto API utilizzando l'interfaccia utente di Apigee:

1. Seleziona Pubblica > Prodotti API.
2. Fai clic su +Crea.
3. Inserisci i dettagli del prodotto API.
   

   Campo	Descrizione
   Nome	Nome interno del prodotto API. Non specificare caratteri speciali nel nome. Nota: non puoi modificare il nome dopo aver creato il prodotto API.
   Nome visualizzato	Nome visualizzato del prodotto API. Il nome visualizzato viene utilizzato nell'interfaccia utente e puoi modificarlo in qualsiasi momento. Se non specificato, verrà utilizzato il valore Nome. Questo campo viene compilato automaticamente utilizzando il valore del campo Nome; puoi modificarne o eliminarne i contenuti. Il nome visualizzato può includere caratteri speciali.
   Descrizione	Descrizione del prodotto API.
   Ambiente	Ambienti a cui il prodotto API consentirà l'accesso. Ad esempio, test o prod.
   Accesso	Seleziona Public (Pubbliche).
   Approva automaticamente le richieste di accesso	Attiva l'approvazione automatica delle richieste chiave per questo prodotto API da qualsiasi app.
   Quota	Ignora per questo tutorial.
   Ambiti OAuth consentiti	Ignora per questo tutorial.

4. Nella sezione Operazioni, fai clic su AGGIUNGI UN'OPERAZIONE.
5. Nel campo Proxy API, seleziona il proxy API che hai appena creato.
6. Nel campo Percorso, inserisci "/". Ignora gli altri campi.
7. Fai clic su Salva per salvare l'operazione.
8. Fai clic su Salva per salvare il prodotto API.

Aggiungi uno sviluppatore e un'app alla tua organizzazione

Quindi, simuleremo il flusso di lavoro di uno sviluppatore che si registra per utilizzare le tue API. Uno sviluppatore avrà una o più app che chiamano le tue API e ogni app riceve una chiave API univoca. In questo modo, il fornitore delle API può controllare in modo più granulare l'accesso alle API e generare report più granulari sul traffico API per app.

Creare uno sviluppatore

Per creare uno sviluppatore:

1. Seleziona Pubblica > Sviluppatori nel menu.
   Nota: se ti trovi ancora nella schermata Sviluppo, fai clic su "<" di DEVELOP per visualizzare il menu e seleziona Pubblica > Sviluppatori
2. Fai clic su + Sviluppatore.
3. Nella finestra Nuovo sviluppatore, inserisci quanto segue:
   

   In questo campo	Invio
   Nome	Keyser
   Cognome	Soze
   Nome utente	keyser
   Email	[e-mail]

4. Fai clic su Crea.

Registra un'app

Per registrare un'app sviluppatore:

1. Seleziona Pubblica > App.
2. Fai clic su + App.
3. Inserisci quanto segue nella finestra Nuova app sviluppatore:
   

   In questo campo	fai questo
   Nome e Nome visualizzato	Inserisci: keyser_app
   Developer	Seleziona: Keyser Soze ([e-mail])
   URL di callback e Note	Lascia vuoto

4. Nella sezione Credenziali, seleziona Mai. Le credenziali per questa app non scadranno mai.
5. Fai clic su Aggiungi prodotto.
6. Seleziona il prodotto appena creato.
7. Fai clic su Crea.

Recuperare la chiave API

Per ottenere la chiave API:

1. Nella pagina App (Pubblica > App), fai clic su keyser_app.
2. Nella pagina keyser_app, fai clic su Mostra accanto a Chiave nella sezione Credenziali. Tieni presente che la chiave è associata al prodotto che hai creato.
   
3. Seleziona e copia la chiave. Lo utilizzerai nel passaggio successivo.

Chiama l'API con una chiave

Ora che disponi di una chiave API, puoi utilizzarla per chiamare il proxy API. Incolla la chiave API come parametro di query, come mostrato. Assicurati che non ci siano spazi aggiuntivi nel parametro di query.

curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=your_api_key

Ora, quando chiami il proxy API, dovresti ricevere questa risposta: Hello, Guest!

Complimenti! Hai creato un proxy API e lo hai protetto richiedendo l'inclusione di una chiave API valida nella chiamata.

Tieni presente che, in generale, non è consigliabile passare una chiave API come parametro di query. Considera invece di trasmetterlo nell'intestazione HTTP.

Best practice: passaggio della chiave nell'intestazione HTTP

Nota: è buona norma passare la chiave API in un'intestazione anziché in un parametro di query. I parametri di query vengono visualizzati nella cronologia del browser e nei log di rete, il che potrebbe presentare un rischio per la sicurezza. Le intestazioni non vengono visualizzate nella cronologia del browser e nei log di rete.

In questo passaggio, modificherai il proxy per cercare la chiave API in un'intestazione denominata x-apikey.

1. Modifica il proxy API. Seleziona Sviluppo > Proxy API > helloworld_apikey e vai alla vista Sviluppo.

2. Seleziona il criterio Verifica chiave API e modifica il codice XML del criterio per indicare al criterio di cercare nel header anziché in queryparam:

   <APIKey ref="request.header.x-apikey"/>
   

3. Salva il proxy API e utilizza Esegui il deployment per implementarlo.

4. Effettua la seguente chiamata API utilizzando cURL per passare la chiave API sotto forma di intestazione x-apikey. Non dimenticare di sostituire il nome dell'organizzazione.

   curl -v -H "x-apikey: {api_key_goes_here}" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey

Tieni presente che, per completare la modifica, devi anche configurare il criterio Assegna messaggio per rimuovere l'intestazione anziché il parametro di query. Ad esempio:

<Remove>
  <Headers>
      <Header name="x-apikey"/>
  </Headers>
</Remove>

Nota:puoi anche passare la chiave API come parametro del modulo. In questo caso, il criterio di verifica chiave API verrebbe configurato in questo modo:

<APIKey ref="request.formparam.{api_key_goes_here}"/>

Argomenti correlati

Ecco alcuni argomenti relativi a chiavi e prodotti API:

• Gestione dei prodotti basati su API
• Chiavi API
• Registrare gli sviluppatori di app
• Registrare app e gestire le chiavi API
• Verifica il criterio della chiave API

La protezione delle API comporta spesso misure di sicurezza aggiuntive come, ad esempio, OAuth, un protocollo aperto che scambia le credenziali (come nome utente e password) con token di accesso. I token di accesso sono lunghe stringhe casuali che possono essere trasmesse attraverso una pipeline di messaggi, anche da un'app all'altra, senza compromettere le credenziali originali.

Per una panoramica degli argomenti relativi alla sicurezza, consulta Proteggere un proxy.