VENDITE: 1-800-867-1389

Uso dell'API Graph per effettuare query su Azure AD

Aggiornamento: maggio 2014

noteNota
NOTA: Questo esempio è obsoleto. La tecnologia, i metodi e/o le istruzioni dell'interfaccia utente sono stati sostituiti da nuove funzionalità. Per un esempio aggiornato che consente di creare un'applicazione simile, vedere WebApp-GraphAPI-DotNet.

Questa applicazione di esempio è destinata agli sviluppatori .NET che desiderano aggiungere un'applicazione a quelle esistenti o creare nuove applicazioni per Microsoft Azure Active Directory (Microsoft Azure AD). Questa procedura dettagliata è basata sul risultato ottenuto mediante la procedura descritta in Aggiunta del processo di accesso nell'applicazione Web tramite Microsoft Azure AD, in cui sono riportate le istruzioni per la generazione di un'app di esempio che illustra come offrire un'esperienza utente Web Single Sign-On ai clienti Microsoft Azure AD. In questa procedura dettagliata viene mostrato come usare l'API Microsoft Azure AD Graph per la lettura dei dati della directory. L'API Graph è un'API RESTful che consente alle applicazioni di accedere ai dati della directory dei clienti di Azure.

L'accesso delle applicazioni ai dati della directory è richiesto in numerosi scenari, ad esempio:

  • Recupero di elenchi di utenti, gruppi, contatti per utenti o gruppi selezionati

  • Lettura di informazioni dettagliate su tenant, utenti e gruppi

  • Verifica dell'appartenenza a gruppi

  • Modifica di utenti, gruppi e appartenenza a gruppi

  • Aggiornamento delle password utente

  • Disabilitazione degli account utente

noteNota
Quando un'applicazione multi-tenant tenta di acquisire un token per accedere all'API Graph per un tenant di Azure AD che ha autorizzato l'applicazione di recente, la richiesta del token potrebbe avere esito negativo con codice di errore ACS50012. Per risolvere il problema, attendere qualche minuto e ripetere l'operazione. In alternativa, chiedere all'amministratore di tenant che ha fornito il consenso di accedere all'applicazione dopo il consenso. Per ulteriori informazioni, vedere Codici di errore di ACS.

Questo documento è costituito dalle seguenti sezioni:

Per completare l'esercitazione, verificare che siano soddisfatti i seguenti prerequisiti:

Al termine di questa procedura dettagliata, si disporrà di un'applicazione configurata per la lettura dei dati dal tenant di Azure AD. L'applicazione è in grado di leggere le seguenti entità della directory: utenti, gruppi, contatti, informazioni sulla società, licenze e ruoli. Inoltre, se vengono concesse autorizzazioni di scrittura, l'applicazione è anche in grado di aggiornare le entità.

In questa applicazione di esempio verrà esaminato come leggere i dati della directory dalla società di Azure AD. Di seguito sono riportati alcuni argomenti aggiuntivi di approfondimento:

  • Recupero di dettagli utente completi

  • Creazione e aggiornamento di utenti

  • Recupero di un elenco di gruppi

  • Aggiornamento dell'appartenenza a gruppi

L'esperienza Single Sign-On rimane invariata dopo l'aggiornamento dell'applicazione in modo da consentire l'accesso all'API Graph. Dopo l'autenticazione utente, l'applicazione richiede un token all'endpoint di autenticazione di Azure AD e, se l'esito è positivo, usa il token nelle chiamate all'API Graph per ottenere tutti gli utenti dal tenant. Nell'applicazione viene visualizzato un elenco di utenti con i relativi Display Names e User Principal Names.

Architettura della soluzione

