Erstellen von .NET-Apps mit Microsoft Graph und nur app-Authentifizierung

In diesem Tutorial erfahren Sie, wie Sie eine .NET-Konsolen-App erstellen, die die Microsoft Graph-API verwendet, um mithilfe der reinen App-Authentifizierung auf Daten zuzugreifen. Die reine App-Authentifizierung ist eine gute Wahl für Hintergrunddienste oder Anwendungen, die auf Daten für alle Benutzer in einer Organisation zugreifen müssen.

In diesem Lernprogramm wird Folgendes vermittelt:

• Benutzer auflisten

Voraussetzungen

Bevor Sie mit diesem Tutorial beginnen, sollte das .NET SDK auf Ihrem Entwicklungscomputer installiert sein.

Sie sollten auch über ein Microsoft-Geschäfts-, Schul- oder Unikonto mit der Rolle "Globaler Administrator" verfügen. Wenn Sie nicht über einen Microsoft 365-Mandanten verfügen, können Sie sich über das Microsoft 365-Entwicklerprogramm für einen mandantenfähigen Mandanten qualifizieren. Weitere Informationen finden Sie in den häufig gestellten Fragen. Alternativ können Sie sich für eine kostenlose 1-monatige Testversion registrieren oder einen Microsoft 365-Plan erwerben.

Registrieren der App im Portal

• 18 Minuten verbleibend

In dieser Übung registrieren Sie eine neue Anwendung in Azure Active Directory, um die reine App-Authentifizierung zu aktivieren. Sie können eine Anwendung über das Microsoft Entra Admin Center oder mithilfe des Microsoft Graph PowerShell SDK registrieren.

Registrieren der Anwendung für die reine App-Authentifizierung

In diesem Abschnitt registrieren Sie eine Anwendung, die die reine App-Authentifizierung mit Clientanmeldeinformationen unterstützt.

Erstellen einer .NET-Konsolen-App

• 15 Minuten verbleibend

Erstellen Sie zunächst ein neues .NET-Konsolenprojekt mithilfe der .NET CLI.

1. Öffnen Sie Ihre Befehlszeilenschnittstelle (CLI) in einem Verzeichnis, in dem Sie das Projekt erstellen möchten. Führen Sie den folgenden Befehl aus.

   dotnet new console -o GraphAppOnlyTutorial
   

2. Nachdem das Projekt erstellt wurde, überprüfen Sie, ob es funktioniert, indem Sie das aktuelle Verzeichnis in das Verzeichnis GraphTutorial ändern und den folgenden Befehl in Ihrer CLI ausführen.

   dotnet run
   

   Wenn es funktioniert, sollte die App ausgeben Hello, World!.

Installieren von Abhängigkeiten

Bevor Sie mit dem Vorgang fortfahren, fügen Sie einige zusätzliche Abhängigkeiten hinzu, die Sie später verwenden werden.

• .NET-Konfigurationspakete zum Lesen der Anwendungskonfiguration aus appsettings.json.
• Azure Identity-Clientbibliothek für .NET zum Authentifizieren des Benutzers und Abrufen von Zugriffstoken.
• Microsoft Graph .NET-Clientbibliothek , um Aufrufe an Microsoft Graph zu tätigen.

Führen Sie die folgenden Befehle in Ihrer CLI aus, um die Abhängigkeiten zu installieren.

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

Laden von Anwendungseinstellungen

In diesem Abschnitt fügen Sie dem Projekt die Details Ihrer App-Registrierung hinzu.

1. Erstellen Sie im Verzeichnis GraphAppOnlyTutorial eine Datei mit dem Namen appsettings.json , und fügen Sie den folgenden Code hinzu.

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

2. Aktualisieren Sie die Werte gemäß der folgenden Tabelle.

   Einstellung	Wert
   clientId	Die Client-ID Ihrer App-Registrierung
   tenantId	Die Mandanten-ID Ihrer Organisation.

   Tipp

   Optional können Sie diese Werte in einer separaten Datei mit dem Namen appsettings festlegen. Development.json.

