Condividi tramite

Protezione API

Quando sei uno sviluppatore e proteggi la tua API, ti concentri sull'autorizzazione. Per chiamare l'API della risorsa, le applicazioni devono acquisire l'autorizzazione dell'applicazione. La risorsa impone l'autorizzazione. In questo articolo vengono illustrate le procedure consigliate per raggiungere gli obiettivi zero trust . Descrive come proteggere l'API tramite registrazione, autorizzazione e definizione del consenso e applicazione dell'accesso.

Registrare l'API protetta

Per proteggere l'API con Microsoft Entra ID (Microsoft Entra ID), registrare l'API. È quindi possibile gestire le API registrate. In Microsoft Entra ID un'API è un'app con impostazioni di registrazione dell'app specifiche che lo definiscono come risorsa o API a cui un'altra applicazione può accedere. Nell'interfaccia di amministrazione di Microsoft Entra, Microsoft Identity Developer, le registrazioni delle app sono API che si trovano nel tenant come API aziendali o servizi di provider di Software-as-a-Service (SaaS) che dispongono di API protette da Microsoft Entra ID.

Durante la registrazione si definisce il modo in cui le applicazioni chiamante fanno riferimento all'API e alle relative autorizzazioni delegate e dell'applicazione. Una registrazione dell'app può rappresentare una soluzione con applicazioni client e API. Tuttavia, in questo articolo viene affrontato lo scenario in cui una risorsa autonoma espone un'API.

In genere, un'API non esegue l'autenticazione o richiede direttamente l'autorizzazione. L'API convalida un token presentato dall'app chiamante. Le API non hanno accessi interattivi, quindi non è necessario registrare impostazioni come l'URI di reindirizzamento o il tipo di applicazione. Le API ottengono i token dalle applicazioni che chiamano tali API, non interagendo con Microsoft Entra ID. Per le API Web, usare i token di accesso OAuth2 per l'autorizzazione. Le API Web convalidano i token di connessione per autorizzare i chiamanti. Non accettare token ID come prova di autorizzazione.

Per impostazione predefinita, Microsoft Entra ID aggiunge User.Read alle autorizzazioni API di qualsiasi nuova registrazione dell'app. Questa autorizzazione viene rimossa per la maggior parte delle API Web. Microsoft Entra ID richiede autorizzazioni API solo quando un'API chiama un'altra API. Se l'API non chiama un'altra API, rimuovi l'autorizzazione User.Read quando registri l'API.

È necessario un identificatore univoco per l'API, noto come URI ID applicazione, che le app client che devono accedere all'API richiedono l'autorizzazione per chiamare l'API. L'URI ID dell'applicazione deve essere univoco tra tutti i tenant di Microsoft Entra. È possibile usare api://<clientId> (il suggerimento predefinito nel portale) dove <clientId> è l'ID applicazione dell'API registrata.

Per fornire agli sviluppatori che chiamano la tua API un nome più user-friendly, è possibile usare l'indirizzo dell'API come URI ID dell'applicazione. Ad esempio, è possibile usare https://API.yourdomain.com dove yourdomain.com è un dominio di pubblicazione configurato nel tenant di Microsoft Entra. Microsoft verifica di avere la proprietà del dominio in modo che sia possibile usarlo come identificatore univoco per l'API. Non è necessario avere codice in questo indirizzo. L'API può essere ovunque si desideri, ma è consigliabile usare l'indirizzo https dell'API come URI ID applicazione.

Definire le autorizzazioni delegate con privilegi minimi

Se le applicazioni con utenti chiamano l'API, definire almeno un'autorizzazione delegata (vedere Aggiungere un ambito nella registrazione dell'app Esporre un'API).

Le API che forniscono l'accesso agli archivi dati dell'organizzazione possono attirare l'attenzione di attori malintenzionati che vogliono accedere a tali dati. Invece di avere una sola autorizzazione delegata, progettare le autorizzazioni con il principio Zero Trust dell'accesso con privilegi minimi . Può essere difficile accedere a un modello con privilegi minimi in un secondo momento se tutte le app client iniziano con l'accesso con privilegi completi.

Spesso, gli sviluppatori rientrano in un modello di uso di una singola autorizzazione, ad esempio accesso come utente o impersonazione utente (che è una frase comune tecnicamente imprecisa). Le singole autorizzazioni, come queste, consentono solo l'accesso con privilegi completi all'API.

