Создание приложений .NET с помощью Microsoft Graph и проверки подлинности только для приложений

В этом руководстве описано, как создать консольное приложение .NET, которое использует API Microsoft Graph для доступа к данным с помощью проверки подлинности только для приложений. Проверка подлинности только для приложений — это хороший выбор для фоновых служб или приложений, которым требуется доступ к данным для всех пользователей в организации.

В этом руководстве описан порядок выполнения перечисленных ниже задач.

• Перечисление пользователей

Предварительные условия

Перед началом работы с этим руководством на компьютере разработки должен быть установлен пакет SDK для .NET .

У вас также должна быть рабочая или учебная учетная запись Майкрософт с ролью глобального администратора. Если у вас нет клиента Microsoft 365, вы можете претендовать на него в рамках Программы разработчиков Microsoft 365. Дополнительные сведения см. в разделе Вопросы и ответы. Кроме того, вы можете зарегистрироваться для получения бесплатной пробной версии на 1 месяц или приобрести план Microsoft 365.

Регистрация приложения на портале

• Осталось 18 мин

В этом упражнении вы зарегистрируете новое приложение в Azure Active Directory, чтобы включить проверку подлинности только для приложений. Вы можете зарегистрировать приложение в Центре администрирования Microsoft Entra или с помощью пакета SDK Для Microsoft Graph PowerShell.

Регистрация приложения для проверки подлинности только для приложений

В этом разделе описано, как зарегистрировать приложение, которое поддерживает проверку подлинности только для приложений с помощью потока учетных данных клиента.

Создание консольного приложения .NET

• Осталось 15 мин

Начните с создания консольного проекта .NET с помощью интерфейса командной строки .NET.

1. Откройте интерфейс командной строки (CLI) в каталоге, в котором вы хотите создать проект. Выполните следующую команду.

   dotnet new console -o GraphAppOnlyTutorial
   

2. После создания проекта убедитесь, что он работает, изменив текущий каталог на каталог GraphTutorial и выполнив следующую команду в интерфейсе командной строки.

   dotnet run
   

   Если это работает, приложение должно вывести .Hello, World!

Установка зависимостей

Прежде чем переходить дальше, добавьте некоторые дополнительные зависимости, которые будут использоваться позже.

• Пакеты конфигурации .NET для чтения конфигурации приложения из appsettings.json.
• Клиентская библиотека удостоверений Azure для .NET для проверки подлинности пользователя и получения маркеров доступа.
• Клиентская библиотека Microsoft Graph .NET для выполнения вызовов к Microsoft Graph.

Выполните следующие команды в интерфейсе командной строки, чтобы установить зависимости.

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

Загрузка параметров приложения

В этом разделе вы добавите в проект сведения о регистрации приложения.

1. Создайте файл в каталоге GraphAppOnlyTutorialс именем appsettings.json и добавьте следующий код.

   {
     "settings": {
       "clientId": "YOUR_CLIENT_ID_HERE",
       "tenantId": "YOUR_TENANT_ID_HERE"
     }
   }
   

2. Обновите значения в соответствии со следующей таблицей.

   Параметр	Значение
   clientId	Идентификатор клиента для регистрации приложения
   tenantId	Идентификатор клиента вашей организации.

   Совет

   При необходимости эти значения можно задать в отдельном файле с именем appsettings. Development.json.

3. Добавьте секрет клиента в диспетчер секретов .NET. В интерфейсе командной строки измените каталог на расположение GraphAppOnlyTutorial.csproj и выполните следующие команды, заменив <секрет> клиента секретом клиента.

   dotnet user-secrets init
   dotnet user-secrets set settings:clientSecret <client-secret>
   

4. Обновите GraphAppOnlyTutorial.csproj , чтобы скопировать appsettings.json в выходной каталог. Добавьте следующий код между строками <Project> и </Project> .

   <ItemGroup>
     <None Include="appsettings*.json">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>
   </ItemGroup>
   

5. Создайте файл в каталоге GraphAppOnlyTutorialс именем Settings.cs и добавьте следующий код.

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

Проектирование приложения

В этом разделе вы создадите простое меню на основе консоли.

1. Откройте ./Program.cs и замените все его содержимое следующим кодом.

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

2. Добавьте следующие методы-заполнители в конец файла. Вы будете реализовывать их на последующих шагах.

   void InitializeGraph(Settings settings)
   {
       // TODO
   }
   
   async Task DisplayAccessTokenAsync()
   {
       // TODO
   }
   
   async Task ListUsersAsync()
   {
       // TODO
   }
   
   async Task MakeGraphCallAsync()
   {
       // TODO
   }
   

Это реализует базовое меню и считывает выбор пользователя из командной строки.

Добавление проверки подлинности только для приложений

• Осталось 9 мин

В этом разделе вы добавите в приложение проверку подлинности только для приложений. Это необходимо для получения необходимого маркера доступа OAuth для вызова Microsoft Graph. На этом шаге вы интегрируете клиентную библиотеку удостоверений Azure для .NET в приложение и настроите проверку подлинности для клиентской библиотеки Microsoft Graph .NET.

Библиотека удостоверений Azure предоставляет ряд классов, которые реализуют потоки маркеров TokenCredential OAuth2. Клиентская библиотека Microsoft Graph использует эти классы для проверки подлинности вызовов Microsoft Graph.