3. Fügen Sie den geheimen Clientschlüssel zum .NET-Geheimnis-Manager hinzu. Ändern Sie in Ihrer Befehlszeilenschnittstelle das Verzeichnis in den Speicherort von GraphAppOnlyTutorial.csproj, und führen Sie die folgenden Befehle aus, und ersetzen Sie dabei den geheimen> Clientschlüssel durch Ihren geheimen< Clientschlüssel.

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

4. Aktualisieren Sie GraphAppOnlyTutorial.csproj , um appsettings.json in das Ausgabeverzeichnis zu kopieren. Fügen Sie den folgenden Code zwischen den <Project> Zeilen und </Project> hinzu.

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

5. Erstellen Sie im Verzeichnis GraphAppOnlyTutorial eine Datei mit dem Namen Settings.cs , und fügen Sie den folgenden Code hinzu.

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

Entwerfen der App

In diesem Abschnitt erstellen Sie ein einfaches konsolenbasiertes Menü.

1. Öffnen Sie ./Program.cs , und ersetzen Sie den gesamten Inhalt durch den folgenden Code.

   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. Fügen Sie am Ende der Datei die folgenden Platzhaltermethoden hinzu. Sie implementieren sie in späteren Schritten.

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

Dadurch wird ein einfaches Menü implementiert und die Auswahl des Benutzers aus der Befehlszeile gelesen.

Hinzufügen einer reinen App-Authentifizierung

• 9 Minuten verbleibend

In diesem Abschnitt fügen Sie der Anwendung die reine App-Authentifizierung hinzu. Dies ist erforderlich, um das erforderliche OAuth-Zugriffstoken zum Aufrufen von Microsoft Graph abzurufen. In diesem Schritt integrieren Sie die Azure Identity-Clientbibliothek für .NET in die Anwendung und konfigurieren die Authentifizierung für die Microsoft Graph .NET-Clientbibliothek.

Die Azure Identity-Bibliothek bietet eine Reihe von TokenCredential Klassen, die OAuth2-Tokenflows implementieren. Die Microsoft Graph-Clientbibliothek verwendet diese Klassen, um Aufrufe von Microsoft Graph zu authentifizieren.

Konfigurieren des Graph-Clients für die reine App-Authentifizierung

In diesem Abschnitt verwenden Sie die ClientSecretCredential -Klasse, um mithilfe des Clientanmeldeinformationsflows ein Zugriffstoken anzufordern.

1. Erstellen Sie im Verzeichnis GraphTutorial eine neue Datei mit dem Namen GraphHelper.cs , und fügen Sie der Datei den folgenden Code hinzu.

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

2. Fügen Sie der GraphHelper-Klasse den folgenden Code hinzu.

   // 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. Ersetzen Sie die leere InitializeGraph Funktion in Program.cs durch Folgendes.

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

Dieser Code deklariert zwei private Eigenschaften, ein ClientSecretCredential -Objekt und ein GraphServiceClient -Objekt. Die InitializeGraphForAppOnlyAuth -Funktion erstellt eine neue Instanz von ClientSecretCredentialund verwendet diese Instanz dann, um eine neue Instanz von GraphServiceClientzu erstellen. Jedes Mal, wenn ein API-Aufruf an Microsoft Graph über _appClienterfolgt, werden die bereitgestellten Anmeldeinformationen verwendet, um ein Zugriffstoken abzurufen.

Testen von ClientSecretCredential

Fügen Sie als Nächstes Code hinzu, um ein Zugriffstoken ClientSecretCredentialvon abzurufen.

1. Fügen Sie die folgende Funktion zur GraphHelper-Klasse hinzu:

   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. Ersetzen Sie die leere DisplayAccessTokenAsync Funktion in Program.cs durch Folgendes.

   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. Erstellen Sie die App, und führen Sie sie aus. Geben Sie ein 1 , wenn Sie zur Eingabe einer Option aufgefordert werden. Die Anwendung zeigt ein Zugriffstoken an.

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

   Tipp

   Nur zu Validierungs- und Debugzwecken können Sie Nur-App-Zugriffstoken mithilfe des Onlinetokenparsers von Microsoft unter https://jwt.msdecodieren. Dies kann nützlich sein, wenn beim Aufrufen von Microsoft Graph Tokenfehler auftreten. Beispielsweise wird überprüft, ob der role Anspruch im Token die erwarteten Microsoft Graph-Berechtigungsbereiche enthält.

