Ambiti e autorizzazioni in Microsoft Identity Platform

  • Articolo

Microsoft Identity Platform implementa il protocollo di autorizzazione OAuth 2.0. OAuth 2.0 è un metodo tramite cui un'applicazione di terze parti può accedere alle risorse ospitate sul Web per conto di un utente. Tutte le risorse ospitate sul Web che si integrano con Microsoft Identity Platform possiedono un identificatore o URI dell'ID applicazione.

Questo articolo illustra gli ambiti e le autorizzazioni in Identity Platform.

L'elenco seguente mostra alcuni esempi di risorse ospitate sul Web Microsoft:

  • Microsoft Graph: https://graph.microsoft.com
  • Microsoft 365 Mail API: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

Lo stesso vale per le risorse di terze parti integrate con Microsoft Identity Platform. Tutte queste risorse possono anche definire un set di autorizzazioni da usare per dividere la funzionalità di tale risorsa in blocchi più piccoli. Ad esempio, Microsoft Graph ha definito le autorizzazioni per eseguire le attività seguenti, tra le altre:

  • Lettura del calendario dell'utente
  • Scrittura nel calendario dell'utente
  • Invio di messaggi di posta elettronica come utente

Grazie a questi tipi di definizione di autorizzazione, la risorsa può avere un controllo accurato dei dati e dell'esposizione delle funzionalità API. Un'app di terze parti può richiedere queste autorizzazioni da utenti e amministratori, che devono approvare la richiesta prima che l'app possa accedere ai dati o agire per conto di un utente.

Quando una funzionalità della risorsa è suddivisa in set di autorizzazioni di dimensioni minori, è possibile creare le app di terze parti affinché vengano richieste solo le autorizzazioni necessarie per il relativo funzionamento. Utenti e amministratori possono conoscere i dati a cui l’applicazione può accedere. E possono essere più sicuri che l'app non si comporta con finalità dannose. Gli sviluppatori dovrebbero sempre seguire il principio del privilegio minimo, chiedendo solo le autorizzazioni necessarie per il funzionamento dell'applicazione.

In OAuth 2.0 questi tipi di set di autorizzazioni sono denominati ambiti. Spesso anche autorizzazioni. In Microsoft Identity Platform un'autorizzazione è rappresentata come valore stringa. Un'applicazione richiede le autorizzazioni necessarie specificandole nel parametro di query scope. Identity Platform supporta diversi ambiti di OpenID Connect ben definiti e le autorizzazioni basate sulle risorse (ogni autorizzazione è indicata aggiungendo il valore dell'autorizzazione all'identificatore di risorsa o all'URI dell'ID applicazione). La stringa di autorizzazione https://graph.microsoft.com/Calendars.Read, ad esempio, viene usata per richiedere l'autorizzazione per leggere i calendari dell'utente in Microsoft Graph.

Nelle richieste al server di autorizzazione, per Microsoft Identity Platform, se l'identificatore della risorsa viene omesso nel parametro di ambito, si presuppone che la risorsa sia Microsoft Graph. Ad esempio, scope=User.Read equivale a https://graph.microsoft.com/User.Read.

Autorizzazioni riservate all'amministratore

Le autorizzazioni in Microsoft Identity Platform possono essere impostate su restrizioni per l'amministratore. Ad esempio, molte autorizzazioni con privilegi più elevati di Microsoft Graph richiedono l'approvazione dell'amministratore. Se l'app richiede autorizzazioni con restrizioni di amministratore, l'amministratore di un'organizzazione deve fornire il consenso a tali ambiti per conto degli utenti dell'organizzazione. La sezione seguente fornisce esempi di questi tipi di autorizzazioni:

  • User.Read.All: lettura dei profili completi di tutti gli utenti
  • Directory.ReadWrite.All: scrittura di dati in una directory aziendale
  • Groups.Read.All: lettura di tutti i gruppi nella directory aziendale

Nota

Nelle richieste agli endpoint di autorizzazione, token o consenso per Microsoft Identity Platform, se l'identificatore della risorsa viene omesso nel parametro di ambito, si presuppone che la risorsa sia Microsoft Graph. Ad esempio, scope=User.Read equivale a https://graph.microsoft.com/User.Read.

