Condividi tramite

Consenso amministratore in Microsoft Identity Platform

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ò far parte del flusso di accesso all'app, delle impostazioni dell'app oppure può trattarsi di un flusso di connessione dedicato. In molti casi, è opportuno che l'app mostri questa visualizzazione di connessione solo dopo che un utente ha eseguito l'accesso con un account Microsoft aziendale o dell'istituto di istruzione.

Quando fa accedere l'utente all'app, è possibile identificare l'organizzazione a cui appartiene l'amministratore prima di chiedergli di approvare le autorizzazioni necessarie. Anche se non strettamente necessario, questo può essere utile per creare un'esperienza più intuitiva per gli utenti aziendali.

Richiedere le autorizzazioni da un amministratore della 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=00001111-aaaa-2222-bbbb-3333cccc4444
        &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 Obbligatorio Il tenant della directory da cui si desidera ottenere autorizzazione. Può essere fornito in formato GUID o nome descrittivo OPPURE a cui si fa riferimento in modo generico con 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 Obbligatorio L'ID applicazione (client) che la funzionalità Microsoft Entra admin center – Registrazioni app ha assegnato all'app.
redirect_uri Obbligatorio 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 Obbligatorio 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 sarà simile alla seguente:

http://localhost/myapp/permissions
    ?admin_consent=True
    &tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee
    &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
    &state=12345
Parametro Descrizione
tenant Il tenant della directory, in formato GUID, che ha concesso le autorizzazioni richieste dall'applicazione.
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 informazioni sullo stato dell'utente nell'app prima che si sia verificata la richiesta di autenticazione, ad esempio la pagina o la visualizzazione in cui si trovavano.
scope Set di autorizzazioni a cui è stato concesso l'accesso per l'applicazione.
admin_consent Verrà impostato su True.

Avvertimento

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 di 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+0000aaaa-11bb-cccc-dd22-eeeeee333333%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 può essere usata per reagire agli errori.
error_description Messaggio di errore specifico che può aiutare uno sviluppatore a identificare la causa radice 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 informazioni sullo stato dell'utente nell'app prima che si sia verificata la richiesta di autenticazione, ad esempio la pagina o la visualizzazione in cui si trovavano.
admin_consent Verrà impostato su True per indicare che questa risposta si è verificata in un flusso di consenso amministratore.

Passaggi successivi