Exporter (0) Imprimer
Développer tout

Utilisation de l'API Graph pour interroger Azure AD

Mis à jour: mai 2014

noteRemarque
REMARQUE : cet exemple est obsolète, car la technologie, les méthodes et/ou les instructions sur l'interface utilisateur auxquelles il fait appel ont été remplacées par des fonctionnalités plus récentes. Pour obtenir un exemple actualisé permettant de créer une application similaire, consultez WebApp-GraphAPI-DotNet.

Cet exemple d'application est destiné aux développeurs .NET qui souhaitent ajouter des applications existantes et créer de nouvelles applications pour Windows Azure Active Directory (Windows Azure AD). Cette procédure pas à pas s'appuie sur la rubrique Ajout d'une procédure d'authentification à une application web avec Azure AD, qui a permis de générer un exemple d'application illustrant la mise en œuvre d'une expérience utilisateur d'authentification unique web pour les clients Windows Azure AD. Cette procédure pas à pas montre comment utiliser l'API Windows Azure AD Graph pour lire des données d'annuaire. L'API Graph est une API RESTful qui permet aux applications d'accéder aux données d'annuaire Windows Azure des clients.

Les applications ont besoin d'un accès aux données d'annuaire pour de nombreux scénarios, dont notamment :

  • Récupération de listes d'utilisateurs, de groupes et de contacts pour des outils de sélection d'utilisateurs/de groupes

  • Lecture d'informations détaillées de locataire, d'utilisateur ou de groupe

  • Vérification de l'appartenance aux groupes

  • Modification d'un utilisateur, de groupes et de l'appartenance aux groupes

  • Mise à jour des mots de passe d'un utilisateur

  • Désactivation de comptes d'utilisateur

noteRemarque
Lorsqu'une application mutualisée tente d'acquérir un jeton pour accéder à l'API Graph pour un locataire Azure AD qui a récemment consenti à l'application, la demande de jeton peut échouer avec l'erreur ACS50012. Pour résoudre le problème, patienter quelques minutes et réessayez. Sinon, demandez à l'administrateur du locataire qui a donné le consentement de se connecter à l'application après le consentement. Pour plus d'informations, consultez Codes d'erreur ACS.

Ce document comprend les sections suivantes :

Ce didacticiel ne peut être effectué que si les conditions préalables suivantes sont remplies :

À la fin de cette procédure pas à pas, vous disposerez d'une application configurée pour lire les données à partir de votre locataire Azure AD. L'application peut lire les entités d'annuaire suivantes : Utilisateurs, Groupes, Contacts, Informations sur la société, Licences et Rôles. De plus, si votre application se voit accorder des autorisations d'écriture, elle peut également mettre à jour ces entités.

Dans cet exemple d'application, nous verrons comment lire les données d'annuaire de votre société Azure AD. Rubriques avancées supplémentaires :

  • Obtenir des détails d'utilisateur complets

  • Créer et mettre à jour les utilisateurs

  • Obtenir la liste des groupes

  • Mettre à jour l'appartenance aux groupes

L'expérience d'authentification unique demeure la même une fois que vous avez mis à jour l'application pour qu'elle puisse accéder à l'API Graph. Une fois que l'authentification de l'utilisateur a réussi, l'application demande un jeton auprès du point de terminaison d'authentification Azure AD et, en cas de succès, l'application utilise ce jeton dans les appels à l'API Graph afin d'obtenir tous les utilisateurs du locataire. L'application affiche la liste des utilisateurs, avec leurs Display Names et User Principal Names.

Architecture de la solution

Dans cette procédure pas à pas, vous utiliserez le flux d'informations d'identification du client OAuth 2.0 pour authentifier l'application. Avant d'accéder au point de terminaison de l'API Graph, l'application doit acquérir un jeton valide à partir du point de terminaison d'authentification Azure AD. Pour cela, elle présente des informations d'identification d'application valides (ID client et question secrète). Si les informations d'identification sont validées, un jeton signé est retourné à l'application. Ensuite, l'application inclut le jeton dans l'en-tête d'autorisation de ses appels à l'API Graph. Le service de l'API Graph valide le jeton dans le cadre de la demande entrante et, en cas de succès, une vérification d'autorisation est effectuée.