Dichiarare ambiti con privilegi minimi in modo che le applicazioni non siano vulnerabili a compromessi o usate per eseguire un'attività che non si intende mai. Definire più ambiti in Autorizzazioni API. Ad esempio, separare gli ambiti dalla lettura e dall'aggiornamento dei dati e prendere in considerazione l'offerta di autorizzazioni di sola lettura. L'accesso in scrittura include privilegi per le operazioni di creazione, aggiornamento ed eliminazione. Un client non dovrebbe mai richiedere l'accesso in scrittura quando deve solo leggere i dati.

Prendere in considerazione le autorizzazioni di accesso standard e completo quando l'API funziona con dati sensibili. Limitare le proprietà sensibili in modo che un'autorizzazione standard non consenta l'accesso , ad esempio Resource.Read. Implementare quindi un'autorizzazione di accesso completa ( ad esempio , Resource.ReadFull) che restituisce proprietà e informazioni riservate.

Valutare sempre le autorizzazioni che si richiedono per garantire di richiedere il set con privilegi minimi assoluti per svolgere il compito. Evitare di richiedere autorizzazioni con privilegi più elevati. Creare invece un'autorizzazione singola per ogni scenario principale. Consultare il riferimento delle autorizzazioni di Microsoft Graph per buoni esempi di questo approccio. Individuare e usare solo il numero corretto di autorizzazioni per soddisfare le proprie esigenze.

Come parte delle definizioni di ambito, decidere se l'intervallo di operazioni che può essere eseguito con un determinato ambito richiede il consenso dell'amministratore.

In progettazione API è possibile fornire indicazioni su quali ambiti possono richiedere in modo sicuro solo il consenso dell'utente. Tuttavia, gli amministratori tenant possono configurare un tenant in modo che tutte le autorizzazioni richiedano il consenso amministratore. Se si definisce un ambito che richiede il consenso dell'amministratore, l'autorizzazione richiede sempre il consenso amministratore.

Quando si decide il consenso dell'utente o dell'amministratore, si hanno queste considerazioni principali:

  • Indica se l'intervallo di operazioni dietro l'autorizzazione influisce su più di un singolo utente. Se l'autorizzazione consente all'utente di scegliere quale applicazione può accedere solo alle proprie informazioni, il consenso dell'utente potrebbe essere appropriato. Ad esempio, l'utente può fornire il consenso per scegliere l'applicazione preferita per la posta elettronica. Tuttavia, se le operazioni dietro l'autorizzazione implicano più di un singolo utente (ad esempio la visualizzazione di profili utente completi di altri utenti), definire tale autorizzazione come richiesta di consenso amministratore.

  • Indica se l'intervallo di operazioni dietro l'autorizzazione ha un ambito ampio. Ad esempio, un ambito generale è quando un'autorizzazione consente a un'app di modificare tutti gli elementi in un tenant o di eseguire un'operazione che potrebbe essere irreversibile. Un ambito generale indica che è necessario il consenso amministratore anziché il consenso dell'utente.

Sii cauto e richiedere il consenso dell'amministratore in caso di dubbi. Descrivere in modo chiaro e conciso le conseguenze del consenso nelle stringhe di autorizzazione. Si supponga che l'utente che legge le stringhe di descrizione non abbia familiarità con le API o il prodotto.

Evitare di aggiungere le API alle autorizzazioni esistenti in modo da modificare la semantica dell'autorizzazione. L'overload delle autorizzazioni esistenti comporta la diluizione del motivo su cui i client hanno precedentemente concesso il consenso.

Definire le autorizzazioni dell'applicazione

Quando si compilano applicazioni non utente, non si ha un utente che può richiedere un nome utente e una password o l'autenticazione a più fattori . Se le applicazioni senza utenti (ad esempio carichi di lavoro, servizi e daemon) chiamano l'API, definire le autorizzazioni dell'applicazione per l'API . Quando si definisce un'autorizzazione dell'applicazione, usare un ruolo applicazione anziché usare gli ambiti.

