Chiamare un'API con una chiave di sottoscrizione
Quando si pubblica un'API, spesso si vuole avere un controllo di un certo livello su chi può accedere all'API tramite il gateway. Le chiavi di sottoscrizione sono un modo per limitare l'accesso a un'API.
In questa unità viene descritto come usare le chiavi di sottoscrizione per proteggere le API.
Sottoscrizioni e chiavi
Per proteggere le API, è possibile usare una chiave di sottoscrizione.
Nota
Generalmente negli ambienti di produzione di Gestione API la chiave di sottoscrizione si combina con altri meccanismi per proteggere le API dall'uso non autorizzato, ad esempio nel caso dell'autenticazione di certificati o dell'autorizzazione OAuth 2.0. questi meccanismi non rientrano nell'ambito di questo modulo.
Una chiave di sottoscrizione è una stringa univoca generata automaticamente, che viene passata nelle intestazioni della richiesta client o come stringa di query nell'URL. La chiave è direttamente correlata a una sottoscrizione che può essere inclusa nell'ambito di diverse aree, offrendo un controllo granulare su autorizzazioni e criteri. Gli ambiti principali di una sottoscrizione sono:
- Tutte le API
- Una singola API
- Prodotto
Un'applicazione che chiama un'API protetta deve includere la chiave nella richiesta.
È possibile rigenerare le chiavi di sottoscrizione in qualsiasi momento. È possibile rigenerare le chiavi di sottoscrizione se ad esempio si sospetta che una chiave era condivisa con utenti non autorizzati.
Ogni sottoscrizione ha due chiavi, una primaria e una secondaria. Con due chiavi è più facile rigenerarne una all’occorrenza. Se ad esempio si vuole cambiare la chiave primaria senza tempi di inattività, usare la chiave secondaria nelle app.
Per i prodotti in cui sono abilitate le sottoscrizioni, è necessario specificare una chiave quando si effettuano chiamate alle API in tale prodotto. Gli sviluppatori possono ottenere una chiave inviando una richiesta di sottoscrizione. Questo processo è una parte fondamentale del flusso di lavoro di Gestione API.
Nota
La creazione di nuovi utenti e l'assegnazione delle chiavi di sottoscrizione per consentire loro di accedere all'API sono una parte fondamentale del flusso di lavoro di Gestione API, ma non rientrano nell'ambito di questo modulo.
Chiamare un'API con la chiave di sottoscrizione
Le applicazioni devono includere una chiave valida in tutte le richieste HTTP quando effettuano chiamate agli endpoint dell'API protetti da una sottoscrizione. Le chiavi possono essere passate nell'intestazione della richiesta oppure come stringa di query nell'URL.
Il nome dell'intestazione predefinito è Ocp-Apim-Subscription-Key e la stringa di query predefinita è subscription-key.
Per testare le chiamate API, è possibile usare il portale per sviluppatori (se disponibile nel livello di servizio), uno strumento da riga di comando come curl o altri strumenti client REST.
Ecco un esempio di richiesta GET che passa una chiave nell'intestazione della richiesta usando il comando curl :
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Ecco un comando curl di esempio che passa una chiave nell'URL come stringa di query:
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
Se la chiave non viene passata nell'intestazione o come stringa di query nell'URL, si ottiene una risposta di accesso negato 401 dal gateway API.