Condividi tramite

Guida dello sviluppatore alla richiesta di autorizzazioni e consenso in Microsoft Identity Platform

Le applicazioni in Microsoft Identity Platform si basano sul consenso per ottenere l'accesso alle risorse o alle API necessarie. Diversi tipi di consenso sono migliori per diversi scenari di applicazione. La scelta dell'approccio migliore per il consenso per l'app consente di ottenere maggiore successo con utenti e organizzazioni.

In questo articolo vengono illustrati i diversi tipi di consenso e come richiedere le autorizzazioni per l'applicazione tramite il consenso.

Annotazioni

Per le applicazioni nei tenant esterni i clienti non possono concedere il consenso alle autorizzazioni stesse. Un amministratore dovrà concedere il consenso per l'applicazione per accedere alle risorse per loro conto. Per altre informazioni, vedere Approva il consenso amministrativo.

Nello scenario di consenso utente statico è necessario specificare tutte le autorizzazioni necessarie nella configurazione dell'app nell'interfaccia di amministrazione di Microsoft Entra. Se l'utente (o l'amministratore, se appropriato) non concede il consenso per questa app, Microsoft Identity Platform chiede all'utente di fornire il consenso in questo momento.

Le autorizzazioni statiche consentono anche agli amministratori di concedere il consenso per conto di tutti gli utenti dell'organizzazione.

Anche se si basa sul consenso statico e un singolo elenco di autorizzazioni mantiene il codice semplice e semplice, significa anche che l'app richiede tutte le autorizzazioni che potrebbe essere necessario in anticipo. Questa impostazione può scoraggiare gli utenti e gli amministratori dall'approvazione della richiesta di accesso dell'app.

Con l'endpoint di Microsoft Identity Platform, è possibile ignorare le autorizzazioni statiche definite nelle informazioni di registrazione dell'applicazione nell'interfaccia di amministrazione di Microsoft Entra. È invece possibile richiedere le autorizzazioni in modo incrementale. È possibile richiedere un set minimo di autorizzazioni prima e richiedere più tempo perché il cliente usa più funzionalità dell'applicazione. A tale scopo, è possibile specificare gli ambiti necessari per l'applicazione in qualsiasi momento includendo i nuovi ambiti nel scope parametro quando si richiede un token di accesso , senza la necessità di definirli nelle informazioni di registrazione dell'applicazione.

Se l'utente non acconsente ai nuovi ambiti aggiunti alla richiesta, riceve una richiesta di consenso solo per le nuove autorizzazioni. Il consenso incrementale o dinamico si applica solo alle autorizzazioni delegate e non alle autorizzazioni dell'applicazione.

Consentire a un'applicazione di richiedere le autorizzazioni in modo dinamico tramite il scope parametro fornisce agli sviluppatori il controllo completo sull'esperienza dell'utente. È possibile caricare in anticipo l'esperienza di consenso e richiedere tutte le autorizzazioni in una richiesta di autorizzazione iniziale. Se l'applicazione richiede un numero elevato di autorizzazioni, è possibile raccogliere tali autorizzazioni dall'utente in modo incrementale quando tentano di usare determinate funzionalità dell'applicazione nel corso del tempo.

Importante

Il consenso dinamico può essere utile, ma presenta una sfida significativa per le autorizzazioni che richiedono il consenso dell'amministratore. L'esperienza di consenso amministratore nei pannelli Registrazioni delle app e Applicazioni aziendali nel portale non riconosce tali autorizzazioni dinamiche al momento del consenso. È consigliabile elencare tutte le autorizzazioni con privilegi di amministratore necessarie per l'applicazione nel portale.

Ciò consente agli amministratori tenant di fornire il consenso per conto di tutti gli utenti nel portale una sola volta. Gli utenti non devono passare attraverso l'esperienza di consenso per tali autorizzazioni per l'accesso. L'alternativa consiste nell'usare il consenso dinamico per tali autorizzazioni. Per concedere il consenso dell'amministratore, un singolo amministratore accede all'app, attiva una richiesta di consenso per le autorizzazioni appropriate e seleziona il consenso per l'intera organizzazione nella finestra di dialogo di consenso.

In una richiesta di autorizzazione OpenID Connect o OAuth 2.0 un'applicazione può richiedere le autorizzazioni necessarie usando il scope parametro di query. Ad esempio, quando un utente accede a un'app, l'applicazione invia una richiesta come nell'esempio seguente. (Le interruzioni di riga vengono aggiunte per la leggibilità).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

Il scope parametro è un elenco separato da spazi di autorizzazioni delegate richieste dall'applicazione. Ogni autorizzazione viene indicata aggiungendo il valore dell'autorizzazione all'identificatore di risorsa (URI dell'ID applicazione). Nell'esempio di richiesta, l'applicazione deve disporre dell'autorizzazione per leggere il calendario dell'utente e inviare messaggi di posta elettronica come utente.

