Proteggere le API usando le sottoscrizioni
Quando si pubblicano le API con Gestione API, è facile e comune proteggere l'accesso a tali API usando le chiavi di sottoscrizione. Gli sviluppatori che devono utilizzare le API pubblicate devono includere una chiave di sottoscrizione valida nelle richieste HTTP quando effettuano chiamate a tali API. In caso contrario, le chiamate vengono rifiutate immediatamente dal gateway di Gestione API. Non vengono inoltrate ai servizi back-end.
Per ottenere una chiave di sottoscrizione per l'accesso alle API, è necessaria una sottoscrizione. Una sottoscrizione è essenzialmente un contenitore denominato per una coppia di chiavi di sottoscrizione. Gli sviluppatori che devono utilizzare le API pubblicate possono ottenere sottoscrizioni. E non è necessaria l'approvazione da parte degli editori delle API. Gli editori delle API possono anche creare sottoscrizioni direttamente per i consumer di API.
Nota
Gestione API supporta anche altri meccanismi per la protezione dell'accesso alle API, tra cui OAuth2.0, certificati client ed elenco di indirizzi IP consentiti.
Sottoscrizioni e chiavi
Una chiave di sottoscrizione è una stringa univoca generata automaticamente che può essere passata nelle intestazioni della richiesta client o come parametro della stringa di query. 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 | Questo ambito 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. |
Le applicazioni che chiamano un'API protetta devono includere la chiave 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.
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 stringa di query nell'URL.
Il nome di 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 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 come è possibile passare una chiave nell'intestazione della richiesta usando curl:
curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path
Ecco un esempio di comando curl 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 riceverà una risposta 401 Accesso negato dal gateway API.