L'autorisation de l'application est vérifiée par l'API Graph et son service RBAC (contrôle d'accès basé sur les rôles) sous-jacent. Les appels à l'API Graph sont limités par les autorisations de l'application. Les données sont retournées à l'application en cas de réussite de l'authentification et de l'autorisation.

La configuration de l'authentification et de l'autorisation d'une application est stockée dans Azure AD à l'aide d'un objet Service Principal stocké dans l'annuaire du locataire. Les applications sont représentées dans Azure AD par un objet Service Principal doté d'une identité unique, d'informations d'identification et d'autorisations. Ceci est similaire aux objets User Principal dans Active Directory, qui représentent des utilisateurs, tous dotés d'identités, d'informations d'identification et d'autorisations uniques.

L'objet Service Principal d'une application possède un ID unique et une question secrète utilisés pour l'authentification. L'autorisation est gérée via l'ajout du principal de service de l'application à un rôle doté des autorisations requises. Les administrateurs clients peuvent créer des principaux de service d'application et les ajouter à des rôles dans le portail de gestion Azure AD. Éventuellement, les administrateurs clients peuvent également utiliser Windows PowerShell pour gérer les principaux de service. Pour plus d'informations, consultez Gérer Windows Azure Active Directory à l'aide de Windows PowerShell

Dans la procédure pas à pas Ajout d'une procédure d'authentification à une application web avec Azure AD, vous avez autorisé l'application à accepter l'authentification unique à l'aide de vos informations d'identification d'utilisateur Azure AD en configurant les autorisations de l'application dans le portail de gestion Azure AD. Vous allez à présent mettre à jour la configuration de l'application pour permettre à votre application de relevé de dépenses de s'authentifier auprès de l'API Graph et d'appeler cette dernière. Vous effectuerez les étapes suivantes :

  • Autorisation : configurez les autorisations de votre application pour autoriser l'accès en lecture/écriture à l'annuaire.

  • Authentification : obtenez une clé d'application qui servira de mot de passe à votre application. Elle permet d'authentifier votre application auprès de l'API Graph.

  1. Accédez au Portail de gestion Microsoft Azure (https://manage.WindowsAzure.com), ouvrez une session, puis cliquez sur Active Directory. (Conseil de dépannage : « Active Directory » est manquant ou non disponible)

  2. Sélectionnez votre annuaire d'un clic, cliquez sur Applications, puis sur l'exemple d'application de relevé de dépenses (Expense Reporting) que vous avez créé dans la procédure pas à pas d'authentification unique.



    Accès externe

  3. En bas de la page, cliquez sur Gérer l'accès.

  4. Sélectionnez Modifier l'accès de l'annuaire pour cette application.



    Que souhaitez-vous faire ?
  5. Sélectionnez Authentification unique, lecture des données d'annuaire. Ensuite, cliquez sur la coche pour enregistrer vos modifications.



    Accès au répertoire

  1. Dans la page de l'application Expense Reporting, développez Activer votre application pour accéder en lecture ou écriture aux données d'annuaire. Dans la section Créer une clé, sélectionnez Configurer la clé.



    Configurer la clé

  2. Pour ajouter une clé, dans la page Configurer, dans la section Clés, sélectionnez la durée de vie de la clé (1 an par défaut), puis cliquez sur Enregistrer au bas de l'écran. Cela génère une valeur de clé qui servira de mot de passe à votre application.

    WarningAvertissement
    La valeur de clé est affichée après la création de la clé, mais elle cannot être récupérée ultérieurement. Par conséquent, vous devez copier immédiatement la valeur de clé et la stocker dans un emplacement sécurisé pour pouvoir vous y reporter ultérieurement. De plus, votre application peut posséder plusieurs clés. Par exemple, vous pouvez en avoir une ou plusieurs pour les tests et la production.



    Graphique de la clé

À ce stade, vous disposez d'un ID client (ID d'application), d'une clé d'application (la valeur de clé) et vous avez configuré des autorisations de lecture pour l'application.

