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

2023-09-27

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

Diagramm: Zugreifen auf 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 von Microsoft Entra ID 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

Wenn Sie nicht über ein Azure-Konto verfügen, erstellen Sie ein kostenloses Konto , bevor Sie beginnen.

Voraussetzungen

Eine unter Azure App Service ausgeführte Webanwendung, für die das App Service-Modul für die Authentifizierung/Autorisierung aktiviert ist.

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.

Wählen Sie in Ihrer App Service-Instanz im linken Bereich die Option Identität und dann Vom System zugewiesen aus.
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.
Notieren Sie sich den Wert der Objekt-ID für den nächsten Schritt.

Screenshot: Systemseitig zugewiesene Identität

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 Microsoft Entra Admin Center zuzuweisen.

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

PowerShell
Azure-Befehlszeilenschnittstelle

# Install the module.
# Install-Module Microsoft.Graph -Scope CurrentUser

# The tenant ID
$TenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee"

# The name of your web app, which has a managed identity.
$webAppName = "SecureWebApp-20201106120003" 
$resourceGroupName = "SecureWebApp-20201106120003ResourceGroup"

# The name of the app role that the managed identity should be assigned to.
$appRoleName = "User.Read.All"

# Get the web app's managed identity's object ID.
Connect-AzAccount -Tenant $TenantId
$managedIdentityObjectId = (Get-AzWebApp -ResourceGroupName $resourceGroupName -Name $webAppName).identity.principalid

Connect-MgGraph -TenantId $TenantId -Scopes 'Application.Read.All','AppRoleAssignment.ReadWrite.All'

# Get Microsoft Graph app's service principal and app role.
$serverApplicationName = "Microsoft Graph"
$serverServicePrincipal = (Get-MgServicePrincipal -Filter "DisplayName eq '$serverApplicationName'")
$serverServicePrincipalObjectId = $serverServicePrincipal.Id

$appRoleId = ($serverServicePrincipal.AppRoles | Where-Object {$_.Value -eq $appRoleName }).Id

# Assign the managed identity access to the app role.
New-MgServicePrincipalAppRoleAssignment `
    -ServicePrincipalId $managedIdentityObjectId `
    -PrincipalId $managedIdentityObjectId `
    -ResourceId $serverServicePrincipalObjectId `
    -AppRoleId $appRoleId

az login

webAppName="SecureWebApp-20201106120003"

spId=$(az resource list -n $webAppName --query [*].identity.principalId --out tsv)

graphResourceId=$(az ad sp list --display-name "Microsoft Graph" --query [0].id --out tsv)

appRoleId=$(az ad sp list --display-name "Microsoft Graph" --query "[0].appRoles[?value=='User.Read.All' && contains(allowedMemberTypes, 'Application')].id" --output tsv)

uri=https://graph.microsoft.com/v1.0/servicePrincipals/$spId/appRoleAssignments

body="{'principalId':'$spId','resourceId':'$graphResourceId','appRoleId':'$appRoleId'}"

az rest --method post --uri $uri --body $body --headers "Content-Type=application/json"

Nachdem Sie das Skript ausgeführt haben, können Sie im Microsoft Entra Admin Center überprüfen, ob der verwalteten Identität die angeforderten API-Berechtigungen zugewiesen wurden.
Wechseln Sie zu Anwendungen und dann zu Unternehmensanwendungen. In diesem Bereich werden alle Dienstprinzipale Ihres Mandanten angezeigt. Fügen Sie einen Filter für „Anwendungstyp == Verwaltete Identitäten“ hinzu, und wählen Sie 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.
Wählen Sie den Dienstprinzipal für die verwaltete Identität aus.
Wenn Sie unter Übersicht die Option Berechtigungen auswählen, werden die hinzugefügten Berechtigungen für Microsoft Graph angezeigt.

Microsoft Graph mit Node.js aufrufen

Ihre Web-App verfügt jetzt über die erforderlichen Berechtigungen, und den Anmeldeparametern wird die Client-ID von Microsoft Graph hinzugefügt.