In questa procedura dettagliata verrà usato il flusso delle credenziali client OAuth 2.0 per autenticare l'applicazione. Prima di accedere all'endpoint dell'API Graph, l'applicazione deve acquisire un token valido dall'endpoint di autenticazione di Azure AD, presentando credenziali valide (ID e chiave privata client). In caso di convalida delle credenziali, all'applicazione viene restituito un token firmato. A partire da questo momento, il token viene incluso automaticamente nell'intestazione dell'autorizzazione delle chiamate all'API Graph. Il servizio API Graph convalida il token nella richiesta in ingresso e, se l'esito è positivo, viene eseguito un controllo dell'autorizzazione.

L'autorizzazione dell'applicazione viene verificata dall'API Graph e dal servizio di controllo di accesso basato sui ruoli (RBAC) sottostante. Le chiamate all'API Graph sono limitate dalle autorizzazioni dell'applicazione. Se l'autenticazione e l'autorizzazione hanno esito positivo, all'applicazione vengono restituiti i dati.

La configurazione dell'autenticazione e dell'autorizzazione di un'applicazione viene archiviata in Azure AD mediante un oggetto Service Principal presente nella directory del tenant. Le applicazioni sono rappresentate in Azure AD da un oggetto Service Principal con identità, credenziali e autorizzazioni univoche. Questo è simile agli oggetti User Principal di Active Directory che rappresentano gli utenti, ognuno dei quali dispone di identità, credenziali e autorizzazioni univoche.

L'oggetto Service Principal di un'applicazione dispone di un ID e di una chiave privata univoci che vengono usati per l'autenticazione. L'autorizzazione viene gestita aggiungendo l'entità servizio dell'applicazione a un ruolo che dispone delle autorizzazioni necessarie. Gli amministratori di tenant possono creare le entità servizio dell'applicazione e aggiungerle ai ruoli nel portale di gestione di Azure AD. Facoltativamente, possono usare anche Windows PowerShell per gestire le entità servizio. Per ulteriori informazioni, vedere Gestione di Windows Azure Active Directory con Windows PowerShell