Benutzer auflisten

• 6 Minuten verbleibend

In diesem Abschnitt fügen Sie die Möglichkeit hinzu, alle Benutzer in Ihrer Azure Active Directory-Instanz mithilfe der reinen App-Authentifizierung aufzulisten.

1. Öffnen Sie ./GraphHelper.cs , und fügen Sie der GraphHelper-Klasse die folgende Funktion hinzu.

   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. Ersetzen Sie die leere ListUsersAsync Funktion in Program.cs durch Folgendes.

   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. Führen Sie die App aus, und wählen Sie Option 2 aus, um Benutzer aufzulisten.

   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
   

Code erläutert

Betrachten Sie den Code in der GetUsersAsync Funktion.

• Es ruft eine Sammlung von Benutzern ab.
• Wird verwendet Select , um bestimmte Eigenschaften anzufordern.
• Wird verwendet Top , um die Anzahl der zurückgegebenen Benutzer zu begrenzen.
• OrderBy Verwendet, um die Antwort zu sortieren.

Optional: Fügen Sie Ihren eigenen Code hinzu.

• 4 Minuten verbleibend

In diesem Abschnitt fügen Sie der Anwendung Ihre eigenen Microsoft Graph-Funktionen hinzu. Dies kann ein Codeausschnitt aus der Microsoft Graph-Dokumentation oder graph-Explorer oder code sein, den Sie erstellt haben. Dieser Abschnitt ist optional.

Aktualisieren der App

1. Öffnen Sie ./GraphHelper.cs , und fügen Sie der GraphHelper-Klasse die folgende Funktion hinzu.

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

2. Ersetzen Sie die leere MakeGraphCallAsync Funktion in Program.cs durch Folgendes.

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

Auswählen einer API

Suchen Sie eine API in Microsoft Graph, die Sie ausprobieren möchten. Beispiel: Die Api zum Erstellen eines Ereignisses . Sie können eines der Beispiele in der API-Dokumentation verwenden oder ein Beispiel anpassen.

Konfigurieren von Berechtigungen

Überprüfen Sie den Abschnitt Berechtigungen der Referenzdokumentation für Die ausgewählte API, um zu sehen, welche Authentifizierungsmethoden unterstützt werden. Einige APIs unterstützen z. B. keine reinen Apps oder persönlichen Microsoft-Konten.

• Informationen zum Aufrufen einer API mit Benutzerauthentifizierung (wenn die API die (delegierte) Benutzerauthentifizierung unterstützt), finden Sie im Tutorial zur benutzerseitig (delegierten) Authentifizierung .
• Um eine API mit nur app-Authentifizierung aufzurufen (sofern die API dies unterstützt), fügen Sie den erforderlichen Berechtigungsbereich im Azure AD Admin Center hinzu.

Fügen Sie Ihren Code hinzu

Kopieren Sie Ihren Code in die MakeGraphCallAsync Funktion in GraphHelper.cs. Wenn Sie einen Codeausschnitt aus der Dokumentation oder dem Graph-Explorer kopieren, müssen Sie den GraphServiceClient_appClientin umbenennen.

Herzlichen Glückwunsch!

• 100 % abgeschlossen!

Sie haben das Microsoft Graph-Tutorial für .NET abgeschlossen. Nachdem Sie nun über eine funktionierende App verfügen, die Microsoft Graph aufruft, können Sie experimentieren und neue Features hinzufügen.

• Erfahren Sie, wie Sie die (delegierte) Benutzerauthentifizierung mit dem Microsoft Graph .NET SDK verwenden.
• Besuchen Sie die Übersicht über Microsoft Graph , um alle Daten anzuzeigen, auf die Sie mit Microsoft Graph zugreifen können.

.NET-Beispiele

• ASP.NET Core MVC-App
• UWP-App (Universelle Windows-Plattform)
• Xamarin-App
• Blazor WebAssembly-App
• Azure Functions
• Bot Framework
• Teams-App
• Benachrichtigungen ändern
• ASP.NET Core-Codeausschnitte