Sebbene un utente consumer possa concedere a un'applicazione l'accesso a questi tipi di dati, gli utenti aziendali non possono concedere accesso allo stesso set di dati riservati dell'azienda. Se l'applicazione richiede l'accesso a una di queste autorizzazioni da un utente dell'organizzazione, l'utente riceve un messaggio di errore che indica che non è autorizzato a fornire il consenso alle autorizzazioni dell'applicazione.

Se l'applicazione richiede le autorizzazioni dell'applicazione e un amministratore concede queste autorizzazioni, questa concessione non viene eseguita per conto di un utente specifico. Al contrario, all'applicazione client le autorizzazioni verranno concesse direttamente. Questi tipi di autorizzazioni dovrebbero essere usati solo dai servizi daemon e da altre applicazioni non interattive eseguite in background. Per altre informazioni sullo scenario di accesso diretto, vedere Scenari di accesso in Microsoft Identity Platform.

Per una guida dettagliata su come esporre gli ambiti in un'API Web, vedere Configurare un'applicazione per esporre un'API Web.

Ambiti di OpenID Connect

L'implementazione di Microsoft Identity Platform di OpenID Connect include alcuni ambiti ben definiti ospitati anche in Microsoft Graph: openid, email profile, e offline_access. Gli ambiti address e phone di OpenID Connect non sono supportati.

Se si richiedono gli ambiti openID Connect e un token, si otterrà un token per chiamare l'endpoint UserInfo.

L'ambito openid

Se un'app esegue l'accesso usando OpenID Connect, deve richiedere l'ambito openid. L'ambito openid viene visualizzato nella pagina di consenso dell'account aziendale come autorizzazione Accesso per te.

Questa autorizzazione consente a un'app di ricevere un identificatore univoco per l'utente sotto forma di attestazione sub. L’autorizzazione concede inoltre all'app l'accesso all'endpoint delle informazioni utente. È possibile usare l'ambito openid nell'endpoint del token di Microsoft Identity Platform per acquisire i token ID. L'app può usare questi token per l'autenticazione.

L'ambito email

L'ambito email può essere usato con l'ambito openid e con tutti gli altri. Consente all'applicazione di accedere all'indirizzo di posta elettronica primario dell'utente sotto forma di attestazione email.

L'attestazione email è inclusa nei token solo quando un indirizzo e-mail è associato all'account utente, condizione che non è sempre vera. Se l'app usa l'ambito email, deve essere in grado di gestire un caso in cui non esiste alcuna attestazione email nel token.

L'ambito profile

L'ambito profile può essere usato con l'ambito openid e con tutti gli altri. Consente all'applicazione di accedere a numerose informazioni sull'utente. tra cui il nome e il cognome dell'utente, il nome utente preferito, l'ID dell'oggetto e così via.

Per un elenco completo delle attestazioni profile disponibili nel parametro id_tokens per un determinato utente, vedere le id_tokensinformazioni di riferimento.

L'ambito offline_access

L'ambito offline_access consente all'app di accedere alle risorse per conto dell'utente per un periodo di tempo prolungato. Nella pagina di consenso l'ambito viene visualizzato come autorizzazione Conservazione dell'accesso ai dati per cui è stato autorizzato l'accesso.

Quando un utente approva l'ambito offline_access, l'app è in grado di ricevere token di aggiornamento dall'endpoint del token Microsoft Identity Platform. I token di aggiornamento sono di lunga durata. L'applicazione può ottenere nuovi token di accesso quando i vecchi scadono.

Nota

Questa autorizzazione viene attualmente visualizzata in tutte le pagine di consenso, anche per i flussi che non forniscono un token di aggiornamento (ad esempio il flusso implicito). Questa configurazione risolve gli scenari in cui un client può iniziare all'interno del flusso implicito e successivamente passare al flusso di codice in cui è previsto un token di aggiornamento.

