Tutorial: Zugreifen auf Microsoft Graph über eine geschützte .NET-App als App

Es wird beschrieben, wie Sie über eine Web-App, die in Azure App Service ausgeführt wird, auf Microsoft Graph zugreifen.

Diagram that shows accessing Microsoft Graph.

Sie möchten Microsoft Graph für die Web-App aufrufen. Eine sichere Methode, um Ihrer Web-App den Zugriff auf Daten zu gewähren, ist die Verwendung einer systemseitig zugewiesenen verwalteten Identität. Mit einer verwalteten Identität aus Azure Active Directory kann App Service mittels rollenbasierter Zugriffssteuerung (Role-Based Access Control, RBAC) auf Ressourcen zugreifen, ohne dass App-Anmeldeinformationen benötigt werden. Nachdem Sie Ihrer Web-App eine verwaltete Identität zugewiesen haben, kümmert sich Azure um die Erstellung und Verteilung eines Zertifikats. Sie müssen sich keine Gedanken über die Verwaltung von Geheimnissen oder App-Anmeldeinformationen machen.

In diesem Tutorial lernen Sie Folgendes:

  • Erstellen einer systemseitig zugewiesenen verwalteten Identität in einer Web-App
  • Hinzufügen von Microsoft Graph-API-Berechtigungen zu einer verwalteten Identität
  • Aufrufen von Microsoft Graph über eine Web-App unter Verwendung verwalteter Identitäten

Sollten Sie über kein Azure-Abonnement verfügen, können Sie zunächst ein kostenloses Azure-Konto erstellen.

Voraussetzungen

Aktivieren einer verwalteten Identität für die App

Wenn Sie Ihre Web-App mit Visual Studio erstellen und veröffentlichen, wird die verwaltete Identität für Sie in Ihrer App aktiviert.

  1. Wählen Sie in Ihrer App Service-Instanz im linken Bereich die Option Identität und dann Vom System zugewiesen aus.

  2. Vergewissern Sie sich, dass der Status auf Ein festgelegt ist. Falls nicht: Wählen Sie Speichern und dann Ja aus, um die systemseitig zugewiesene verwaltete Identität zu aktivieren. Wenn die verwaltete Identität aktiviert ist, ist der Status auf Ein festgelegt, und die Objekt-ID ist verfügbar.

  3. Notieren Sie sich den Wert der Objekt-ID für den nächsten Schritt.

Screenshot that shows the system-assigned identity.

Gewähren von Zugriff auf Microsoft Graph

Beim Zugreifen auf Microsoft Graph muss die verwaltete Identität über die entsprechenden Berechtigungen für den Vorgang verfügen, der ausgeführt werden soll. Derzeit gibt es keine Möglichkeit, diese Berechtigungen über das Azure-Portal zuzuweisen.

  1. Führen Sie das folgende Skript aus, um die angeforderten Microsoft Graph-API-Berechtigungen dem Dienstprinzipalobjekt der verwalteten Identität hinzuzufügen.

    # Install the module. (You need admin on the machine.)
    # Install-Module AzureAD.
    
    # Your tenant ID (in the Azure portal, under Azure Active Directory > Overview).
    $TenantID="<tenant-id>"
    $resourceGroup = "securewebappresourcegroup"
    $webAppName="SecureWebApp-20201102125811"
    
    # Get the ID of the managed identity for the web app.
    $spID = (Get-AzWebApp -ResourceGroupName $resourceGroup -Name $webAppName).identity.principalid
    
    # Check the Microsoft Graph documentation for the permission you need for the operation.
    $PermissionName = "User.Read.All"
    
    Connect-AzureAD -TenantId $TenantID
    
    # Get the service principal for Microsoft Graph.
    # First result should be AppId 00000003-0000-0000-c000-000000000000
    $GraphServicePrincipal = Get-AzureADServicePrincipal -SearchString "Microsoft Graph" | Select-Object -first 1
    
    # Assign permissions to the managed identity service principal.
    $AppRole = $GraphServicePrincipal.AppRoles | `
    Where-Object {$_.Value -eq $PermissionName -and $_.AllowedMemberTypes -contains "Application"}
    
    New-AzureAdServiceAppRoleAssignment -ObjectId $spID -PrincipalId $spID `
    -ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole.Id
    
  2. Nachdem Sie das Skript ausgeführt haben, können Sie im Azure-Portal überprüfen, ob die angeforderten API-Berechtigungen der verwalteten Identität zugewiesen wurden.

  3. Navigieren Sie zu Azure Active Directory, und wählen Sie Unternehmensanwendungen aus. In diesem Bereich werden alle Dienstprinzipale Ihres Mandanten angezeigt. Wählen Sie unter Verwaltete Identitäten den Dienstprinzipal für die verwaltete Identität aus.

    In diesem Tutorial werden zwei Dienstprinzipale mit dem gleichen Anzeigenamen verwendet (z. B. „SecureWebApp2020094113531“). Der Dienstprinzipal mit einer URL für Startseite steht für die Web-App Ihres Mandanten. Für den Dienstprinzipal, der unter Verwaltete Identitäten angezeigt wird, sollte keineHomepage-URL aufgeführt sein, und die Objekt-ID sollte mit dem Objekt-ID-Wert der verwalteten Identität im vorherigen Schritt übereinstimmen.

  4. Wählen Sie den Dienstprinzipal für die verwaltete Identität aus.

    Screenshot that shows the All applications option.

  5. Wenn Sie unter Übersicht die Option Berechtigungen auswählen, werden die hinzugefügten Berechtigungen für Microsoft Graph angezeigt.

    Screenshot that shows the Permissions pane.