Nella procedura dettagliata Aggiunta del processo di accesso nell'applicazione Web tramite Microsoft Azure AD sono state configurate le autorizzazioni dell'app nel portale di gestione di Azure AD in modo da consentire l'accesso Single Sign-On tramite le credenziali utente di Azure AD. A questo punto è necessario aggiornare la configurazione dell'applicazione per consentire all'applicazione Expense Reporting di eseguire l'autenticazione e ottenere l'autorizzazione per chiamare l'API Graph. Verranno effettuate le seguenti operazioni:

  • Autorizzazione: configurare le autorizzazioni dell'app per consentire l'accesso in lettura/scrittura alla directory.

  • Autenticazione: ottenere una chiave dell'applicazione, corrispondente alla password, che viene usata per autenticare l'applicazione nell'API Graph.

  1. Passare al portale di gestione di Microsoft Azure (https://manage.WindowsAzure.com), eseguire l'accesso, quindi fare clic su Active Directory. (Suggerimento per la risoluzione dei problemi: elemento "Active Directory" mancante o non disponibile)

  2. Per selezionare la directory, fare clic su Applicazioni, quindi sull'applicazione di esempio Expense Reporting creata durante la procedura dettagliata di Single Sign-On.



    Accesso esterno

  3. Nella parte inferiore della pagina fare clic su Gestisci accesso.

  4. Selezionare Modifica l'accesso alla directory per questa app.



    Come procedere
  5. Selezionare Single Sign-On, Lettura dati directory. Fare quindi clic sul segno di spunta per salvare le modifiche.



    Accesso alla directory

  1. Nella pagina dell'applicazione Expense Reporting espandere Consenti all'app di leggere o scrivere i dati della directory. Nella sezione Crea una chiave selezionare Configura chiave.



    Configura chiave

  2. Per aggiungere una chiave, nella sezione Chiavi della pagina Configura selezionare la durata della chiave (1 anno per impostazione predefinita), quindi fare clic su Salva nella parte inferiore della schermata. In questo modo viene generato un valore della chiave, corrispondente alla password dell'applicazione.

    WarningAvviso
    Questo valore viene visualizzato dopo la creazione della chiave e non può essere recuperato in un secondo momento. È pertanto necessario copiare e memorizzare immediatamente il valore della chiave in un luogo sicuro per riferimento futuro. L'applicazione può inoltre disporre di più chiavi, ad esempio per i test e per la produzione.



    Chiave grafico

A questo punto si dispone di un ID client (ID applicazione) e di una chiave dell'applicazione (il valore della chiave) e sono state configurate le autorizzazioni di lettura per l'applicazione.

noteNota
In questa procedura dettagliata viene usato il valore della chiave come password per l'autenticazione dell'applicazione. In termini OAuth 2.0, viene usato il flusso di concessione delle credenziali client, dove grant_type=client_credentials.

Aprire Visual Studio, quindi "Expense Reporting", il progetto relativo alla procedura dettagliata di Single Sign-On creato in precedenza. L'applicazione della procedura dettagliata di Single Sign-On verrà modificata mediante i seguenti passaggi:

  1. Aggiungere il progetto della classe helper di Graph

  2. Eseguire l'aggiornamento a WCF Dataservices 5.3 o versioni successive

  3. Aggiornare il file Web.config

  4. Modificare la classe HomeController

  5. Aggiungere una nuova visualizzazione per gli utenti

  6. Aggiornare la visualizzazione _Layout comune

Scaricare la Libreria helper dell'API Azure AD Graph. Il progetto della classe helper di Graph include una libreria e classi che semplificano l'autenticazione e le chiamate all'API Graph. Il progetto contiene il codice sorgente e deve essere incluso e compilato come parte di questa procedura dettagliata.

  1. Per aggiungere l'helper di Graph al progetto Expense Reporting, fare clic con il pulsante destro del mouse su Soluzione 'ExpenseReport', quindi scegliere Aggiungi e infine Progetto esistente.

  2. Dalla finestra di dialogo Aggiungi progetto esistente passare al percorso dell'helper di Graph, quindi aprire il file di progetto Microsoft.WindowsAzure.ActiveDirectory.GraphHelper.csproj.

Il progetto della classe helper di Graph risulta ora aggiunto alla soluzione ExpenseReport.

La sezione appSettings del file Web.config include informazioni di configurazione specifiche dell'applicazione. Aggiungere le coppie chiave-valore ClientId e Password al file Web.config dell'applicazione.

  • ClientId: corrisponde al valore dell'ID client dalla pagina di gestione dell'applicazione del portale di gestione di Azure AD.

  • Password: corrisponde al valore della chiave dell'applicazione dalla pagina di gestione dell'applicazione del portale di gestione di Azure AD. La password dovrebbe essere stata memorizzata nel passaggio precedente durante la creazione della chiave. Non può essere recuperata in altro modo. Se la chiave precedente risulta persa o dimenticata, è necessario crearne un'altra nella stessa applicazione.

<appSettings>
    <add key="ClientId" value="<insert your ClientId here>"/>
    <add key="Password" value="<insert your Application Key here>"/>
    ...

Dopo aver apportato le modifiche, salvare il file Web.config.

  1. In Visual Studio fare clic con il pulsante destro del mouse sulla cartella References del progetto Expense Reporting, quindi scegliere Aggiungi riferimento.

  2. Nella finestra di dialogo Gestione riferimenti fare clic su Estensioni, quindi selezionare gli assembly Microsoft.Data.OData versione 5.3.0.0 e Microsoft.Data.Services.Client versione 5.3.0.0.



    Riferimento OData
  3. Nella stessa finestra di dialogo Gestione riferimenti espandere il menu Soluzione a sinistra, quindi selezionare la casella di controllo relativa a Microsoft.WindowsAzure.ActiveDirectory.GraphHelper. Fare clic su OK. I riferimenti verranno aggiunti al progetto.



    Aggiungi riferimento helper grafico

Aprire il file HomeController.cs presente nella cartella Controller. Aggiungere gli assembly riportati di seguito, quindi salvare il file.

using System.Configuration;
using System.Security.Claims;
using System.Data.Services.Client;
using Microsoft.WindowsAzure.ActiveDirectory;
using Microsoft.WindowsAzure.ActiveDirectory.GraphHelper;

Individuare la classe HomeController nel file HomeController.cs, dove si trovano gli oggetti ActionResults esistenti (Index, About, Contact). Aggiungere un nuovo oggetto ActionResult denominato Users come illustrato di seguito:

       public ActionResult Users()
       {
            //get the tenantName
            string tenantName = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;



            // retrieve the clientId and password values from the Web.config file
            string clientId = ConfigurationManager.AppSettings["ClientId"];
            string password = ConfigurationManager.AppSettings["Password"];



            // get a token using the helper
            AADJWTToken token = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);

            // initialize a graphService instance using the token acquired from previous step
            DirectoryDataService graphService = new DirectoryDataService(tenantName, token);

            //  get Users
            //
            var users = graphService.users;
            QueryOperationResponse<User> response;
            response = users.Execute() as QueryOperationResponse<User>;
            List<User> userList = response.ToList();
            ViewBag.userList = userList;


            //  For subsequent Graph Calls, the existing token should be used.
            //  The following checks to see if the existing token is expired or about to expire in 2 mins
            //  if true, then get a new token and refresh the graphService
            //
            int tokenMins = 2;
            if (token.IsExpired || token.WillExpireIn(tokenMins))
            {
                AADJWTToken newToken = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);
                token = newToken;
                graphService = new DirectoryDataService(tenantName, token);
            }

            //  get tenant information
            //
            var tenant = graphService.tenantDetails;
            QueryOperationResponse<TenantDetail> responseTenantQuery;
            responseTenantQuery = tenant.Execute() as QueryOperationResponse<TenantDetail>;
            List<TenantDetail> tenantInfo = responseTenantQuery.ToList();
            ViewBag.OtherMessage = "User List from tenant: " + tenantInfo[0].displayName;


            return View(userList);
       }