Dopo l'accesso, Microsoft Identity Platform verifica il consenso dell'utente esistente. Se l'utente non approva le autorizzazioni richieste e un amministratore non le approva, la piattaforma chiede all'utente di concedere il consenso.

Nell'esempio seguente l'autorizzazione offline_access ("Mantenere l'accesso ai dati a cui si concede l'accesso") e User.Read l'autorizzazione ("Accedere e leggere il profilo") vengono automaticamente incluse nel consenso iniziale di un'applicazione. Queste autorizzazioni sono necessarie per le funzionalità dell'applicazione appropriate.

L'autorizzazione offline_access concede all'applicazione l'accesso ai token di aggiornamento critici per le app native e le app Web. L'autorizzazione User.Read concede l'accesso alla richiesta sub. Consente al client o all'applicazione di identificare correttamente l'utente nel tempo e di accedere alle informazioni dell'utente rudimentali.

Screenshot di esempio che mostra il consenso dell'account aziendale.

Quando l'utente approva la richiesta di autorizzazione, viene registrato il consenso. L'utente non deve fornire di nuovo il consenso quando accederà successivamente all'applicazione.

La richiesta di consenso per un intero tenant richiede il consenso amministratore. Il consenso amministratore eseguito per conto di un'organizzazione richiede le autorizzazioni statiche registrate per l'app. Impostare tali autorizzazioni nel portale di registrazione delle app se è necessario un amministratore per fornire il consenso per conto dell'intera organizzazione.

Quando l'app richiede autorizzazioni delegate che richiedono il consenso amministratore, gli utenti visualizzano un errore "non autorizzato al consenso" e devono chiedere a un amministratore l'accesso. Quando un amministratore concede il consenso per l'intero tenant, agli utenti non viene richiesto di nuovo se non viene revocato il consenso o vengono aggiunte nuove autorizzazioni.

Gli amministratori che usano la stessa applicazione visualizzano la richiesta di consenso dell'amministratore. La richiesta di consenso dell'amministratore fornisce una casella di controllo che consente di concedere all'applicazione l'accesso ai dati richiesti per conto degli utenti per l'intero tenant. Per altre informazioni sull'esperienza di consenso dell'utente e dell'amministratore, vedere Esperienza di consenso dell'applicazione.

Esempi di autorizzazioni delegate per Microsoft Graph che richiedono il consenso amministratore sono:

  • Lettura dei profili completi di tutti gli utenti tramite User.Read.All
  • Scrittura dei dati in una directory aziendale tramite Directory.ReadWrite.All
  • Lettura di tutti i gruppi in una directory aziendale tramite Groups.Read.All

Per visualizzare l'elenco completo delle autorizzazioni di Microsoft Graph, vedere Informazioni di riferimento sulle autorizzazioni di Microsoft Graph.

È anche possibile configurare le autorizzazioni per le proprie risorse per richiedere il consenso dell'amministratore. Per altre informazioni su come aggiungere ambiti che richiedono il consenso amministratore, vedere Aggiungere un ambito che richiede il consenso amministratore.

Alcune organizzazioni potrebbero modificare i criteri di consenso utente predefiniti per il tenant. Quando l'applicazione richiede l'accesso alle autorizzazioni valutate rispetto a questi criteri. L'utente potrebbe dover richiedere il consenso amministratore anche se non richiesto per impostazione predefinita. Per informazioni su come gli amministratori gestiscono i criteri di consenso per le applicazioni, vedere Gestire i criteri di consenso delle app.

Annotazioni

Nelle richieste di autorizzazione, token o consenso sulla piattaforma di identità di Microsoft, omettere l'identificatore della risorsa nel parametro scope comporta il default su Microsoft Graph. Ad esempio, scope=User.Read viene considerato come https://graph.microsoft.com/User.Read.

Le autorizzazioni dell'applicazione richiedono sempre il consenso amministratore. Le autorizzazioni dell'applicazione non hanno un contesto utente e la concessione del consenso non viene eseguita per conto di un utente specifico. Al contrario, all'applicazione client le autorizzazioni verranno concesse direttamente. Questi tipi di autorizzazioni vengono usati solo dai servizi daemon e da altre applicazioni non interattive eseguite in background. Gli amministratori devono configurare le autorizzazioni iniziali e concedere il consenso amministratore tramite l'interfaccia di amministrazione di Microsoft Entra.

Se l'applicazione che richiede l'autorizzazione è un'applicazione multi-tenant, la registrazione dell'applicazione esiste solo nel tenant in cui è stata creata, pertanto le autorizzazioni non possono essere configurate nel tenant locale. Se l'applicazione richiede autorizzazioni che richiedono il consenso amministratore, l'amministratore deve fornire il consenso per conto degli utenti. Per fornire il consenso a queste autorizzazioni, gli amministratori devono accedere all'applicazione stessa, quindi viene attivata l'esperienza di accesso con il consenso amministratore. Per informazioni su come configurare l'esperienza di consenso amministratore per le applicazioni multi-tenant, vedere Abilitare gli accessi multi-tenant