Die DefaultAzureCredential-Klasse aus dem Paket DefaultAzureCredential wird zum Abrufen von Tokenanmeldeinformationen für Ihren Code verwendet, um Anforderungen für Azure Storage zu autorisieren. Erstellen Sie eine Instanz der Klasse DefaultAzureCredential, bei der die verwaltete Identität zum Abrufen von Token verwendet wird, und fügen Sie diese an den Dienstclient an. Im folgenden Codebeispiel werden die authentifizierten Tokenanmeldeinformationen abgerufen und zum Erstellen eines Dienstclientobjekts verwendet, mit dem die Benutzer der Gruppe abgerufen werden.

Hinweis

Das @azure/identity-Paket wird in Deiner Web-App für die grundlegende Authentifizierung/Autorisierung oder zur Authentifizierung von Anfragen mit Microsoft Graph nicht benötigt. Es ist möglich, Downstream-APIs auf sichere Weise aufzurufen, wenn nur das App Service-Modul für die Authentifizierung/Autorisierung aktiviert ist.

Die Authentifizierung/Autorisierung von App Service ist für grundlegendere Authentifizierungsszenarios ausgelegt. Für komplexere Szenarien (z.B. die Bearbeitung von benutzerdefinierten Ansprüchen) benötigst Du das @azure/identity-Paket. Am Anfang muss etwas mehr eingerichtet und konfiguriert werden, aber das @azure/identityPaket kann neben dem App Service Authentifizierungs-/Autorisierungsmodul ausgeführt werden. Später, wenn Deine Web-App komplexere Szenarien bewältigen muss, kannst Du das Authentifizierungs-/Autorisierungsmodul des App-Dienstes deaktivieren und es @azure/identitywird bereits Teil Deiner App sein.

Installieren von Clientbibliothekspaketen

Installieren Sie die Pakete @azure/Identity und @microsoft/microsoft-graph-client in Ihrem Projekt mit npm.

npm install @azure/identity @microsoft/microsoft-graph-client

Konfigurieren von Authentifizierungsinformationen

// partial code in app.js
const appSettings = {
    appCredentials: {
        clientId: process.env.WEBSITE_AUTH_CLIENT_ID, // Enter the client Id here,
        tenantId: "common", // Enter the tenant info here,
        clientSecret: process.env.MICROSOFT_PROVIDER_AUTHENTICATION_SECRET // Enter the client secret here,
    },
    authRoutes: {
        redirect: "/.auth/login/aad/callback", // Enter the redirect URI here
        unauthorized: "/unauthorized" // enter the relative path to unauthorized route
    },
}

Aufrufen von Microsoft Graph im Auftrag der App

Im folgenden Code wird gezeigt, wie Sie den Microsoft Graph-Controller als App aufrufen und Benutzerinformationen abrufen.

// graphController.js

const graphHelper = require('../utils/graphHelper');
const { DefaultAzureCredential } = require("@azure/identity");

exports.getUsersPage = async(req, res, next) => {

    const defaultAzureCredential = new DefaultAzureCredential();
    
    try {
        // get app's access token scoped to Microsoft Graph
        const tokenResponse = await defaultAzureCredential.getToken("https://graph.microsoft.com/.default");

        // use token to create Graph client
        const graphClient = graphHelper.getAuthenticatedClient(tokenResponse.token);

        // return profiles of users in Graph
        const users = await graphClient
            .api('/users')
            .get();

        res.render('users', { user: req.session.user, users: users });   
    } catch (error) {
        next(error);
    }
}

Der vorherige Code basiert auf der folgenden getAuthenticatedClient-Funktion, um den Microsoft Graph-Client zurückzugeben.

// utils/graphHelper.js

const graph = require('@microsoft/microsoft-graph-client');

getAuthenticatedClient = (accessToken) => {
    // Initialize Graph client
    const client = graph.Client.init({
        // Use the provided access token to authenticate requests
        authProvider: (done) => {
            done(null, accessToken);
        }
    });

    return client;
}

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: Löschen der Ressourcengruppe

Die Ausführung dieses Befehls kann mehrere Minuten dauern.

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

Erfahren Sie, wie Sie eine .NET Core-App oder Node.js-App mit einer Datenbank verbinden.

Freigeben über