Creare una nuova visualizzazione nelle cartelle Views/Home, assegnare il nome Users.cshtml alla visualizzazione e aggiungere il codice riportato di seguito:

@model IEnumerable<Microsoft.WindowsAzure.ActiveDirectory.User> 
@{
    ViewBag.Title = "Users";
}

<h1>@ViewBag.Message</h1>
<h2>@ViewBag.OtherMessage</h2>
<table>
    <tr>
        <th>
            DisplayName
        </th>
        <th>
            UPN
        </th>
        <th></th>
    </tr>

@if (User.Identity.IsAuthenticated)
{

  foreach (var user in Model) {
    <tr>
        <td>
         @Html.DisplayFor(modelItem => user.displayName)    
        </td>
        <td>
         @Html.DisplayFor(modelItem => user.userPrincipalName)
        </td>
   </tr>
  }
}
</table>

Nella cartella Views/Shared aprire il file _Layout.cshtml. Nella sezione <header> del file, nell'elemento <nav> aggiungere il nuovo elemento elenco: "<li>@Html.ActionLink("Users", "Users", "Home")</li>". Salvare quindi il file.

               <nav>
                        <ul id="menu">
                            <li>@Html.ActionLink("Home", "Index", "Home")</li>
                            <li>@Html.ActionLink("About", "About", "Home")</li>
                            <li>@Html.ActionLink("Contact", "Contact", "Home")</li>
                            <li>@Html.ActionLink("Users", "Users", "Home")</li>
                        </ul>
                    </nav>

Per eseguire l'applicazione, premere F5. Quando richiesto, eseguire l'accesso con le credenziali di un utente nella directory di Azure AD, ovvero un utente con un account aziendale nel dominio della directory.

