Protezione API

Quando si è uno sviluppatore, proteggere l'API, l'obiettivo è l'autorizzazione. Per chiamare l'API della risorsa, le applicazioni devono acquisire l'autorizzazione dell'applicazione. La risorsa stessa deve applicare l'autorizzazione. Questo articolo illustra le procedure consigliate per proteggere l'API tramite la registrazione, la definizione di autorizzazioni e il consenso e l'applicazione dell'accesso per raggiungere gli obiettivi Zero Trust .

Registrare l'API protetta

Per proteggere l'API con Microsoft Entra ID (Microsoft Entra ID) si registrerà prima di tutto l'API, dopo la quale è 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ò essere autorizzata ad accedere. Nell'interfaccia di amministrazione di Microsoft Entra, Microsoft Identity Developer, Registrazioni app, sono API presenti nel tenant come API line-of-business o servizi di provider SaaS con 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, rimuovere l'autorizzazione quando si registra l'API User.Read .

È 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 applicazione deve essere univoco in 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 l'API con un nome più descrittivo, è possibile usare l'indirizzo dell'API come URI ID applicazione. Ad esempio, è possibile usare https://API.yourdomain.com dove yourdomain.com deve essere 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 l'API verrà chiamata dalle applicazioni con utenti, è necessario 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 degli utenti 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 "rappresentazione utente" (che è una frase comune anche se tecnicamente imprecisa). Autorizzazioni singole come queste consentono solo l'accesso completo e con privilegi 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. "Accesso in scrittura" include privilegi per le operazioni di creazione, aggiornamento ed eliminazione. Un client non deve mai richiedere l'accesso in scrittura solo ai dati di lettura.

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 richieste per assicurarsi di cercare il set con privilegi minimi assoluti per eseguire il processo. Evitare di richiedere autorizzazioni con privilegi più elevati. Creare invece un'autorizzazione singola per ogni scenario principale. Per esempi validi di questo approccio, vedere informazioni di riferimento sulle autorizzazioni di Microsoft Graph. Individuare e usare solo il numero corretto di autorizzazioni per soddisfare le proprie esigenze.

Definire il consenso utente e il consenso amministratore

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, sono disponibili due considerazioni principali:

1. 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 comportano più di un singolo utente (ad esempio, la visualizzazione di profili utente completi di altri utenti), definire tale autorizzazione come richiesta di consenso amministratore.

2. 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.

Err sul lato conservatore e richiedere il consenso 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 creano 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, è necessario definire le autorizzazioni dell'applicazione per l'API. Quando si definisce un'autorizzazione dell'applicazione, si usa 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 solo ruolo app (autorizzazione dell'app) e un ambito (autorizzazione delegata) o esporre tutte le operazioni a ogni client.

I carichi di lavoro eseguono l'autenticazione con le credenziali client e richiedono un token usando 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.

Applicare l'accesso

Assicurarsi che le API applichino l'accesso convalidando e interpretando i token di accesso che chiamano le applicazioni forniscono come token di connessione nell'intestazione di autorizzazione della richiesta HTTPS. È possibile 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, deve convalidare il token. La convalida garantisce che il token provenga dall'autorità emittente appropriata come non modificato e non modificato. Controllare la firma perché non si ottiene il token direttamente da Microsoft Entra ID come si fa con i token ID 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.

Facoltativamente, estendere la convalida del token. Usare l'attestazione ID tenant (tid) per limitare i tenant in cui l'API può ottenere un token. Usare le azp attestazioni e appid per filtrare le app che possono chiamare l'API. Usare l'attestazione ID oggetto (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 sono state occasionalmente hardcoded per aggiornare tali chiavi di firma pubblica ogni 24 ore. Prendere in considerazione quando Microsoft Entra ID deve ruotare rapidamente tali chiavi e le chiavi scaricate 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, chiedere all'API di esaminare l'attestazione di ambito (scp) per vedere cosa deve fare l'applicazione. Esaminare l'ID oggetto () o le attestazioni della chiave dell'oggetto (oidsub) per visualizzare l'utente per conto dell'applicazione.

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'attestazione 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

• Un esempio di API protetta dal framework di consenso delle identità Microsoft consente di progettare strategie di autorizzazioni dell'applicazione con privilegi minimi per un'esperienza utente ottimale.
• Chiamare un'API da un'altra API consente di garantire Zero Trust quando si dispone di un'API che deve chiamare un'altra API e sviluppare in modo sicuro l'applicazione quando lavora per conto di un utente.
• Personalizzare i token descrive le informazioni che è possibile ricevere nei token di Microsoft Entra. Spiega come personalizzare i token per migliorare la flessibilità e il controllo aumentando al contempo la sicurezza senza attendibilità delle applicazioni con privilegi minimi.
• Configurare le attestazioni di gruppo e i ruoli dell'app nei token illustra come configurare le app con definizioni di ruolo dell'app e assegnare gruppi di sicurezza ai ruoli dell'app. Questi metodi consentono di migliorare la flessibilità e il controllo aumentando la sicurezza senza attendibilità delle applicazioni con privilegi minimi.
• Acquisire l'autorizzazione per accedere alle risorse consente di comprendere come garantire al meglio Zero Trust durante l'acquisizione delle autorizzazioni di accesso alle risorse per l'applicazione.
• Richiedere autorizzazioni che richiedono il consenso amministrativo descrive l'autorizzazione e l'esperienza di consenso quando le autorizzazioni dell'applicazione richiedono il consenso amministrativo.
• In questa guida introduttiva: Proteggere un'API Web con Microsoft Identity Platform, informazioni su come proteggere un'API Web ASP.NET limitando l'accesso alle risorse solo agli account autorizzati.
• In questa esercitazione: Trasformare e proteggere l'API in Azure Gestione API, informazioni sulla configurazione di criteri comuni per nascondere le informazioni sullo stack di tecnologie o gli URL originali nella risposta HTTP dell'API.