Come per le autorizzazioni delegate, si forniscono autorizzazioni granulari per le applicazioni in modo che i carichi di lavoro che chiamano l'API possano seguire l'accesso con privilegi minimi e allinearsi ai principi Zero Trust. Evitare di pubblicare un unico ruolo app (autorizzazione dell'app) e un solo ambito (autorizzazione delegata) o di esporre tutte le operazioni a ogni client.

I carichi di lavoro eseguono l'autenticazione con le credenziali client e richiedono un token con l'ambito.default, come illustrato nel codice di esempio seguente.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

Le autorizzazioni richiedono il consenso dell'amministratore quando non è presente alcun utente davanti all'app e quando l'autorizzazione dell'applicazione abilita un'ampia gamma di operazioni.

Imporre l'accesso

Assicurarsi che le API applichino l'accesso convalidando e interpretando i token di accesso che le applicazioni chiamanti forniscono come token di portatore nell'intestazione di autorizzazione https della richiesta. Applicare l'accesso convalidando i token, gestendo l'aggiornamento dei metadati e applicando ambiti e ruoli, come descritto nelle sezioni seguenti.

Convalidare i token

Dopo che l'API riceve un token, assicurarsi che convalida il token. La convalida garantisce che il token provenga dal giusto emittente, intatto e non modificato. Controllare la firma perché non si ottiene il token direttamente da Microsoft Entra ID come si fa con i token ID. Convalidare la firma dopo che l'API riceve un token da un'origine non attendibile nella rete.

Poiché esistono vulnerabilità note relative alla verifica della firma del token Web JSON, usare una libreria di convalida dei token standard ben gestita e stabilita. Le librerie di autenticazione (ad esempio Microsoft.Identity.Web) usano i passaggi appropriati e attenuano le vulnerabilità note.

Opzionalmente, estendere la convalida del token. Usare la dichiarazione ID tenant (tid) per limitare i tenant per cui l'API può ottenere un token. Usare le attestazioni azp e appid per filtrare le app che possono chiamare la tua API. Usare la dichiarazione di oggetto-ID (oid) per limitare ulteriormente l'accesso ai singoli utenti.

Gestire l'aggiornamento dei metadati

Assicurarsi sempre che la libreria di convalida dei token gestisca in modo efficace i metadati necessari. In questo caso, i metadati sono le chiavi pubbliche, la coppia di chiavi private, che Microsoft usa per firmare i token di Microsoft Entra. Quando le librerie convalidano questi token, ottengono l'elenco pubblicato di chiavi di firma pubbliche da un indirizzo Internet noto. Assicurarsi che l'ambiente di hosting abbia la tempistica corretta per ottenere tali chiavi.

Ad esempio, le librerie meno recenti erano talvolta codificate in modo rigido per aggiornare tali chiavi di firma pubblica ogni 24 ore. Prendi in considerazione il momento in cui Microsoft Entra ID deve ruotare rapidamente tali chiavi, e le chiavi che hai scaricato non includevano le nuove chiavi ruotate. L'API potrebbe essere offline per un giorno mentre attende il ciclo di aggiornamento dei metadati. Fare riferimento a indicazioni specifiche per l'aggiornamento dei metadati per assicurarsi di ottenere correttamente i metadati. Se si usa una libreria, assicurarsi che gestisca i metadati entro un intervallo ragionevole.

Applicare ambiti e ruoli

Dopo aver convalidato il token, l'API esamina le attestazioni nel token per determinare il funzionamento.

Per i token di autorizzazione delegati, far esaminare all'API la dichiarazione di ambito (scp) per vedere a cosa è stata data autorizzazione all'applicazione. Esaminare l'ID dell'oggetto (oid) o le attestazioni della chiave del soggetto (sub) per visualizzare l'utente per conto del quale l'applicazione sta lavorando.

Chiedere quindi all'API di verificare che l'utente abbia accesso anche all'operazione richiesta. Se l'API definisce i ruoli per l'assegnazione a utenti e gruppi, verificare la presenza di attestazioni dei ruoli nel token e comportarsi di conseguenza. I token di autorizzazione dell'applicazione non hanno un claim di ambito (scp). Chiedere invece all'API di esaminare l'attestazione dei ruoli per determinare le autorizzazioni dell'applicazione ricevute dal carico di lavoro.

Dopo che l'API convalida il token e gli ambiti ed elabora l'ID oggetto (oid), la chiave del soggetto (sub) e le attestazioni dei ruoli, l'API può restituire i risultati.

Passaggi successivi

  • Last updated on