Proteggere un'API richiedendo le chiavi API

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Nota: questo video è stato registrato con una versione precedente della UI di Apigee; tuttavia, i concetti sono ancora validi.

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 richieda una chiave API.
• Crea un prodotto API, uno sviluppatore e un'app sviluppatore.
• Chiama l'API con una chiave API.

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

Quando un'app effettua 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 controlla che la chiave API fornita:

• È valido
• Non sia stata revocata
• Corrisponde alla chiave API per il prodotto API che espone le risorse richieste

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

Nota:per completare questo tutorial, creerai e implementerai un proxy che utilizza criteri estensibili anziché criteri standard.

Crea il proxy API

Apigee nella console Cloud

1. Nella console Google Cloud , vai alla pagina Sviluppo proxy > Proxy API.

   Vai ai proxy API

2. Seleziona la tua organizzazione dal selettore di progetti nel riquadro Google Cloud. Il nome dell'organizzazione è uguale al nome del tuo progetto Google Cloud.
3. Fai clic su + Crea.
4. Nel riquadro Crea un proxy, in Modello di proxy, seleziona Proxy inverso (il più comune). Un proxy inverso instrada il traffico in entrata a un servizio di backend.
5. Configura il proxy come segue:
   

   Nome	Valore
   Nome proxy	helloworld_apikey
   Base Path	/helloapikey Il percorso di base del progetto fa parte dell'URL utilizzato per inviare richieste al proxy API.
   Descrizione	hello world protected by API key
   Destinazione (API esistente)	http://mocktarget.apigee.net Definisce l'URL di destinazione richiamato da Apigee in una richiesta al proxy API. Questo target restituisce una semplice risposta: Hello, Guest!.

6. Fai clic su Avanti.
7. (Facoltativo) Esegui il deployment. Lascia vuoti questi campi.
8. Fai clic su Crea.
9. Apigee crea il nuovo proxy e mostra il riepilogo dei dettagli del proxy nel riquadro Riepilogo proxy.

UI classica

1. Vai alla UI Apigee e accedi.
2. Seleziona la tua organizzazione utilizzando il menu a discesa nell'angolo in alto a sinistra dell'interfaccia utente.

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

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

   In questo campo	Fai questo
   Nome proxy	Inserisci: helloworld_apikey
   Project Base Path	Cambia con: /helloapikey Il percorso di base del progetto fa parte dell'URL utilizzato per effettuare richieste al proxy API.
   Descrizione	Inserisci: hello world protected by API key
   Destinazione (API esistente)	Inserisci: http://mocktarget.apigee.net Definisce l'URL di destinazione richiamato da Apigee in una richiesta al proxy API. Questo target restituisce una semplice risposta: Hello, Guest!.

7. Fai clic su Avanti.
8. Nella pagina Norme 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. Fai clic su 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

Apigee nella console Cloud

1. Nel riquadro Riepilogo proxy per il proxy helloworld_apikey, fai clic sulla scheda Sviluppa.
2. Nel menu Policy, fai clic su Aggiungi policy.
3. Nel riquadro Crea criterio, in Sicurezza, seleziona Verifica chiave API.
4. Nel riquadro Verifica chiave API, completa i campi obbligatori nelle sezioni Nome e Nome visualizzato utilizzando i seguenti valori:
   • Nome: inserisci un nome per la policy. Ad esempio, VerifyAPIKey.
   • Nome visualizzato: inserisci il nome della policy da utilizzare nell'interfaccia utente. Ad esempio, Verify API Key.
5. Fai clic su Crea.
6. Fai clic su per aggiungere un'altra policy.
7. Nel riquadro Crea criterio, seleziona Assegna messaggio nella sezione Mediazione.
8. Nel riquadro Assegna messaggio, compila i campi obbligatori nelle sezioni Nome e Nome visualizzato utilizzando i seguenti valori:
   • Nome: inserisci un nome per la policy. Ad esempio, AssignMessage.
   • Nome visualizzato: inserisci il nome della policy da utilizzare nell'interfaccia utente. Ad esempio, Assign Message.
9. Fai clic su Crea.
10. L'elemento <APIKey> nel codice XML riportato di seguito specifica la posizione della chiave API all'interno della richiesta in entrata. Per impostazione predefinita, il criterio recupera la chiave da un parametro di ricerca denominato apikey nella richiesta HTTP.

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

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

11. Aggiorna i contenuti della norma Assegna messaggio con i seguenti:
    Nota:il nome della norma cambierà in Remove Query Param apikey una volta apportata questa modifica.