Aufrufen von Microsoft Graph

Die Klassen ChainedTokenCredential, ManagedIdentityCredential und EnvironmentCredential werden verwendet, um Tokenanmeldeinformationen für Ihren Code zum Autorisieren von Anforderungen an Microsoft Graph abzurufen. Erstellen Sie eine Instanz der ChainedTokenCredential-Klasse, die die verwaltete Identität in der App Service-Umgebung oder die Entwicklungsumgebungsvariablen verwendet, um Token abrufen und an den Dienstclient anfügen zu können. Im folgenden Codebeispiel werden die authentifizierten Tokenanmeldeinformationen abgerufen und zum Erstellen eines Dienstclientobjekts verwendet, mit dem die Benutzer der Gruppe abgerufen werden.

Diesen Code können Sie sich in einer Beispielanwendung ansehen unter:

Installieren des Pakets mit der Clientbibliothek „Microsoft.Identity.Web.MicrosoftGraph“

Installieren Sie das NuGet-Paket Microsoft.Identity.Web.MicrosoftGraph in Ihrem Projekt, indem Sie die .NET Core-Befehlszeilenschnittstelle oder die Paket-Manager-Konsole in Visual Studio verwenden.

.NET Core-Befehlszeile

Öffnen Sie eine Befehlszeile, und wechseln Sie zu dem Verzeichnis, in dem Ihre Projektdatei enthalten ist.

Führen Sie die Installationsbefehle aus.

dotnet add package Microsoft.Identity.Web.MicrosoftGraph

Paket-Manager-Konsole

Öffnen Sie das Projekt bzw. die Projektmappe in Visual Studio, und navigieren Sie zu Extras>NuGet-Paket-Manager>Paket-Manager-Konsole, um die Konsole zu öffnen.

Führen Sie die Installationsbefehle aus.

Install-Package Microsoft.Identity.Web.MicrosoftGraph

.NET-Beispiel

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc.RazorPages;
using Azure.Identity;​
using Microsoft.Graph.Core;​​
using System.Net.Http.Headers;

...

public IList<MSGraphUser> Users { get; set; }

public async Task OnGetAsync()
{
    // Create the Graph service client with a ChainedTokenCredential which gets an access
    // token using the available Managed Identity or environment variables if running
    // in development.
    var credential = new ChainedTokenCredential(
        new ManagedIdentityCredential(),
        new EnvironmentCredential());
    var token = credential.GetToken(
        new Azure.Core.TokenRequestContext(
            new[] { "https://graph.microsoft.com/.default" }));

    var accessToken = token.Token;
    var graphServiceClient = new GraphServiceClient(
        new DelegateAuthenticationProvider((requestMessage) =>
        {
            requestMessage
            .Headers
            .Authorization = new AuthenticationHeaderValue("bearer", accessToken);

            return Task.CompletedTask;
        }));

    // MSGraphUser is a DTO class being used to hold User information from the graph service client call
    List<MSGraphUser> msGraphUsers = new List<MSGraphUser>();
    try
    {
        var users =await graphServiceClient.Users.Request().GetAsync();
        foreach(var u in users)
        {
            MSGraphUser user = new MSGraphUser();
            user.userPrincipalName = u.UserPrincipalName;
            user.displayName = u.DisplayName;
            user.mail = u.Mail;
            user.jobTitle = u.JobTitle;

            msGraphUsers.Add(user);
        }
    }
    catch(Exception ex)
    {
        string msg = ex.Message;
    }

    Users = msGraphUsers;
}

Bereinigen von Ressourcen

Wenn Sie dieses Tutorial abgeschlossen haben und die Web-App und die zugehörigen Ressourcen nicht mehr benötigen, sollten Sie die von Ihnen erstellten Ressourcen bereinigen.

Löschen der Ressourcengruppe

Wählen Sie im Azure-Portal im Portalmenü die Option Ressourcengruppen und dann die Ressourcengruppe aus, die Ihren App-Dienst und den App Service-Plan enthält.

Wählen Sie Ressourcengruppe löschen aus, um die Ressourcengruppe und alle Ressourcen zu löschen.

Screenshot that shows deleting the resource group.

Die Ausführung dieses Befehls kann mehrere Minuten dauern.

Löschen der App-Registrierung

Wählen Sie im Menü des Portals Azure Active DirectoryApp-Registrierungen aus. Wählen Sie anschließend die von Ihnen erstellte Anwendung aus. Screenshot that shows selecting app registration.

Wählen Sie in der Übersicht der App-Registrierungen die Option Löschen aus. Screenshot that shows deleting the app registration.

Nächste Schritte

In diesem Tutorial haben Sie Folgendes gelernt:

  • Erstellen einer systemseitig zugewiesenen verwalteten Identität in einer Web-App
  • Hinzufügen von Microsoft Graph-API-Berechtigungen zu einer verwalteten Identität
  • Aufrufen von Microsoft Graph über eine Web-App unter Verwendung verwalteter Identitäten

Informieren Sie sich darüber, wie Sie für eine .NET Core-App, Python-App, Java-App oder Node.js-App eine Verbindung mit einer Datenbank herstellen.