Creare sottoscrizioni in Gestione API di Azure
Quando si pubblica un'API con Gestione API, si definisce chi può accedere all'API tramite il gateway.
Per l'app del meteo, si vuole garantire che solo i clienti che hanno sottoscritto il servizio possano accedere all'API e usare i dati delle previsioni. Questo controllo di accesso viene eseguito tramite l'emissione di chiavi di sottoscrizione.
Importante
Le sottoscrizioni in questo contesto non sono correlate alle sottoscrizioni di Azure usate per gestire l'account di Azure.
In questa unità si apprenderà come usare le chiavi di sottoscrizione per proteggere le API.
Sottoscrizioni e chiavi
È possibile scegliere di rendere disponibili liberamente le API e le informazioni in esse contenute. Ma in genere si vuole limitare l'accesso agli utenti a pagamento o alle organizzazioni con cui si intrattiene una relazione di lavoro. È possibile controllare l'accesso alle API tramite le sottoscrizioni. Le sottoscrizioni vengono usate per segmentare l'accesso degli utenti a un'API.
Le chiavi di sottoscrizione formano l'autorizzazione per consentire l'accesso a queste sottoscrizioni. Ogni volta che un client effettua una richiesta a un'API protetta, deve essere inclusa una chiave di sottoscrizione valida nella richiesta HTTP altrimenti la chiamata viene rifiutata.
Una chiave di sottoscrizione è una chiave univoca generata automaticamente che può essere passata come parte di una chiamata API. La chiave è direttamente correlata a una sottoscrizione che può avere come ambito diverse aree. Le sottoscrizioni offrono un controllo granulare delle autorizzazioni e dei criteri.
I tre ambiti principali di una sottoscrizione sono:
| Ambito | Dettagli |
|---|---|
| Tutte le API | Si applica a tutte le API accessibili dal gateway. |
| Singola API | Si applica a una singola API importata e a tutti i relativi endpoint. |
| Prodotto | Un prodotto è una raccolta di una o più API configurate in Gestione API. È possibile assegnare le API a più di un prodotto. I prodotti possono avere regole di accesso, quote di utilizzo e condizioni per l'utilizzo diverse. Quindi, se si desidera che i partner e i fornitori abbiano diritti di accesso diversi per l'API WeatherData, assegnare l'API a un prodotto e quindi usare il portale di Azure per associare le API a un prodotto. |
Le applicazioni che chiamano un'API protetta devono includere una chiave di sottoscrizione in ogni richiesta.
È possibile rigenerare le chiavi di sottoscrizione in qualsiasi momento. Ad esempio, se si sospetta che una chiave sia stata condivisa con utenti non autorizzati, è possibile crearne una nuova.
Ogni sottoscrizione ha due chiavi, una primaria e una secondaria. Avere due chiavi consente di rigenerare una chiave più facilmente, quando è necessario. 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 che i client specifichino una chiave quando effettuano chiamate alle API nel prodotto. Gli sviluppatori possono ottenere una chiave inviando una richiesta di sottoscrizione. Se si approva la richiesta, è necessario inviare la chiave di sottoscrizione in modo sicuro, ad esempio in un messaggio crittografato. Questo passaggio è una parte fondamentale del flusso di lavoro di Gestione API.
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 parametro della stringa di query nell'URL.
Il nome di intestazione della chiave di sottoscrizione predefinito è Ocp-Apim-Subscription-Key e il nome della stringa di query predefinito è subscription-key.
Per testare le chiamate API, è possibile usare una console di test nel portale di Azure o il portale per sviluppatori o gli strumenti da riga di comando, ad esempio curl. Di seguito è riportato un esempio di richiesta GET nel portale per sviluppatori, che mostra l'intestazione della chiave di sottoscrizione:
Ecco un esempio di come passare una chiave in un'intestazione di richiesta usando curl:
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Ecco un esempio di come usare un comando curl per passare una chiave come stringa di query in un URL:
curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>
Se una chiave obbligatoria non viene passata nell'intestazione o come stringa di query nell'URL, si riceverà una risposta 401 - Accesso negato dal gateway API.