In Microsoft Identity Platform (richieste effettuate all'endpoint v2.0), l'app deve richiedere in modo esplicito l'ambito offline_access per ricevere i token di aggiornamento. Ciò significa che, quando si riscatta un codice di autorizzazione nel flusso del codice di autorizzazione OAuth 2.0, si riceve solo un token di accesso dall'endpoint /token.

Il token di accesso è in genere valido per circa un'ora. A questo punto, l'app reindirizza l'utente all'endpoint /authorize per richiedere un nuovo codice di autorizzazione. Durante questo reindirizzamento e a seconda del tipo di app, l'utente potrebbe dover immettere di nuovo le credenziali o fornire di nuovo il consenso per le autorizzazioni.

Il token di aggiornamento ha una scadenza maggiore rispetto al token di accesso ed è in genere valido per un giorno. Per altre informazioni su come ottenere e usare i token di aggiornamento, vedere il riferimento al protocollo di Microsoft Identity Platform.

L'inclusione del token di aggiornamento nella risposta può dipendere da diversi fattori, tra cui la configurazione specifica dell'applicazione e gli ambiti richiesti durante il processo di autorizzazione. Se si prevede di ricevere un token di aggiornamento nella risposta ma non è possibile, considerare i fattori seguenti:

  • Requisiti di ambito: assicurarsi di richiedere gli offline_access ambiti insieme ad altri ambiti necessari.
  • Tipo di concessione di autorizzazione: il token di aggiornamento viene generalmente fornito quando si usa il tipo di concessione del codice di autorizzazione. Se il flusso è diverso, può influire sulla risposta.
  • Configurazione client: controllare le impostazioni dell'applicazione in Identity Platform. Alcune configurazioni possono limitare il rilascio di refresh_tokens.

L'ambito .default

L'ambito .default viene usato per fare riferimento genericamente a un servizio risorse (API) in una richiesta, senza identificare autorizzazioni specifiche. Se è necessario il consenso, l’uso di .default segnala che il consenso dovrebbe essere richiesto per tutte le autorizzazioni necessarie elencate nella registrazione dell'applicazione (per tutte le API nell'elenco).

Il valore del parametro di ambito viene costruito usando l'URI dell'identificatore per la risorsa e .default, separati da una barra (/). Ad esempio, se l'URI dell'identificatore della risorsa è https://contoso.com, l'ambito da richiedere è https://contoso.com/.default. Per i casi in cui è necessario includere una seconda barra per richiedere correttamente il token, vedere la sezione relativa alle barre finali.

L'uso di scope={resource-identifier}/.default è funzionalmente uguale a resource={resource-identifier} nell'endpoint v1.0 (dove {resource-identifier} è l'URI dell'identificatore per l'API, ad esempio https://graph.microsoft.com per Microsoft Graph).

È possibile usare l'ambito .default in qualsiasi flusso OAuth 2.0 e per avviare il consenso dell’amministratore. Il relativo uso è necessario nel flusso On-Behalf-Of e in quello delle credenziali del client.

I client non possono combinare consenso statico (.default) e consenso dinamico in una singola richiesta. scope=https://graph.microsoft.com/.default Mail.Read genera quindi un errore poiché combina più tipi di ambito.

Il parametro ambito .default attiva solo una richiesta di consenso se il consenso non è stato concesso per alcuna autorizzazione delegata tra il client e la risorsa, per conto dell'utente connesso.

Se esiste il consenso, il token restituito contiene tutti gli ambiti concessi per tale risorsa per l'utente connesso. Tuttavia, se non è stata concessa alcuna autorizzazione per la risorsa richiesta (o se è stato specificato il parametro prompt=consent), viene visualizzata una richiesta di consenso per tutte le autorizzazioni necessarie configurate per la registrazione dell'applicazione client, per tutte le API nell'elenco.

Ad esempio, se viene richiesto l'ambito https://graph.microsoft.com/.default, l'applicazione richiede un token di accesso per l'API Microsoft Graph. Se per conto dell'utente connesso è stata concessa almeno un'autorizzazione delegata per conto dell'utente connesso, l'accesso continuerà e tutte le autorizzazioni delegate di Microsoft Graph concesse per tale utente verranno incluse nel token di accesso. Se non sono state concesse autorizzazioni per la risorsa richiesta (Microsoft Graph, in questo esempio), verrà visualizzata una richiesta di consenso per tutte le autorizzazioni necessarie configurate per l'applicazione, per tutte le API nell'elenco.

Esempio 1: l'utente o l'amministratore del tenant ha concesso le autorizzazioni

In questo esempio, l'utente o un amministratore tenant ha concesso al client le autorizzazioni di Microsoft Graph Mail.Read e User.Read al client.

Se il client richiede scope=https://graph.microsoft.com/.default, non è visualizzata alcuna richiesta di consenso indipendentemente dal contenuto delle autorizzazioni registrate delle applicazioni client per Microsoft Graph. Il token restituito contiene gli ambiti Mail.Read e User.Read.

Esempio 2: l'utente non ha concesso autorizzazioni tra il client e la risorsa

In questo esempio l'utente non ha concesso il consenso tra il client e Microsoft Graph, né ha un amministratore. Il client ha eseguito la registrazione per le autorizzazioni User.Read e Contacts.Read. Ha anche registrato per l'ambito https://vault.azure.net/user_impersonationdi Azure Key Vault.

Quando il client richiede un token per scope=https://graph.microsoft.com/.default, l'utente visualizza una pagina di consenso per gli ambiti User.Read e Contacts.Read di Microsoft Graph e per l'ambito user_impersonation di Azure Key Vault. Il token restituito contiene solo gli ambiti User.Read e Contacts.Read e può essere usato solo in Microsoft Graph.

Esempio 3: L'utente ha acconsentito e il client richiede più ambiti

In questo esempio, l'utente ha già dato il consenso per Mail.Read per il client. Il client ha eseguito la registrazione per l'ambito Contacts.Read.

Il client esegue prima un accesso con scope=https://graph.microsoft.com/.default. In base al parametro scopes della risposta, il codice dell'applicazione rileva che è stato concesso solo Mail.Read. Il client avvia quindi un secondo accesso usando scope=https://graph.microsoft.com/.default e questa volta forza il consenso usando prompt=consent. Se l'utente è autorizzato a fornire il consenso per tutte le autorizzazioni registrate dall'applicazione, verrà visualizzata la richiesta di consenso. (in caso contrario, verranno visualizzati un messaggio di errore o il modulo di richiesta di consenso amministratore). Sia Contacts.Read che Mail.Read saranno nella richiesta di consenso. Se viene concesso il consenso e l'accesso continua, il token restituito è per Microsoft Graph e contiene Mail.Read e Contacts.Read.

Uso dell'ambito .default con il client

In alcuni casi, un client può richiedere il proprio ambito .default. L'esempio seguente illustra questo scenario.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Questo esempio di codice genera una pagina di consenso per tutte le autorizzazioni registrate se le descrizioni precedenti del consenso e .default si applicano allo scenario. Il codice restituisce successivamente un oggetto id_token, anziché un token di accesso.

Questa configurazione non dovrebbe essere usata dai nuovi client destinati a Microsoft Identity Platform. Assicurarsi di eseguire la migrazione a Microsoft Authentication Library (MSAL) da Azure AD Authentication Library (ADAL).

Diagramma del flusso di concessione delle credenziali client e .default

Un altro uso di .default consiste nel richiedere ruoli dell'app (noti anche come autorizzazioni dell'applicazione) in un'applicazione non interattiva come un'app daemon che usa il flusso di concessione delle credenziali client per chiamare un'API Web.

Per definire i ruoli dell'app (autorizzazioni dell'applicazione) per un'API Web, vedere Aggiungere ruoli dell'app nell'applicazione.

Le richieste di credenziali client nel servizio client devono includere scope={resource}/.default. In questo caso, {resource} è l'API Web per cui l'app intende chiamare e vuole ottenere un token di accesso. L'emissione di una richiesta di credenziali client tramite le singole autorizzazioni dell'applicazione (ruoli) non è supportata. Tutti i ruoli dell'app (autorizzazioni dell'applicazione) concessi per tale API Web sono inclusi nel token di accesso restituito.

Per concedere l'accesso ai ruoli dell'app definiti, inclusa la concessione del consenso amministratore per l'applicazione, vedere Configurare un'applicazione client per accedere a un'API Web.

Barra finale e .default

Alcuni URI di risorsa hanno una barra finale, ad esempio https://contoso.com/ anziché https://contoso.com. La barra finale può causare problemi con la convalida del token. I problemi si verificano principalmente quando viene richiesto un token per Azure Resource Manager (https://management.azure.com/).

In questo caso, una barra finale sull'URI della risorsa indica che la barra deve essere presente quando viene richiesto il token. Pertanto, quando si richiede un token per https://management.azure.com/ e si usa .default, è necessario richiedere https://management.azure.com//.default (si noti la doppia barra!).

In generale, se si verifica che il token venga emesso e se il token viene rifiutato dall'API che lo dovrebbe accettare, è consigliabile aggiungere una seconda barra e riprovare.

Vedi anche