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.
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 è con 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.
Seleziona la tua organizzazione utilizzando il menu a discesa nell'angolo in alto a sinistra dell'interfaccia utente.
Fai clic su Sviluppa > Proxy API per visualizzare l'elenco dei proxy API.
Fai clic su Crea nuovo.
Nella procedura guidata Crea un proxy, seleziona Reverse proxy (il più comune).
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
Target (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!.
Fai clic su Avanti.
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.
Fai clic su Avanti.
Nella pagina Riepilogo, assicurati che sia selezionato un ambiente di deployment e fai clic su Crea ed esegui il deployment.
Fai clic su Modifica proxy per visualizzare la
pagina Panoramica del proxy API.
Visualizzare le norme
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 trasferita e
esposta inutilmente.
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.
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!
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
Per aggiungere un prodotto API utilizzando l'interfaccia utente Apigee:
Seleziona Pubblica > Prodotti API.
Fai clic su +Crea.
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 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.
Nella sezione Operazioni, fai clic su AGGIUNGI UN'OPERAZIONE.
Nel campo Proxy API, seleziona il proxy API appena creato.
Nel campo Percorso, inserisci "/". Ignora gli altri campi.
Fai clic su Salva per salvare l'operazione.
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
Per creare uno sviluppatore:
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.
Fai clic su + Sviluppatore.
Nella finestra Nuovo sviluppatore, inserisci quanto segue:
In questo campo
invio
Nome
Keyser
Cognome
Soze
Nome utente
keyser
Email
keyser@example.com
Fai clic su Crea.
Registrare un'app
Per registrare un'app per sviluppatori:
Seleziona Pubblica > App.
Fai clic su + App.
Nella finestra Nuova app per sviluppatori, inserisci quanto segue:
In questo campo
Fai questo
Nome e Nome visualizzato
Inserisci: keyser_app
Developer
Seleziona: Keyser Soze (keyser@example.com)
URL di callback e Note
Lascia vuoto
Nella sezione Credenziali, seleziona Mai.
Le credenziali per questa app non scadranno mai.
Fai clic su Aggiungi prodotto.
Seleziona il prodotto appena creato.
Fai clic su Crea.
Recuperare la chiave API
Per ottenere la chiave API:
Nella pagina App (Pubblica > App), fai clic su keyser_app.
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.
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.
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
In questo passaggio, modificherai il proxy in modo che cerchi la chiave API in un'intestazione denominata x-apikey.
Modifica il proxy API. Seleziona Sviluppa > Proxy API >
helloworld_apikey e vai alla visualizzazione Sviluppa.
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"/>
Salva il proxy API e utilizza Esegui il deployment per eseguirne il deployment.
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.
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:
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.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-09-05 UTC."],[[["\u003cp\u003eThis guide demonstrates how to secure APIs in Apigee and Apigee hybrid using API keys to prevent unauthorized access.\u003c/p\u003e\n"],["\u003cp\u003eThe tutorial walks through the process of creating an API proxy, configuring it to require API keys, and setting up policies to verify and remove the API key.\u003c/p\u003e\n"],["\u003cp\u003eIt explains how to create API products, developers, and developer apps, which are needed to generate API keys for accessing the protected API proxy.\u003c/p\u003e\n"],["\u003cp\u003eThe document illustrates how to test the API proxy by making calls with and without a valid API key, showcasing the security enforcement.\u003c/p\u003e\n"],["\u003cp\u003eIt highlights the best practice of passing API keys in the HTTP header (x-apikey) instead of as a query parameter for enhanced security, and details the required modifications to the API proxy.\u003c/p\u003e\n"]]],[],null,["# Secure an API by requiring API keys\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\n\n*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*\n\n| **Note:** This video was recorded with a previous version of the Apigee UI; however, the concepts are still valid.\n\n\n**Video:** Check out this short video for an introduction on securing your API. \n**What you'll learn**\n\nThis tutorial explains how to:\n\n- Create an API proxy that requires an API key.\n- Create an API product, a developer, and a developer app.\n- Call your API with an API key. \nIt's important to protect your API from unauthorized access. One way to do that is with\nAPI keys.\n\nWhen an app makes a request to an API proxy that is configured to verify an API\nkey, the app must supply a valid key. At runtime, the\nVerify API Key policy checks that the supplied API key:\n\n- Is valid\n- Hasn't been revoked\n- Matches the API key for the API product that exposes the requested resources\n\nIf the key is valid, the request is allowed. If the key is invalid, the request results in\nan authorization failure. \n\nCreate the API proxy\n--------------------\n\n1. Go to the [Apigee UI](https://apigee.google.com) and sign in.\n2. Select your organization using the drop-down menu in the upper left corner of the UI.\n3. Click **Develop \\\u003e API Proxies** to display the API\n proxies list.\n\n4. Click **Create New** . \n5. In the Build a Proxy wizard, select **Reverse proxy (most common)**.\n6. Configure the proxy as follows: \n\n7. Click **Next**.\n8. On the **Common policies** page, select **API Key**. This option automatically adds two policies to your API proxy and creates an API product needed for generating the API key.\n9. Click **Next**.\n10. On the Summary page, make sure a deployment environment is selected, and click **Create and deploy**.\n11. Click **Edit proxy** to display the Overview page for the API proxy. \n\nView the policies\n-----------------\n\n1. In the API proxy editor, click the **Develop** tab. You'll see that two policies have been added to the request flow of the API proxy:\n - **Verify API Key** -- Checks the API call to make sure a valid API key is present (sent as a query parameter).\n - **Remove Query Param apikey** -- An Assign Message policy that removes the API key after it's checked, so that it doesn't get passed around and exposed unnecessarily.\n2. Click the Verify API Key policy icon in the flow view, and look at the policy's XML\n configuration in the lower code view. The `\u003cAPIKey\u003e` element tells the\n policy where it should look for the API key when the call is made. By default, it looks\n for the key as a query parameter called `apikey` in the HTTP request:\n\n ```text\n \u003cAPIKey ref=\"request.queryparam.apikey\" /\u003e\n ```\n\n The name `apikey` is arbitrary and can be any property that contains the\nAPI key. \n\nTry to call the API\n-------------------\n\nIn this step, you'll make a successful API call directly to the target service, then\nyou'll make an unsuccessful call to the API proxy to see how it's being protected by the\npolicies.\n\n1. **Success**\n\n In a web browser, go to the following address. This is the target service that the API\n proxy is configured to forward the request to, but you'll hit it directly for now: \n\n ```text\n http://mocktarget.apigee.net\n ```\n\n You should get this successful response: `Hello, Guest!`\n2. **Failure**\n\n Now try to call your API proxy: \n\n ```\n curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey\n ```\n\n where \u003cvar translate=\"no\"\u003eYOUR ENV_GROUP_HOSTNAME\u003c/var\u003e is the environment group hostname. See\n [Find the environment group hostname](/apigee/docs/api-platform/get-started/test-proxy#find-the-environment-group-hostname).\n | **Note:** If you have trouble calling the proxy, you may need to add the `Host` header, as described in [Deploy a sample proxy](/apigee/docs/api-platform/get-started/deploy-sample).\n\n Without the Verify API Key policy, this call would give you the same response as the\n previous call. But in this case, you should get the following error response: \n\n ```gdscript\n {\"fault\":{\"faultstring\":\"Failed to resolve API Key variable request.queryparam.apikey\",\"detail\":{\"errorcode\":\"steps.oauth.v2.FailedToResolveAPIKey\"}}}\n ```\n\n which means, correctly, that you didn't pass a valid API key (as a query\n parameter).\n\nIn the next steps, you'll get the required API key. \n\nAdding an API product\n---------------------\n\nTo add an API product using the Apigee UI:\n\n1. Select **Publish \\\u003e API Products**.\n2. Click **+Create**.\n3. Enter the Product Details for your API product. \n\n4. In the **Operations** section, click **ADD AN OPERATION**.\n5. In the API Proxy field, select the API proxy you just created.\n6. In the Path field, enter \"/\". Ignore the other fields.\n7. Click **Save** to save the Operation.\n8. Click **Save** to save the API product. \n\nAdd a developer and app to your\norganization\n--------------------------------------------\n\nNext, we're going to simulate the workflow of a developer signing up to use your APIs. A\ndeveloper will have one or more apps that call your APIs, and each app gets a unique API key.\nThis gives you, the API provider, more granular control over access to your APIs and more\ngranular reporting on API traffic by app.\n\n### Create a developer\n\nTo create a developer:\n\n1. Select **Publish \\\u003e Developers** in the menu. \n **Note** : If you are still in the Develop screen, click on the **\"\\\u003c\"** by **DEVELOP** to display the menu and select **Publish \\\u003e Developers**\n2. Click **+ Developer**.\n3. Enter the following in the New Developer window: \n\n4. Click **Create**.\n\n### Register an app\n\nTo register a developer app:\n\n1. Select **Publish \\\u003e Apps**.\n2. Click **+ App**.\n3. Enter the following in the New Developer App window: \n\n4. In the Credentials section, select **Never**. The credentials for this app will never expire.\n5. Click **Add product**.\n6. Select the product you just created.\n7. Click **Create**.\n\n### Get the API key\n\nTo get the API key:\n\n1. On the Apps page (Publish \\\u003e Apps), click **keyser_app**.\n2. On the **keyser_app** page, click **Show** next to **Key** in the **Credentials** section. Notice that the key is associated with the product you created. \n3. Select and copy the key. You'll use it in the next step. \n\nCall the API with a key\n-----------------------\n\nNow that you have an API key, you can use it to call the API proxy. Paste the API key as\nshown, as a query parameter. Make sure there are no extra\nspaces in the query parameter. \n\n```\ncurl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=your_api_key\n```\n\nNow when you call the API proxy, you should get this response: `Hello,\nGuest!`\n\nCongratulations! You've created an API proxy and protected it by requiring that a valid\nAPI key be included in the call.\n\nNote that in general it's not good practice to pass an API key as a query parameter. You\nshould consider [passing it in the HTTP\nheader instead](#extracreditpassingthekeyinthehttpheader). \n\nBest practice: Passing the key in the HTTP\nheader\n-------------------------------------------------\n\n| **Note:** It's a good practice to pass the API key in a header rather than in a query parameter. Query parameters appear in the browser history and network logs, which could present a security risk. Headers do not appear in the browser history and network logs.\n\nIn this step, you will modify the proxy to look for the API key in a header called `x-apikey`.\n\n1. Edit the API proxy. Select **Develop \\\u003e API Proxies \\\u003e\n helloworld_apikey** , and go to the **Develop** view.\n2. Select the **Verify API Key** policy, and modify the policy XML to tell\n the policy to look in the `header` rather than in the\n `queryparam`:\n\n ```text\n \u003cAPIKey ref=\"request.header.x-apikey\"/\u003e\n ```\n3. **Save** the API proxy and use **Deploy** to deploy it.\n4. Make the following API call using cURL to pass the API key as a header called\n `x-apikey`. Don't forget to substitute your organization name.\n\n ```scdoc\n curl -v -H \"x-apikey: {api_key_goes_here}\" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey\n ```\n\nNote that to fully complete the change, you'd also need to configure the Assign Message\npolicy to remove the header instead of the query parameter. For example: \n\n```\n\u003cRemove\u003e\n \u003cHeaders\u003e\n \u003cHeader name=\"x-apikey\"/\u003e\n \u003c/Headers\u003e\n\u003c/Remove\u003e\n```\n| **Note:** You could also pass the API key as a form parameter. If you did, the Verify API Key policy would be configured like this: \n|\n| ```scdoc\n| \u003cAPIKey ref=\"request.formparam.{api_key_goes_here}\"/\u003e\n``` \n\nRelated topics\n--------------\n\nHere are some topics related to API products and keys:\n\n- [Managing API products](/apigee/docs/api-platform/publish/create-api-products)\n- [API keys](/apigee/docs/api-platform/security/api-keys)\n- [Registering app\n developers](/apigee/docs/api-platform/publish/adding-developers-your-api-product)\n- [Register apps and\n manage API keys](/apigee/docs/api-platform/publish/creating-apps-surface-your-api)\n- [Verify API Key\n policy](/apigee/docs/api-platform/reference/policies/verify-api-key-policy)\n\nAPI protection often involves additional security such as [OAuth](/apigee/docs/api-platform/security/oauth/oauth-home), an\nopen protocol that exchanges credentials (like username and password) for\naccess tokens. Access tokens are long, random strings that can be passed through a message\npipeline, including from app to app, without compromising the original credentials.\n\nFor an overview of security-related topics, see\n[Securing a proxy](https://cloud.google.com/apigee/docs/api-platform/security/api-security)."]]