noteRemarque
Dans l'exemple d'application de cette procédure pas à pas, nous utilisons la valeur de clé comme mot de passe pour authentifier l'application. Dans OAuth 2.0, nous utilisons le flux d'attribution d'informations d'identification client, où grant_type=client_credentials).

Ouvrez Visual Studio, puis ouvrez « Expense Reporting », le projet de procédure pas à pas d'authentification unique précédemment créé. Nous allons modifier l'application de procédure pas à pas d'authentification unique dans les étapes suivantes :

  1. Ajouter le projet de classe d'assistance Graph

  2. Effectuer la mise à jour vers WCF Data Services 5.3 ou version ultérieure

  3. Mettre à jour le fichier Web.config

  4. Modifier le fichier HomeController.

  5. Ajouter une vue pour les utilisateurs

  6. Mettre à jour la vue _Layout commune

Téléchargez la Bibliothèque d'aide pour l'API Azure AD Graph. Le projet de classe d'assistance Graph inclut une bibliothèque et des classes qui facilitent l'authentification auprès de l'API Graph et l'appel de cette API. Elle inclut le code source et devrait être incluse et générée dans le cadre de cette procédure pas à pas.

  1. Pour ajouter le programme d'assistance Graph au projet Expense Reporting, cliquez avec le bouton droit sur la solution Solution 'ExpenseReport', cliquez sur Ajouter, puis cliquez sur Projet existant.

  2. Dans la boîte de dialogue Ajouter un projet existant, accédez au chemin du programme d'assistance Graph, puis ouvrez le fichier projet Microsoft.WindowsAzure.ActiveDirectory.GraphHelper.csproj.

Le projet Graph Helper est à présent ajouté à votre solution ExpenseReport.

La section appSettings du fichier Web.config contient des informations de configuration spécifiques à l'application. Ajoutez les paires clé-valeur ClientId et Password au fichier Web.config de l'application.

  • ClientId : égal à la valeur d'ID client issue de la page de gestion d'application du portail de gestion Azure AD.

  • Password : égal à la valeur de clé d'application issue de la page de gestion d'application du portail de gestion Azure AD. Cette valeur doit avoir été enregistrée à l'étape précédente pour créer une clé. Notez qu'elle n'est pas récupérable. Si vous avez oublié ou perdu la clé précédente, créez-en une autre sous la même application.

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

Après avoir effectué les modifications, enregistrez le fichier Web.config.

  1. Dans Visual Studio, cliquez avec le bouton droit sur le dossier Références du projet Expense Reporting et cliquez sur Ajouter une référence…

  2. Dans la boîte de dialogue Gestionnaire de références, cliquez sur Extensions et sélectionnez l'assembly Microsoft.Data.OData version 5.3.0.0 et l'assembly Microsoft.Data.Services.Client version 5.3.0.0.



    Référence OData
  3. Dans la même boîte de dialogue Gestionnaire de références, développez le menu Solution à gauche, puis cochez la case pour Microsoft.WindowsAzure.ActiveDirectory.GraphHelper. Appuyez sur OK. Les références sont ajoutées à votre projet.



    Ajout d'une référence d'application auxiliaire graphique

Ouvrez le fichier HomeController.cs, situé dans le dossier Contrôleurs. Ajoutez les assemblys suivants au fichier, puis enregistrez le fichier.

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

Recherchez la classe HomeController dans le fichier HomeController.cs, où les ActionResults existants résident (Index, About, Contact). Ajoutez un nouveau ActionResult nommé Users (Utilisateurs) comme illustré ci-dessous :

       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);
       }

Créez une vue sous les dossiers Views/Home nommée Users.cshtml et ajoutez le code suivant :

@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>

