Consenso amministratore in Microsoft Identity Platform

  • Articolo

Alcune autorizzazioni richiedono il consenso di un amministratore prima di poter essere concesse all'interno di un tenant. È anche possibile usare l'endpoint di consenso amministratore per concedere le autorizzazioni a un intero tenant.

In genere, durante la compilazione di un'applicazione che usa l'endpoint di consenso dell'amministratore, l'app necessita di una pagina o vista che consenta all'amministratore di approvare le autorizzazioni dell'applicazione. Questa pagina può essere parte del flusso di iscrizione all'app, delle impostazioni dell'applicazione o di un flusso di "connessione" dedicato. In molti casi, è utile per l'applicazione visualizzare la pagina di "connessione" solo dopo che un utente ha eseguito l'accesso con un account di lavoro o dell'istituto di istruzione Microsoft.

L'accesso dell'utente nell'app consente di identificarne l'organizzazione di appartenenza dell'amministratore prima di richiedere l'approvazione delle autorizzazioni necessarie. Sebbene non sia strettamente necessario, questo consente di creare un'esperienza più intuitiva per gli utenti dell'organizzazione.

Richiedere le autorizzazioni da un amministratore di directory

Quando si è pronti per richiedere le autorizzazioni all'amministratore dell'azienda, è possibile reindirizzare l'utente all'endpoint di consenso amministratore di Microsoft Identity Platform.

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
        ?client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
        &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
        &redirect_uri=http://localhost/myapp/permissions
        &state=12345
Parametro Condizione Descrizione
tenant Richiesto Il tenant della directory da cui si desidera richiedere autorizzazioni. Può essere specificato in formato di GUID o nome descrittivo OPPURE con il riferimento generico organizations come illustrato nell'esempio. Non usare "common", perché gli account personali non possono fornire il consenso amministratore tranne nel contesto di un tenant. Per garantire la massima compatibilità con gli account personali che gestiscono i tenant, usare l'ID tenant quando possibile.
client_id Richiesto ID applicazione (client) assegnato all'app dall'interfaccia di amministrazione Registrazioni app di Microsoft Entra.
redirect_uri Richiesto URI di reindirizzamento in cui si desidera che venga inviata la risposta per la gestione da parte dell'app. Deve corrispondere esattamente a uno degli URI di reindirizzamento registrati nel portale di registrazione delle applicazioni.
state Consigliato Valore incluso nella richiesta che verrà restituito anche nella risposta del token. Può trattarsi di una stringa di qualsiasi contenuto. Usare questo stato per codificare le informazioni sullo stato dell'utente nell'app prima dell'esecuzione della richiesta di autenticazione, ad esempio la pagina o la vista in cui si trovava.
scope Richiesto Definisce il set di autorizzazioni che vengono richieste dall'applicazione. Può essere statico (usando /.default) o ambiti dinamici. Può includere gli ambiti OIDC (openid, profile, email).

A questo punto, Microsoft Entra ID richiede a un amministratore tenant di accedere per completare la richiesta. All'amministratore viene chiesto di approvare tutte le autorizzazioni richieste nel scope parametro . Se è stato usato un valore statico (/.default), funzionerà come l'endpoint di consenso amministratore v1.0 e richiederà il consenso per tutti gli ambiti presenti nelle autorizzazioni necessarie (sia utente che app). Per richiedere le autorizzazioni dell'app, è necessario usare il /.default valore . Se non si vuole che gli amministratori visualizzino una determinata autorizzazione nella schermata di consenso amministratore per tutto il tempo in cui si usa /.default, la procedura consigliata consiste nel non inserire l'autorizzazione nella sezione autorizzazioni necessarie. È invece possibile usare il consenso dinamico per aggiungere le autorizzazioni che si desidera includere nella schermata di consenso in fase di esecuzione, anziché usare /.default.

Risposta riuscita

Se l'amministratore approva le autorizzazioni per l'app, la risposta con esito positivo si presenta come segue:

http://localhost/myapp/permissions
    ?admin_consent=True
    &tenant=fa00d692-e9c7-4460-a743-29f2956fd429
    &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
    &state=12345
Parametro Descrizione
tenant Tenant della directory che ha concesso all'applicazione le autorizzazioni richieste, in formato GUID.
state Valore incluso nella richiesta che verrà restituito anche nella risposta del token. Può trattarsi di una stringa di qualsiasi contenuto. Lo stato viene usato per codificare le informazioni sullo stato dell'utente nell'app prima dell'esecuzione della richiesta di autenticazione, ad esempio la pagina o la vista in cui si trovava.
scope Set di autorizzazioni a cui è stato concesso l'accesso per l'applicazione.
admin_consent Sarà impostato su True.

Avviso

Non usare mai il valore ID tenant del tenant parametro per autenticare o autorizzare gli utenti. Il valore dell'ID tenant può essere aggiornato e inviato da attori malintenzionati per rappresentare una risposta all'app. Ciò può causare l'esposizione dell'applicazione agli eventi imprevisti di sicurezza.

Risposta con errore

http://localhost/myapp/permissions
        ?admin_consent=True
        &error=consent_required
        &error_description=AADSTS65004%3a+The+resource+owner+or+authorization+server+denied+the+request.%0d%0aTrace+ID%3a+d320620c-3d56-42bc-bc45-4cdd85c41f00%0d%0aCorrelation+ID%3a+8478d534-5b2c-4325-8c2c-51395c342c89%0d%0aTimestamp%3a+2019-09-24+18%3a34%3a26Z
        &state=12345

L'aggiunta ai parametri visualizzati in una risposta con esito positivo, i parametri di errore vengono visualizzati di seguito.

Parametro Descrizione
error Stringa di codice di errore che può essere usata per classificare i tipi di errori che si verificano e correggerli.
error_description Messaggio di errore specifico che consente a uno sviluppatore di identificare la causa principale di un errore.
state Valore incluso nella richiesta che verrà restituito anche nella risposta del token. Può trattarsi di una stringa di qualsiasi contenuto. Lo stato viene usato per codificare le informazioni sullo stato dell'utente nell'app prima dell'esecuzione della richiesta di autenticazione, ad esempio la pagina o la vista in cui si trovava.
admin_consent Verrà impostato su True per indicare che questa risposta si è verificata in un flusso di consenso amministratore.

Passaggi successivi