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: legge tutti i profili completi dell'utente
  • Directory.ReadWrite.All: scrivere dati nella directory di un'organizzazione
  • Groups.Read.All: legge tutti i gruppi nella directory di un'organizzazione

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.

Anche se un utente consumer potrebbe concedere a un'applicazione l'accesso a questo tipo di dati, gli utenti dell'organizzazione non possono concedere l'accesso allo stesso set di dati aziendali sensibili. 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 devono 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 Connessione include alcuni ambiti ben definiti ospitati anche in Microsoft Graph: openid, email, profilee offline_access. Gli address ambiti di Connessione e phone OpenID non sono supportati.

Se si richiedono gli ambiti di Connessione OpenID e un token, si otterrà un token per chiamare l'endpoint UserInfo.

Ambito openid

Se un'app accede usando OpenID Connessione, deve richiedere l'ambitoopenid. L'ambito openid viene visualizzato nella pagina di consenso dell'account aziendale come autorizzazione Di accesso .

Usando questa autorizzazione, un'app può ricevere un identificatore univoco per l'utente sotto forma di sub attestazione. L'autorizzazione concede inoltre all'app l'accesso all'endpoint UserInfo. L'ambito openid può essere usato nell'endpoint del token di Microsoft Identity Platform per acquisire i token ID. L'app può usare questi token per l'autenticazione.

Ambito email

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

L'attestazione email è inclusa in un token solo se un indirizzo di posta elettronica è associato all'account utente, che non è sempre il caso. Se l'app usa l'ambito email , l'app deve essere in grado di gestire un caso in cui non esiste alcuna email attestazione nel token.

Ambito profile

L'ambito profile può essere usato con l'ambito openid e qualsiasi altro ambito. Consente all'app di accedere a una grande quantità di informazioni sull'utente. Le informazioni a cui può accedere includono, a titolo esemplificativo, il nome, il cognome, il nome utente preferito e l'ID oggetto dell'utente.

Per un elenco completo delle profile attestazioni disponibili nel id_tokens parametro per un utente specifico, vedere il id_tokens riferimento.

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 del consenso questo ambito viene visualizzato come Mantieni l'accesso ai dati a cui è stato concesso l'accesso all'autorizzazione .

Quando un utente approva l'ambito, l'app offline_access può ricevere token di aggiornamento dall'endpoint del token di 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 quindi 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. Pertanto, quando si riscatta un codice di autorizzazione nel flusso del codice di autorizzazione OAuth 2.0, si riceverà solo un token di accesso dall'endpoint/token.

Il token di accesso è in genere valido per circa un'ora. A questo punto, l'app deve reindirizzare 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 più lunga 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 le informazioni di riferimento sul protocollo di Microsoft Identity Platform.

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 .default di segnali che il consenso deve 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 scope={resource-identifier}/.default è funzionalmente uguale a quello resource={resource-identifier} dell'endpoint v1.0 (dove {resource-identifier} è l'URI dell'identificatore per l'API, ad esempio https://graph.microsoft.com per Microsoft Graph).

L'ambito .default può essere usato in qualsiasi flusso OAuth 2.0 e per avviare il consenso amministratore. Il suo uso è necessario nel flusso On-Behalf-Of e nel flusso delle credenziali client.

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

Il .default parametro scope attiva una richiesta di consenso solo 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 il prompt=consent parametro è stato fornito), 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 tenant ha concesso le autorizzazioni

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

Se il client richiede scope=https://graph.microsoft.com/.default, non viene visualizzata alcuna richiesta di consenso, indipendentemente dal contenuto delle autorizzazioni registrate dell'applicazione 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 registrato 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 Microsoft Graph User.Read e Contacts.Read gli ambiti e per l'ambito di Azure Key Vault user_impersonation . Il token restituito contiene solo gli User.Read ambiti e Contacts.Read e può essere usato solo per Microsoft Graph.

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

In questo esempio l'utente ha già acconsentito a Mail.Read per il client. Il client è stato registrato per l'ambito Contacts.Read .

Il client esegue prima un accesso con scope=https://graph.microsoft.com/.default. In base al scopes parametro 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/.defaulte 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 dell'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 .default ambito. 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 quindi un oggetto id_token, anziché un token di accesso.

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

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. {resource} Ecco 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 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 deve accettare, è consigliabile aggiungere una seconda barra e riprovare.

Vedi anche