Créer des applications .NET avec Microsoft Graph et l’authentification d’application uniquement
Ce tutoriel vous apprend à créer une application console .NET qui utilise l’API Microsoft Graph pour accéder aux données à l’aide de l’authentification d’application uniquement. L’authentification d’application uniquement est un bon choix pour les services en arrière-plan ou les applications qui doivent accéder aux données de tous les utilisateurs d’une organisation.
Remarque
Pour savoir comment utiliser Microsoft Graph pour accéder aux données au nom d’un utilisateur, consultez ce tutoriel sur l’authentification de l’utilisateur (déléguée).
Dans ce didacticiel, vous allez :
Conseil
Au lieu de suivre ce didacticiel, vous pouvez télécharger ou cloner le dépôt GitHub et suivre les instructions du fichier LISEZ-MOI pour inscrire une application et configurer le projet.
Configuration requise
Avant de commencer ce didacticiel, vous devez avoir installé le SDK .NET sur votre ordinateur de développement.
Vous devez également disposer d’un compte professionnel ou scolaire Microsoft avec le rôle Administrateur général. Si vous n’avez pas de locataire Microsoft 365, vous pouvez être éligible pour un client via le Programme pour les développeurs Microsoft 365 ; Pour plus d’informations, consultez la FAQ. Vous pouvez également vous inscrire à un essai gratuit de 1 mois ou acheter un plan Microsoft 365.
Remarque
Ce didacticiel a été écrit avec la version 7.0.102 du Kit de développement logiciel (SDK) .NET. Les étapes décrites dans ce guide peuvent fonctionner avec d’autres versions, mais elles n’ont pas été testées.
Inscrire l’application sur le portail
Dans cet exercice, vous allez inscrire une nouvelle application dans Azure Active Directory pour activer l’authentification d’application uniquement. Vous pouvez inscrire une application à l’aide du Centre d’administration Microsoft Entra ou à l’aide du Kit de développement logiciel (SDK) Microsoft Graph PowerShell.
Inscrire l’application pour l’authentification d’application uniquement
Dans cette section, vous allez inscrire une application qui prend en charge l’authentification d’application uniquement à l’aide du flux d’informations d’identification du client.
Ouvrez un navigateur et accédez au Centre d’administration Microsoft Entra et connectez-vous à l’aide d’un compte d’administrateur général.
Sélectionnez Id Microsoft Entra dans le volet de navigation de gauche, développez Identité, Applications, puis inscriptions d’applications.
Sélectionnez Nouvelle inscription. Entrez un nom pour votre application, par exemple .
Graph App-Only Auth Tutorial
Définissez Types de comptes pris en chargesur Comptes dans cet annuaire organisationnel uniquement.
Laissez Redirect URI vide.
Sélectionner Inscription. Dans la page Vue d’ensemble de l’application, copiez la valeur de l’ID d’application (client) et de l’ID d’annuaire (locataire) et enregistrez-les. Vous aurez besoin de ces valeurs à l’étape suivante.
Sélectionnez Autorisations de l’API dans le volet de navigation gauche sous Gérer.
Supprimez l’autorisation User.Read par défaut sous Autorisations configurées en sélectionnant les points de suspension (...) dans sa ligne et en sélectionnant Supprimer l’autorisation.
Sélectionnez Ajouter une autorisation, puis Microsoft Graph.
Sélectionnez Autorisations d’application.
Sélectionnez User.Read.All, puis Ajouter des autorisations.
Sélectionnez Accorder le consentement de l’administrateur pour..., puis sélectionnez Oui pour fournir le consentement de l’administrateur pour l’autorisation sélectionnée.
Sélectionnez Certificats et secrets sous Gérer, puis sélectionnez Nouvelle clé secrète client.
Entrez une description, choisissez une durée, puis sélectionnez Ajouter.
Copiez le secret à partir de la colonne Valeur . Vous en aurez besoin dans les étapes suivantes.
Importante
Ce secret client n’apparaîtra plus jamais, aussi veillez à le copier maintenant.
Remarque
Notez que, contrairement aux étapes de l’inscription à l’authentification utilisateur, dans cette section, vous avez configuré des autorisations Microsoft Graph sur l’inscription de l’application. Cela est dû au fait que l’authentification d’application uniquement utilise le flux d’informations d’identification du client, ce qui nécessite que les autorisations soient configurées lors de l’inscription de l’application. Pour plus d’informations, consultez l’étendue .default .
Créer une application console .NET
Commencez par créer un projet de console .NET à l’aide de l’interface CLI .NET.
Ouvrez votre interface de ligne de commande (CLI) dans un répertoire dans lequel vous souhaitez créer le projet. Exécutez la commande suivante :
dotnet new console -o GraphAppOnlyTutorial
Une fois le projet créé, vérifiez qu’il fonctionne en remplaçant le répertoire actif par le répertoire GraphTutorial et en exécutant la commande suivante dans votre interface CLI.
dotnet run
Si cela fonctionne, l’application doit générer
Hello, World!
.
Installer les dépendances
Avant de continuer, ajoutez des dépendances supplémentaires que vous utiliserez ultérieurement.
- Packages de configuration .NET pour lire la configuration de l’application à partir de appsettings.json.
- Bibliothèque de client Azure Identity pour .NET afin d’authentifier l’utilisateur et d’acquérir des jetons d’accès.
- Bibliothèque de client Microsoft Graph .NET pour effectuer des appels à Microsoft Graph.
Exécutez les commandes suivantes dans votre interface CLI pour installer les dépendances.
dotnet add package Microsoft.Extensions.Configuration.Binder
dotnet add package Microsoft.Extensions.Configuration.Json
dotnet add package Microsoft.Extensions.Configuration.UserSecrets
dotnet add package Azure.Identity
dotnet add package Microsoft.Graph
Charger les paramètres de l’application
Dans cette section, vous allez ajouter les détails de l’inscription de votre application au projet.
Créez un fichier dans le répertoire GraphAppOnlyTutorial nommé appsettings.json et ajoutez le code suivant.
{ "settings": { "clientId": "YOUR_CLIENT_ID_HERE", "tenantId": "YOUR_TENANT_ID_HERE" } }
Mettez à jour les valeurs en fonction du tableau suivant.
Paramètre Valeur clientId
ID client de l’inscription de votre application tenantId
ID de locataire de votre organisation. Conseil
Si vous le souhaitez, vous pouvez définir ces valeurs dans un fichier distinct nommé appsettings. Development.json.
Ajoutez votre clé secrète client au Gestionnaire de secrets .NET. Dans votre interface de ligne de commande, remplacez le répertoire par l’emplacement de GraphAppOnlyTutorial.csproj et exécutez les commandes suivantes, en <remplaçant client-secret> par votre clé secrète client.
dotnet user-secrets init dotnet user-secrets set settings:clientSecret <client-secret>
Mettez à jour GraphAppOnlyTutorial.csproj pour copier appsettings.json dans le répertoire de sortie. Ajoutez le code suivant entre les
<Project>
lignes et</Project>
.<ItemGroup> <None Include="appsettings*.json"> <CopyToOutputDirectory>Always</CopyToOutputDirectory> </None> </ItemGroup>
Créez un fichier dans le répertoire GraphAppOnlyTutorial nommé Settings.cs et ajoutez le code suivant.
using Microsoft.Extensions.Configuration; public class Settings { public string? ClientId { get; set; } public string? ClientSecret { get; set; } public string? TenantId { get; set; } public static Settings LoadSettings() { // Load settings IConfiguration config = new ConfigurationBuilder() // appsettings.json is required .AddJsonFile("appsettings.json", optional: false) // appsettings.Development.json" is optional, values override appsettings.json .AddJsonFile($"appsettings.Development.json", optional: true) // User secrets are optional, values override both JSON files .AddUserSecrets<Program>() .Build(); return config.GetRequiredSection("Settings").Get<Settings>() ?? throw new Exception("Could not load app settings. See README for configuration instructions."); } }
Concevoir l’application
Dans cette section, vous allez créer un menu simple basé sur la console.
Ouvrez ./Program.cs et remplacez tout son contenu par le code suivant.
Console.WriteLine(".NET Graph App-only Tutorial\n"); var settings = Settings.LoadSettings(); // Initialize Graph InitializeGraph(settings); int choice = -1; while (choice != 0) { Console.WriteLine("Please choose one of the following options:"); Console.WriteLine("0. Exit"); Console.WriteLine("1. Display access token"); Console.WriteLine("2. List users"); Console.WriteLine("3. Make a Graph call"); try { choice = int.Parse(Console.ReadLine() ?? string.Empty); } catch (System.FormatException) { // Set to invalid value choice = -1; } switch(choice) { case 0: // Exit the program Console.WriteLine("Goodbye..."); break; case 1: // Display access token await DisplayAccessTokenAsync(); break; case 2: // List users await ListUsersAsync(); break; case 3: // Run any Graph code await MakeGraphCallAsync(); break; default: Console.WriteLine("Invalid choice! Please try again."); break; } }
Ajoutez les méthodes d’espace réservé suivantes à la fin du fichier. Vous les implémenterez dans les étapes ultérieures.
void InitializeGraph(Settings settings) { // TODO } async Task DisplayAccessTokenAsync() { // TODO } async Task ListUsersAsync() { // TODO } async Task MakeGraphCallAsync() { // TODO }
Cela implémente un menu de base et lit le choix de l’utilisateur à partir de la ligne de commande.
Ajouter l’authentification d’application uniquement
Dans cette section, vous allez ajouter l’authentification d’application uniquement à l’application. Cela est nécessaire pour obtenir le jeton d’accès OAuth nécessaire pour appeler Microsoft Graph. Dans cette étape, vous allez intégrer la bibliothèque de client Azure Identity pour .NET dans l’application et configurer l’authentification pour la bibliothèque de client Microsoft Graph .NET.
La bibliothèque Azure Identity fournit un certain nombre de TokenCredential
classes qui implémentent des flux de jetons OAuth2. La bibliothèque de client Microsoft Graph utilise ces classes pour authentifier les appels à Microsoft Graph.
Configurer le client Graph pour l’authentification d’application uniquement
Dans cette section, vous allez utiliser la ClientSecretCredential
classe pour demander un jeton d’accès à l’aide du flux d’informations d’identification du client.
Créez un fichier dans le répertoire GraphTutorial nommé GraphHelper.cs et ajoutez le code suivant à ce fichier.
using Azure.Core; using Azure.Identity; using Microsoft.Graph; using Microsoft.Graph.Models; class GraphHelper { }
Ajoutez ce code à la classe
GraphHelper
.// Settings object private static Settings? _settings; // App-ony auth token credential private static ClientSecretCredential? _clientSecretCredential; // Client configured with app-only authentication private static GraphServiceClient? _appClient; public static void InitializeGraphForAppOnlyAuth(Settings settings) { _settings = settings; // Ensure settings isn't null _ = settings ?? throw new System.NullReferenceException("Settings cannot be null"); _settings = settings; if (_clientSecretCredential == null) { _clientSecretCredential = new ClientSecretCredential( _settings.TenantId, _settings.ClientId, _settings.ClientSecret); } if (_appClient == null) { _appClient = new GraphServiceClient(_clientSecretCredential, // Use the default scope, which will request the scopes // configured on the app registration new[] {"https://graph.microsoft.com/.default"}); } }
Remplacez la fonction vide
InitializeGraph
dans Program.cs par ce qui suit.void InitializeGraph(Settings settings) { GraphHelper.InitializeGraphForAppOnlyAuth(settings); }
Ce code déclare deux propriétés privées, un ClientSecretCredential
objet et un GraphServiceClient
objet . La InitializeGraphForAppOnlyAuth
fonction crée une instance de ClientSecretCredential
, puis utilise cette instance pour créer une nouvelle instance de GraphServiceClient
. Chaque fois qu’un appel d’API est effectué à Microsoft Graph via , _appClient
il utilise les informations d’identification fournies pour obtenir un jeton d’accès.
Tester clientSecretCredential
Ensuite, ajoutez du code pour obtenir un jeton d’accès à partir de .ClientSecretCredential
Ajoutez la fonction suivante à la classe
GraphHelper
.public static async Task<string> GetAppOnlyTokenAsync() { // Ensure credential isn't null _ = _clientSecretCredential ?? throw new System.NullReferenceException("Graph has not been initialized for app-only auth"); // Request token with given scopes var context = new TokenRequestContext(new[] {"https://graph.microsoft.com/.default"}); var response = await _clientSecretCredential.GetTokenAsync(context); return response.Token; }
Remplacez la fonction vide
DisplayAccessTokenAsync
dans Program.cs par ce qui suit.async Task DisplayAccessTokenAsync() { try { var appOnlyToken = await GraphHelper.GetAppOnlyTokenAsync(); Console.WriteLine($"App-only token: {appOnlyToken}"); } catch (Exception ex) { Console.WriteLine($"Error getting app-only access token: {ex.Message}"); } }
Générez et exécutez l’application. Entrez
1
lorsque vous êtes invité à entrer une option. L’application affiche un jeton d’accès..NET Graph Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 1 App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
Conseil
À des fins de validation et de débogage uniquement, vous pouvez décoder les jetons d’accès d’application uniquement à l’aide de l’analyseur de jetons en ligne de Microsoft à l’adresse https://jwt.ms. Cela peut être utile si vous rencontrez des erreurs de jeton lors de l’appel de Microsoft Graph. Par exemple, vérifier que la revendication dans le
role
jeton contient les étendues d’autorisation Microsoft Graph attendues.
Répertorier des utilisateurs
Dans cette section, vous allez ajouter la possibilité de répertorier tous les utilisateurs de votre instance Azure Active Directory à l’aide de l’authentification d’application uniquement.
Ouvrez ./GraphHelper.cs et ajoutez la fonction suivante à la classe GraphHelper .
public static Task<UserCollectionResponse?> GetUsersAsync() { // Ensure client isn't null _ = _appClient ?? throw new System.NullReferenceException("Graph has not been initialized for app-only auth"); return _appClient.Users.GetAsync((config) => { // Only request specific properties config.QueryParameters.Select = new[] { "displayName", "id", "mail" }; // Get at most 25 results config.QueryParameters.Top = 25; // Sort by display name config.QueryParameters.Orderby = new[] { "displayName" }; }); }
Remplacez la fonction vide
ListUsersAsync
dans Program.cs par ce qui suit.async Task ListUsersAsync() { try { var userPage = await GraphHelper.GetUsersAsync(); if (userPage?.Value == null) { Console.WriteLine("No results returned."); return; } // Output each users's details foreach (var user in userPage.Value) { Console.WriteLine($"User: {user.DisplayName ?? "NO NAME"}"); Console.WriteLine($" ID: {user.Id}"); Console.WriteLine($" Email: {user.Mail ?? "NO EMAIL"}"); } // If NextPageRequest is not null, there are more users // available on the server // Access the next page like: // var nextPageRequest = new UsersRequestBuilder(userPage.OdataNextLink, _appClient.RequestAdapter); // var nextPage = await nextPageRequest.GetAsync(); var moreAvailable = !string.IsNullOrEmpty(userPage.OdataNextLink); Console.WriteLine($"\nMore users available? {moreAvailable}"); } catch (Exception ex) { Console.WriteLine($"Error getting users: {ex.Message}"); } }
Exécutez l’application et choisissez l’option 2 pour répertorier les utilisateurs.
Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 2 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: NO EMAIL User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? True
Explication du code
Considérez le code dans la GetUsersAsync
fonction .
- Il obtient une collection d’utilisateurs
- Il utilise
Select
pour demander des propriétés spécifiques - Il utilise
Top
pour limiter le nombre d’utilisateurs retournés - Il utilise
OrderBy
pour trier la réponse
Facultatif : ajouter votre propre code
Dans cette section, vous allez ajouter vos propres fonctionnalités Microsoft Graph à l’application. Il peut s’agir d’un extrait de code de la documentation Microsoft Graph ou de l’Explorateur Graph, ou du code que vous avez créé. Cette section est facultative.
Mettre à jour l’application
Ouvrez ./GraphHelper.cs et ajoutez la fonction suivante à la classe GraphHelper .
// This function serves as a playground for testing Graph snippets // or other code public async static Task MakeGraphCallAsync() { // INSERT YOUR CODE HERE }
Remplacez la fonction vide
MakeGraphCallAsync
dans Program.cs par ce qui suit.async Task MakeGraphCallAsync() { await GraphHelper.MakeGraphCallAsync(); }
Choisir une API
Recherchez une API dans Microsoft Graph que vous souhaitez essayer. Par exemple, l’API Créer un événement . Vous pouvez utiliser l’un des exemples de la documentation de l’API ou personnaliser un exemple.
Configuration des autorisations
Consultez la section Autorisations de la documentation de référence de l’API choisie pour voir quelles méthodes d’authentification sont prises en charge. Certaines API ne prennent pas en charge les comptes Microsoft personnels ou d’application uniquement, par exemple.
- Pour appeler une API avec l’authentification utilisateur (si l’API prend en charge l’authentification utilisateur (déléguée), consultez le tutoriel sur l’authentification utilisateur (déléguée).
- Pour appeler une API avec l’authentification d’application uniquement (si l’API la prend en charge), ajoutez l’étendue d’autorisation requise dans le Centre d’administration Azure AD.
Ajouter votre code
Copiez votre code dans la MakeGraphCallAsync
fonction dans GraphHelper.cs. Si vous copiez un extrait de code à partir de la documentation ou de l’Explorateur Graph, veillez à renommer en GraphServiceClient
_appClient
.
Félicitations !
Vous avez terminé le tutoriel Microsoft Graph .NET. Maintenant que vous disposez d’une application opérationnelle qui appelle Microsoft Graph, vous pouvez expérimenter et ajouter de nouvelles fonctionnalités.
- Découvrez comment utiliser l’authentification utilisateur (déléguée) avec le Kit de développement logiciel (SDK) .NET Microsoft Graph.
- Consultez la vue d’ensemble de Microsoft Graph pour voir toutes les données accessibles avec Microsoft Graph.
Exemples .NET
Vous avez un défi avec cette section ? Si c'est le cas, faites-nous part de vos commentaires pour que nous puissions l'améliorer.