<AssignMessage async="false" continueOnError="false" enabled="true" name="remove-query-param-apikey">
    <DisplayName>Remove Query Param apikey</DisplayName>
    <Remove>
        <QueryParams>
            <QueryParam name="apikey"/>
        </QueryParams>
    </Remove>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

12. Aggiungi le policy VerifyApiKey e Remove Query Param apikey.
    1. Nel menu Endpoint proxy, fai clic su Preflow.
    2. Nel riquadro Richiesta dell'editor visivo, fai clic su Aggiungi passaggio criterio.
    3. Nel riquadro Passaggio Aggiungi criterio, seleziona Verifica chiave API.
    4. Fai clic su Aggiungi.
    5. Nel riquadro Richiesta dell'editor visivo, fai clic su Aggiungi passaggio criterio.
    6. Nel riquadro Aggiungi passaggio criterio, seleziona Rimuovi parametro di query apikey.
    7. Fai clic su Aggiungi.
13. Fai clic su Salva.
14. Esegui il deployment del proxy in un ambiente:
    1. Fai clic su Esegui il deployment.
    2. Seleziona una revisione e un ambiente.
    3. Fai clic su Esegui il deployment.
15. Testa le modifiche chiamando l'API come descritto in Prova a chiamare l'API.

UI classica

1. Nell'editor proxy API, fai clic sulla scheda Sviluppa. Vedrai che sono state aggiunte due norme al flusso di richieste del proxy API:
   • Verifica chiave API: controlla la chiamata API per assicurarsi che sia presente una chiave API valida (inviata come parametro di query).
   • Remove Query Param apikey: una policy Assign Message che rimuove la chiave API dopo che è stata controllata, in modo che non venga passata e esposta inutilmente.

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

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

   Il nome apikey è arbitrario e può essere qualsiasi proprietà che contenga 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 vedere come viene protetto dai criteri.

1. Operazione riuscita

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

   http://mocktarget.apigee.net

   Dovresti ricevere questa risposta di esito positivo: Hello, Guest!

2. Errore

   Ora prova a chiamare il proxy API:

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

   dove YOUR ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti. Consulta 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 Deploy a sample proxy.

   Senza il criterio Verifica chiave API, questa chiamata restituirebbe la stessa risposta della chiamata precedente. In questo caso, 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 passato una chiave API valida (come parametro di query).

Nei passaggi successivi otterrai la chiave API richiesta.

Aggiunta di un prodotto API

Apigee nella console Cloud

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

1. Nella console Google Cloud , vai alla pagina Distribuzione > Prodotti API:

   Vai ai prodotti API

2. Fai clic su +Crea.
3. Inserisci i dettagli del prodotto per il tuo prodotto API.
   

   Campo	Descrizione
   Nome	Nome interno del prodotto API. Non specificare caratteri speciali nel nome. Nota:non puoi modificare il nome una volta creato il prodotto API.
   Nome visualizzato	Nome visualizzato per il prodotto API. Il nome visualizzato viene utilizzato nell'interfaccia utente e puoi modificarlo in qualsiasi momento. Se non specificato, viene utilizzato il valore Name. Questo campo viene compilato automaticamente utilizzando il valore Nome; puoi modificare o eliminare i suoi contenuti. Il nome visualizzato può includere caratteri speciali.
   Descrizione	Descrizione del prodotto API.
   Ambiente	Gli ambienti a cui il prodotto API consentirà l'accesso. Ad esempio, test o prod.
   Accesso	Seleziona Public (Pubbliche).
   Approvare automaticamente le richieste di accesso	Attiva l'approvazione automatica delle richieste di chiavi 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.

Per saperne di più sull'aggiunta di un prodotto API, consulta Crea un prodotto API.

UI classica

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

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

   Campo	Descrizione
   Nome	Nome interno del prodotto API. Non specificare caratteri speciali nel nome. Nota:non puoi modificare il nome una volta creato il prodotto API.
   Nome visualizzato	Nome visualizzato per il 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 Nome. Puoi modificare o eliminare i contenuti. Il nome visualizzato può includere caratteri speciali.
   Descrizione	Descrizione del prodotto API.
   Ambiente	Gli ambienti a cui il prodotto API consentirà l'accesso. Ad esempio, test o prod.
   Accesso	Seleziona Public (Pubbliche).
   Approvare automaticamente le richieste di accesso	Attiva l'approvazione automatica delle richieste di chiavi 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 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.

Aggiungere uno sviluppatore e un'app alla tua organizzazione