L'esperienza Single Sign-On è analoga a quella illustrata nella procedura dettagliata precedente e richiede l'autenticazione tramite le credenziali di Azure AD. Se l'applicazione è stata pubblicata in un sito Web, è necessario aggiornarla con le informazioni fornite in questa procedura. Dopo aver eseguito l'autenticazione utente, selezionare la scheda Utenti dal menu in alto a destra.

Visualizza utenti

L'applicazione avvia il processo di chiamata all'API Graph inviando innanzitutto la richiesta di un token all'endpoint di autenticazione di Azure AD. Se l'operazione ha esito positivo, il token verrà usato nella successiva chiamata a Graph per ottenere tutti gli utenti dal tenant. Nell'applicazione verrà visualizzato un elenco di utenti con i relativi parametri Display Names e User Principal Names.

Si conclude in questo modo la codifica per l'applicazione della procedura dettagliata relativa all'API Graph. La sezione successiva include informazioni dettagliate e collegamenti a un'applicazione di esempio più avanzata dell'API Graph che illustra operazioni di lettura e scrittura aggiuntive.

Dopo la corretta esecuzione dell'accesso Single Sign-On, l'applicazione richiede un token all'endpoint di autorizzazione di Azure AD, usando il nome del tenant (ottenuto dall'attestazione dell'ID tenant dell'utente connesso), l'ID client e la password per l'autenticazione. I dettagli del metodo che supporta l'acquisizione del token sono riportati nella classe DirectoryDataServiceAuthorizationHelper presente nel file con lo stesso nome. Il metodo GetAuthorization gestisce l'acquisizione del token JSON Web Token (JWT) dall'autenticazione di Azure AD fornendo un nome di tenant valido (qualsiasi dominio verificato di proprietà del tenant), l'ID client e la password.

Se la richiesta ha esito positivo, verrà restituito un token JWT da usare nelle chiamate all'API Graph, che verrà inserito nell'intestazione dell'autorizzazione delle richieste successive. La chiamata all'API Graph per ottenere tutti gli utenti è una richiesta HTTP GET contenente le seguenti intestazioni:

Content-Type: application/json; odata=minimalmetadata
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

È consigliabile configurare l'applicazione in modo da memorizzare il token JWT nella cache per le chiamate successive. Nell'applicazione di esempio la scadenza del token JWT viene verificata prima dell'esecuzione di una seconda chiamata all'API Graph. Se il token è scaduto, ne viene acquisito uno nuovo. Se viene eseguita una chiamata all'API Graph con un token scaduto, verrà restituita la seguente risposta di errore e il client dovrà richiedere un nuovo token.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="contoso.com", error="invalid_token", error_description="Your access token has expired. Please renew it before submitting the request.", 

noteNota
Al momento attuale, l'acquisizione dei token di autenticazione di Azure AD viene gestita da un'anteprima di Azure Authentication Library (AAL). Dopo il rilascio di AAL, la documentazione e le applicazioni di esempio correlate verranno aggiornate. La documentazione relativa all'anteprima di AAL è disponibile a questo indirizzo.

Le chiamate REST aggiuntive, inclusi i metodi di lettura e scrittura, sono disponibili in un'altra applicazione di esempio MVC4 che è possibile scaricare da questo indirizzo.

In questo esempio vengono illustrate funzionalità REST aggiuntive, ad esempio:

  • Acquisizione e impostazione dei dettagli utente, incluse le foto di anteprima

  • Creazione e aggiornamento di gruppi

  • Aggiornamento dell'appartenenza a gruppi

  • Paging per la gestione di un numero elevato di oggetti restituiti

Il documento è risultato utile?
(1500 caratteri rimanenti)
Grazie per i commenti inviati.

Aggiunte alla community

Microsoft sta conducendo un sondaggio in linea per comprendere l'opinione degli utenti in merito al sito Web di MSDN. Se si sceglie di partecipare, quando si lascia il sito Web di MSDN verrà visualizzato il sondaggio in linea.

Si desidera partecipare?
Mostra:
© 2014 Microsoft