Настройка клиента Graph для проверки подлинности только для приложений

В этом разделе вы будете ClientSecretCredential использовать класс для запроса маркера доступа с помощью потока учетных данных клиента.

1. Создайте файл в каталоге GraphTutorial с именем GraphHelper.cs и добавьте в этот файл следующий код.

   using Azure.Core;
   using Azure.Identity;
   using Microsoft.Graph;
   using Microsoft.Graph.Models;
   
   class GraphHelper
   {
   }
   

2. Добавьте приведенный ниже код в класс 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"});
       }
   }
   

3. Замените пустую InitializeGraph функцию в Program.cs на следующую.

   void InitializeGraph(Settings settings)
   {
       GraphHelper.InitializeGraphForAppOnlyAuth(settings);
   }
   

Этот код объявляет два частных свойства: ClientSecretCredential объект и GraphServiceClient объект . Функция InitializeGraphForAppOnlyAuth создает новый экземпляр ClientSecretCredential, а затем использует его для создания нового экземпляра GraphServiceClient. Каждый раз, когда вызов API выполняется к Microsoft Graph через _appClient, он использует предоставленные учетные данные для получения маркера доступа.

Тестирование ClientSecretCredential

Затем добавьте код для получения маркера доступа из ClientSecretCredential.

1. Добавьте к классу 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;
   }
   

2. Замените пустую DisplayAccessTokenAsync функцию в Program.cs на следующую.

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

3. Выполните сборку и запуск приложения. Введите 1 при появлении запроса на выбор параметра. Приложение отображает маркер доступа.

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

   Совет

   Только для проверки и отладки можно декодировать маркеры доступа только для приложений с помощью средства синтаксического анализа токенов Майкрософт в сети по адресу https://jwt.ms. Это может быть полезно, если при вызове Microsoft Graph возникают ошибки маркера. Например, убедитесь, что role утверждение в маркере содержит ожидаемые области разрешений Microsoft Graph.

Перечисление пользователей

• Осталось 6 мин

В этом разделе вы добавите возможность вывода списка всех пользователей в Azure Active Directory с помощью проверки подлинности только для приложений.

1. Откройте ./GraphHelper.cs и добавьте следующую функцию в класс 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" };
       });
   }
   

2. Замените пустую ListUsersAsync функцию в Program.cs на следующую.

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

3. Запустите приложение и выберите вариант 2, чтобы получить список пользователей.

   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
   

Описание кода

Рассмотрим код в GetUsersAsync функции.

• Он получает коллекцию пользователей
• Он использует Select для запроса определенных свойств
• Он использует Top для ограничения числа возвращенных пользователей
• Он использует OrderBy для сортировки ответа

Необязательно: добавление собственного кода

• Осталось 4 мин

В этом разделе вы добавите в приложение собственные возможности Microsoft Graph. Это может быть фрагмент кода из документации Microsoft Graph или обозревателя Graph или созданный вами код. Этот раздел является необязательным.

Обновите приложение

1. Откройте ./GraphHelper.cs и добавьте следующую функцию в класс GraphHelper .

   // This function serves as a playground for testing Graph snippets
   // or other code
   public async static Task MakeGraphCallAsync()
   {
       // INSERT YOUR CODE HERE
   }
   

2. Замените пустую MakeGraphCallAsync функцию в Program.cs на следующую.

   async Task MakeGraphCallAsync()
   {
       await GraphHelper.MakeGraphCallAsync();
   }
   

Выбор API

Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API создания событий . Вы можете использовать один из примеров в документации по API или настроить пример.

Настройка разрешений

Ознакомьтесь с разделом Разрешения справочной документации по выбранному API, чтобы узнать, какие методы проверки подлинности поддерживаются. Некоторые API не поддерживают только приложения или личные учетные записи Майкрософт, например.

• Чтобы вызвать API с проверкой подлинности пользователя (если API поддерживает проверку подлинности пользователя (делегированная) проверка подлинности, см. руководство по проверке подлинности пользователя (делегированная).
• Чтобы вызвать API с проверкой подлинности только для приложений (если API поддерживает ее), добавьте требуемую область разрешений в Центре администрирования Azure AD.

Добавление кода

Скопируйте код в функцию MakeGraphCallAsync в GraphHelper.cs. Если вы копируете фрагмент из документации или обозревателя Graph, обязательно переименуйте GraphServiceClient_appClientв .

Поздравляем!

• 100% завершено

Вы завершили работу с руководством по Microsoft Graph для .NET. Теперь, когда у вас есть рабочее приложение, которое вызывает Microsoft Graph, вы можете экспериментировать и добавлять новые функции.

• Узнайте, как использовать проверку подлинности пользователя (делегированная) с помощью пакета SDK для Microsoft Graph для .NET.
• Просмотрите обзор Microsoft Graph , чтобы просмотреть все данные, к которым можно получить доступ с помощью Microsoft Graph.

Примеры .NET

• приложение MVC ASP.NET Core
• Приложение универсальной платформы Windows (UWP)
• Приложение Xamarin
• Приложение Blazor WebAssembly
• Функции Azure
• Bot Framework
• Приложение Teams
• Уведомления об изменениях
• Фрагменты ASP.NET Core