Successivamente, 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, in qualità di fornitore di API, avrai un controllo più granulare sull'accesso alle tue API e report più granulari sul traffico API per app.

Creare uno sviluppatore

Apigee nella console Cloud

Per creare uno sviluppatore:

1. Nella console Google Cloud , vai alla pagina Distribuzione > Sviluppatori:

   Vai a Sviluppatori

2. Fai clic su + Crea.
3. Inserisci quanto segue nella finestra Aggiungi sviluppatore:
   

   Campo	Valore
   Nome	Keyser
   Cognome	Soze
   Email	[e-mail]
   Nome utente	keyser

4. Fai clic su Aggiungi.

Per ulteriori informazioni sulla creazione di uno sviluppatore, vedi Registrazione degli sviluppatori di app.

UI classica

Per creare uno sviluppatore:

1. Seleziona Pubblica > Sviluppatori nel menu.
   Nota: se ti trovi ancora nella schermata Sviluppa, fai clic su "<" accanto a SVILUPPA 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.

Registrare un'app

Apigee nella console Cloud

1. Nella console Google Cloud , vai alla pagina Distribuzione > App:

   Vai ad App

2. Fai clic su + Crea.
3. Nella finestra Crea app, inserisci quanto segue:
   

   Campo	Valore
   Nome applicazione	Inserisci: keyser_app
   Nome visualizzato	Inserisci: keyser_app
   Developer	Seleziona: Keyser Soze ([e-mail])
   URL di callback	Lascia vuoto
   Note	Lascia vuoto

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

Per saperne di più sulla registrazione di un'app, vedi Registrazione di un'app.

UI classica

Per registrare un'app per sviluppatori:

1. Seleziona Pubblica > App.
2. Fai clic su + App.
3. Nella finestra Nuova app per sviluppatori, inserisci quanto segue:
   

   Campo	Valore
   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

Apigee nella console Cloud

Per ottenere la chiave API:

1. Nella console Google Cloud , vai alla pagina Distribuzione > App.

   Vai ad App

2. Seleziona l'app che ti interessa dall'elenco.
3. Nella pagina Visualizza app, in Credenziali, fai clic su accanto al campo Chiave. Tieni presente che la chiave è associata al prodotto che hai creato.
4. Fai clic su Copia. Utilizzerai questa chiave nel passaggio successivo.

UI classica

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.

Chiamare l'API con una chiave

Ora che hai una chiave API, puoi utilizzarla per chiamare il proxy API. Incolla la chiave API come mostrato, come parametro di query. 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 che nella chiamata sia inclusa una chiave API valida.

Tieni presente che in generale non è consigliabile passare una chiave API come parametro di query. Ti consigliamo di passarlo nell'intestazione HTTP.

Best practice: passare la chiave nell'intestazione HTTP

Nota:è consigliabile 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 rappresentare 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 in modo che cerchi la chiave API in un'intestazione denominata x-apikey.

Apigee nella console Cloud

1. Nella console Google Cloud , vai alla pagina Sviluppo proxy > Proxy API.

Vai ai proxy API

2. Seleziona il proxy richiesto dall'elenco.
3. Nella pagina Dettagli proxy, fai clic su Sviluppa.
4. Modifica il file XML del criterio per indicare al criterio di cercare nell'intestazione anziché nel parametro di ricerca:

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

5. Fai clic su Salva per salvare le modifiche.
6. Fai clic su Esegui il deployment.
7. Seleziona una revisione e un ambiente.
8. Fai clic su Esegui il deployment.

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

   curl -v -H "x-apikey: YOUR_API_KEY" 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 Verifica chiave API verrà configurato nel seguente modo:

<APIKey ref="request.formparam.YOUR_API_KEY"/>

UI classica

1. Modifica il proxy API. Seleziona Sviluppa > Proxy API > helloworld_apikey e vai alla visualizzazione Sviluppa.

2. Seleziona la policy Verifica chiave API e modifica l'XML della policy in modo che cerchi in header anziché in queryparam:

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

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

4. Effettua la seguente chiamata API utilizzando cURL per passare la chiave API come intestazione chiamata 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 Verifica chiave API verrà configurato nel seguente modo:

<APIKey ref="request.formparam.YOUR_API_KEY"/>

Argomenti correlati

Ecco alcuni argomenti relativi a prodotti e chiavi API:

• Gestione dei prodotti API
• Chiavi API
• Registrazione degli sviluppatori di app
• Registrare le app e gestire le chiavi API
• Norme relative alla verifica della chiave API

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

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