Un amministratore può concedere il consenso per un'applicazione con le opzioni seguenti.

In genere, quando si compila un'applicazione che richiede il consenso amministratore, l'applicazione richiede una pagina o una visualizzazione in cui l'amministratore può approvare le autorizzazioni dell'app. Questa pagina può essere:

  • Parte del flusso di iscrizione dell'app.
  • Parte delle impostazioni dell'app.
  • Flusso di collegamento dedicato.

In molti casi, è opportuno che l'applicazione mostri la visualizzazione "connetti" solo dopo che un utente ha eseguito l'accesso con un account Microsoft aziendale o un account Microsoft dell'istituto di istruzione.

Quando si accede all'utente nell'app, è possibile identificare l'organizzazione a cui appartiene l'amministratore prima di chiedere loro di approvare le autorizzazioni necessarie. Anche se questo passaggio non è strettamente necessario, può essere utile per creare un'esperienza più intuitiva per gli utenti dell'organizzazione.

Per autenticare l'utente, seguire le esercitazioni sui protocolli di Microsoft Identity Platform.

Richiedere le autorizzazioni nel portale di registrazione dell'app

Nel portale di registrazione delle app le applicazioni possono elencare le autorizzazioni necessarie, incluse le autorizzazioni delegate e le autorizzazioni dell'applicazione. Questa configurazione consente l'uso dell'ambito .default e dell'opzione Concedi consenso amministratore dell'interfaccia di amministrazione di Microsoft Entra.

In generale, le autorizzazioni devono essere definite in modo statico per una determinata applicazione. Devono essere un superset delle autorizzazioni richieste dall'applicazione in modo dinamico o incrementale.

Annotazioni

Le autorizzazioni dell'applicazione possono essere richieste solo tramite .default. Pertanto, se l'applicazione necessita delle autorizzazioni dell'applicazione, assicurarsi che siano elencate nel portale di registrazione delle app.

Per configurare l'elenco delle autorizzazioni richieste in modo statico per un'applicazione:

  1. Accedi al Microsoft Entra admin center come almeno un amministratore di applicazioni cloud.
  2. Passare a Entra ID>Registrazioni app>Tutte le applicazioni.
  3. Selezionare un'applicazione o creare un'app , se non è già stato fatto.
  4. Nella pagina Panoramica dell'applicazione, in Gestisci selezionare Autorizzazioni> APIAggiungi un'autorizzazione.
  5. Selezionare Microsoft Graph nell'elenco delle API disponibili. Aggiungere quindi le autorizzazioni richieste dall'applicazione.
  6. Seleziona Aggiungi autorizzazioni.

Risposta riuscita

Se l'amministratore approva le autorizzazioni per l'app, la risposta con esito positivo sarà simile alla seguente:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Parametro Descrizione
tenant Il tenant della directory, in formato GUID, che ha concesso le autorizzazioni richieste dall'applicazione.
state Valore incluso nella richiesta restituita nella risposta del token. Può trattarsi di una stringa di qualsiasi contenuto. Lo stato viene usato per codificare informazioni sullo stato dell'utente nell'applicazione prima che si sia verificata la richiesta di autenticazione, ad esempio la pagina o la visualizzazione in cui si trovavano.
admin_consent È impostato su True.

Dopo aver ricevuto una risposta corretta dall'endpoint di consenso amministratore, all'applicazione vengono concesse le autorizzazioni richieste. Successivamente, è possibile richiedere un token per la risorsa desiderata.

Risposta di errore

Se l'amministratore non approva le autorizzazioni per l'app, la risposta non riuscita è simile alla seguente:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano. Può anche essere usato per reagire agli errori.
error_description Messaggio di errore specifico che può aiutare uno sviluppatore a identificare la causa radice di un errore.

Dopo il consenso dell'utente alle autorizzazioni per l'app, l'applicazione può acquisire token di accesso che rappresentano l'autorizzazione dell'app ad accedere a una risorsa in una certa capacità. Un token di accesso può essere usato solo per una singola risorsa. Ma codificato all'interno del token di accesso è ogni autorizzazione concessa dall'applicazione per tale risorsa. Per acquisire un token di accesso, l'applicazione può effettuare una richiesta all'endpoint del token di Microsoft Identity Platform, come illustrato di seguito:

POST common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/json

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

È possibile usare il token di accesso risultante nelle richieste HTTP alla risorsa. Indica in modo affidabile alla risorsa che l'applicazione dispone dell'autorizzazione appropriata per eseguire un'attività specifica.

Per altre informazioni sul protocollo OAuth 2.0 e su come ottenere i token di accesso, vedere le informazioni di riferimento sul protocollo endpoint di Microsoft Identity Platform.

Contenuti correlati