Dans le dossier Views/Shared, ouvrez le fichier _Layout.cshtml. Dans la section <header> du fichier, dans l'élément <nav>, ajoutez le nouvel élément de liste : "<li>@Html.ActionLink("Users", "Users", "Home")</li>". Ensuite, enregistrez le fichier.

               <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>

Pour exécuter l'application, appuyez sur F5. Lorsque vous y êtes invité, connectez-vous avec les informations d'identification d'un utilisateur figurant dans votre annuaire Azure AD, à savoir un utilisateur doté d'un compte d'organisation dans le domaine de votre annuaire.

L'expérience d'authentification unique est la même que celle de la procédure pas à pas précédente, exigeant une authentification à l'aide de vos informations d'identification Azure AD. Si vous avez publié votre application sur un site web, vous devez la mettre à jour avec les mises à jour issues de cette procédure pas à pas. Après une authentification d'utilisateur réussie, sélectionnez l'onglet Users (Utilisateurs) dans le menu en haut à droite.

Utilisateurs affichés

L'application démarre le processus d'appel de l'API Graph en commençant par demander un jeton auprès du point de terminaison d'authentification Azure AD. Une fois cette opération réussie, l'application utilisera le jeton dans l'appel suivant à Graph pour obtenir tous les utilisateurs du locataire. L'application affichera alors la liste des utilisateurs, avec leurs Display Names et User Principal Names.

Ceci conclut le codage pour l'application de procédure pas à pas de l'API Graph. La section suivante inclut des informations plus détaillées et des liens vers un exemple d'application d'API Graph plus avancé qui illustre des opérations de lecture et d'écriture supplémentaires.

Après une authentification unique réussie, l'application demande un jeton au point de terminaison d'autorisation Azure AD en utilisant le nom du locataire (obtenu à partir de la revendication d'ID de locataire de l'utilisateur authentifié), l'ID client et le mot de passe pour s'authentifier. Les détails de la méthode qui prend en charge l'acquisition de jeton sont disponibles dans la classe DirectoryDataServiceAuthorizationHelper figurant dans le fichier du même nom. La méthode GetAuthorization gère l'acquisition du jeton web JSON (jeton JWT) à partir de l'authentification Azure AD en fournissant un nom de locataire valide (tout domaine vérifié détenu par le locataire), l'ID client et le mot de passe.

Une demande réussie retournera un jeton JWT à utiliser dans les appels à l'API Graph, qui sera inséré dans l'en-tête d'autorisation des demandes suivantes. L'appel de l'API Graph pour obtenir tous les utilisateurs est une requête HTTP GET contenant les en-têtes suivants :

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

Il est recommandé que le jeton JWT soit mis en cache par l'application pour les appels suivants. Dans l'exemple d'application, l'expiration du jeton JWT est vérifiée avant d'effectuer un second appel de l'API Graph. Si le jeton a expiré, un nouveau jeton est acquis. Si un appel à l'API Graph est effectué avec un jeton expiré, la réponse d'erreur ci-dessous est retournée et le client doit demander un nouveau jeton.

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.", 

noteRemarque
Actuellement, il existe une version préliminaire de la bibliothèque d'authentification Azure (AAL) qui gère l'acquisition des jetons d'authentification Azure AD. Lorsque la bibliothèque AAL sera publiée, nous mettrons à jour les exemples d'applications et la documentation relative à l'utilisation de cette bibliothèque. La documentation relative à la version préliminaire de la bibliothèque AAL est disponible ici.

Des appels REST supplémentaires, y compris des méthodes de lecture et d'écriture, sont disponibles dans un autre exemple d'application MVC4 téléchargeable ici.

Cet exemple illustre des fonctionnalités REST supplémentaires, dont notamment :

  • Obtenir et définir des détails d'utilisateur, y compris des photos miniatures

  • Créer, mettre à jour des groupes

  • Mettre à jour l'appartenance aux groupes

  • Pagination pour la gestion d'un nombre important d'objets retournés

Ajouts de la communauté

Afficher:
© 2014 Microsoft