Microsoft Graph Toolkit-Anbieter

Die Microsoft Graph Toolkit-Anbieter ermöglichen Es Ihrer Anwendung, sich bei Microsoft Identity zu authentifizieren und in nur wenigen Codezeilen auf Microsoft Graph zuzugreifen. Jeder Anbieter verarbeitet die Benutzerauthentifizierung und den Erwerb der Zugriffstoken, um Microsoft Graph-APIs aufzurufen, damit Sie diesen Code nicht selbst schreiben müssen.

Sie können die Anbieter selbst ohne Komponenten verwenden, um die Authentifizierung für Ihre App schnell zu implementieren und Aufrufe an Microsoft Graph über das JavaScript-Client-SDK zu tätigen.

Die Anbieter sind erforderlich, wenn sie die Microsoft Graph Toolkit-Komponenten als Komponenten verwenden, die sie für den Zugriff auf Microsoft Graph verwenden. Wenn Sie bereits über eine eigene Authentifizierung verfügen und die Komponenten verwenden möchten, können Sie stattdessen einen benutzerdefinierten Anbieter verwenden.

Das Toolkit umfasst die folgenden Anbieter.

Anbieter Beschreibung
MSAL Verwendet msal.js, um Benutzer anzumelden und Token für die Verwendung mit Microsoft Graph in einer Webanwendung zu erwerben.
MSAL2 Verwendet msal-browser, um Benutzer anzumelden und Token für die Verwendung mit Microsoft Graph in einer Webanwendung zu erwerben.
Elektron Authentifiziert und bietet Microsoft Graph Zugriff auf Komponenten innerhalb von Atom-Apps.
SharePoint Authentifiziert und bietet Microsoft Graph Zugriff auf Komponenten innerhalb SharePoint Webparts.
Microsoft Teams Verwendet msal.js, um Benutzer anzumelden und Token auf dem Client in Microsoft Teams Registerkarten zu erwerben.
Teams MSAL2 Verwendet msal-browser, um Benutzer anzumelden und Token in Microsoft Teams Registerkarten zu erwerben. Unterstützt einzelne Sign-On mit benutzerdefiniertem Back-End.
Proxy Ermöglicht die Verwendung der Back-End-Authentifizierung durch Weiterleiten aller Aufrufe an Microsoft Graph über Ihr Back-End.
Custom Erstellen Sie einen benutzerdefinierten Anbieter, um die Authentifizierung und den Zugriff auf Microsoft Graph mit dem vorhandenen Authentifizierungscode Ihrer Anwendung zu aktivieren.

Initialisieren eines Anbieters

Um einen Anbieter in Ihrer App zu verwenden, müssen Sie einen neuen Anbieter initialisieren und ihn dann als globalen Anbieter im Anbieternamespace festlegen. Wir empfehlen, dies zu tun, bevor Sie mit der Verwendung einer der Komponenten beginnen. Sie können dies auf zwei Arten tun:

Option 1: Verwenden der Anbieterkomponente

Sie können die Komponentenversion des Anbieters direkt in Ihrem HTML-Code verwenden. Im Hintergrund wird ein neuer Anbieter initialisiert und als globaler Anbieter festgelegt. Das folgende Beispiel zeigt die Verwendung des MSAL2-Anbieters.

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>

Option 2: Initialisieren im Code

Wenn Sie Ihren Anbieter in Ihrem JavaScript-Code initialisieren, können Sie weitere Optionen bereitstellen. Erstellen Sie dazu eine neue Anbieterinstanz, und legen Sie den Wert der Providers.globalProvider Eigenschaft auf den Anbieter fest, den Sie verwenden möchten. Das folgende Beispiel zeigt die Verwendung des MSAL2-Anbieters.

import {Providers, Msal2Provider } from "@microsoft/mgt";
Providers.globalProvider = new Msal2Provider({
  clientId: 'YOUR_CLIENT_ID'
});

Hinweis: Ausführliche Informationen zum Registrieren Ihrer App und zum Abrufen einer Client-ID finden Sie unter Erstellen einer Azure Active Directory-App.

Berechtigungsbereiche

Es wird empfohlen, beim Initialisieren des Anbieters alle Berechtigungsbereiche, die Ihre Anwendung benötigt, dem Attribut oder der scopes Eigenschaft hinzuzufügen (dies gilt nicht für den SharePoint Anbieter). Dies ist optional, verbessert jedoch die Benutzererfahrung, indem dem Benutzer ein einzelner Zustimmungsbildschirm mit einer aggregierten Liste von Berechtigungen angezeigt wird, die von allen Komponenten in Ihrer App angefordert werden, anstatt separate Bildschirme für jede Komponente anzuzeigen. In den folgenden Beispielen wird gezeigt, wie dies mit dem MSAL2-Anbieter geschieht.

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"
                   scopes="user.read,people.read"
                   ></mgt-msal2-provider>

Wenn Sie den Anbieter im Code initialisieren, geben Sie die Berechtigungsbereiche in einem Array in der Eigenschaft an scopes .

import {Providers, Msal2Provider } from "@microsoft/mgt";
Providers.globalProvider = new Msal2Provider({
  clientId: 'YOUR_CLIENT_ID'
  scopes:['user.read','people.read']
});

Die Liste der Berechtigungsbereiche, die für jede Komponente erforderlich sind, finden Sie im Abschnitt "Microsoft Graph Berechtigungen" auf der Dokumentationsseite jeder Komponente.

Anbieterstatus

Der Anbieter verfolgt den Authentifizierungsstatus des Benutzers und teilt ihn den Komponenten mit. Wenn sich beispielsweise ein Benutzer erfolgreich anmeldet, wird dieser ProviderState auf SignedInaktualisiert und signalisiert den Komponenten, dass er jetzt Aufrufe an Microsoft Graph tätigen kann. Die ProviderState Enumeration definiert drei Zustände, wie dargestellt.

export enum ProviderState {
  Loading,
  SignedOut,
  SignedIn
}

In einigen Szenarien sollten Sie bestimmte Funktionen anzeigen oder eine Aktion erst ausführen, nachdem sich ein Benutzer erfolgreich angemeldet hat. Sie können auf den Anbieterstatus zugreifen und diesen überprüfen, wie im folgenden Beispiel gezeigt.

import { Providers, ProviderState } from '@microsoft/mgt'

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  //your code here
}

Sie können die Providers.onProviderUpdated Methode auch verwenden, um benachrichtigt zu werden, wenn sich der Status des Anbieters ändert.

import { Providers, ProviderState } from "@microsoft/mgt";

//assuming a provider has already been initialized

const providerStateChanged = () => {
  if (Providers.globalProvider.state === ProviderState.SignedIn) {
    // user is now signed in
  }
}

// register a callback for when the state changes
Providers.onProviderUpdated(providerStateChanged);

// remove callback if necessary
Providers.removeProviderUpdatedListener(providerStateChanged);

Abrufen eines Zugriffstokens

Jeder Anbieter macht eine aufgerufene getAccessToken Funktion verfügbar, die das aktuelle Zugriffstoken oder ein neues Zugriffstoken für die bereitgestellten Bereiche abrufen kann. Das folgende Beispiel zeigt, wie Sie ein neues Zugriffstoken mit dem User.Read Berechtigungsbereich abrufen.

import { Providers, ProviderState } from "@microsoft/mgt";

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  const token = await Providers.globalProvider.getAccessToken({scopes: ['User.Read']})
}

Eigene Anrufe an Microsoft Graph

Alle Komponenten können auf Microsoft Graph zugreifen, ohne dass Anpassungen erforderlich sind, solange Sie einen Anbieter initialisieren (wie in den vorherigen Abschnitten beschrieben). Wenn Sie Ihre eigenen Aufrufe an Microsoft Graph durchführen möchten, erhalten Sie dazu einen Verweis auf dasselbe Microsoft Graph SDK, das von den Komponenten verwendet wird. Rufen Sie zunächst einen Verweis auf das globale IProvider Objekt ab, und verwenden Sie dann das graph Objekt wie dargestellt:

import { Providers } from '@microsoft/mgt';

let provider = Providers.globalProvider;
if (provider) {
  let graphClient = provider.graph.client;
  let userDetails = await graphClient.api('me').get();
}

Es kann Fälle geben, in denen Sie je nach aufgerufener API zusätzliche Berechtigungen übergeben müssen. Im folgenden Beispiel wird dies veranschaulicht.

import { prepScopes } from '@microsoft/mgt';

graphClient
  .api('me')
  .middlewareOptions(prepScopes('user.read', 'calendar.read'))
  .get();

Verwenden mehrerer Anbieter

In einigen Szenarien wird Ihre Anwendung in verschiedenen Umgebungen ausgeführt und erfordert jeweils einen anderen Anbieter. Beispielsweise kann die App sowohl als Webanwendung als auch als Microsoft Teams Registerkarte ausgeführt werden, was bedeutet, dass Sie möglicherweise sowohl den MSAL2-Anbieter als auch den Teams MSAL2-Anbieter verwenden müssen. In diesem Szenario verfügen alle Anbieterkomponenten über das depends-on Attribut zum Erstellen einer Fallbackkette, wie im folgenden Beispiel dargestellt.

<mgt-teams-msal2-provider
  client-id="[CLIENT-ID]"
  auth-popup-url="auth.html" ></mgt-teams-msal2-provider>

<mgt-msal2-provider
  client-id="[CLIENT-ID]"
  depends-on="mgt-teams-provider" ></mgt-msal2-provider>

In diesem Szenario wird der MSAL2-Anbieter nur verwendet, wenn Ihre App als Webanwendung ausgeführt wird und der Teams MSAL2-Anbieter in der aktuellen Umgebung nicht verfügbar ist.

Um dies im Code zu erreichen, können Sie die isAvailable Eigenschaft für den Anbieter wie dargestellt verwenden.

if (TeamsProvider.isAvailable) {
    Providers.globalProvider = new TeamsProvider(teamsConfig);
} else {
    Providers.globalProvider = new Msal2Provider(msalConfig)
}

Benutzeranmeldung/-abmeldung

Wenn Sie die richtigen Anbieter für Ihre Anwendung initialisiert haben, können Sie die Anmeldekomponente des Toolkits hinzufügen, um die Benutzeranmeldung und -abmeldung einfach und schnell zu implementieren. Die Komponente arbeitet mit dem Anbieter zusammen, um alle Authentifizierungslogik und Anmelde-/Abmeldefunktionen zu verarbeiten. Im folgenden Beispiel werden der MSAL2-Anbieter und die Login-Komponente verwendet.

<script src="https://unpkg.com/@microsoft/mgt/dist/bundle/mgt-loader.js"></script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>
<mgt-login></mgt-login>

In Szenarien, in denen Sie dies selbst implementieren möchten, anstatt die Anmeldekomponente des Toolkits zu verwenden, können Sie dies mithilfe der login und logout Methoden des Anbieters tun.

Implementieren Eines eigenen Anbieters

In Szenarien, in denen Sie Einer Anwendung Toolkit-Komponenten mit bereits vorhandenem Authentifizierungscode hinzufügen möchten, können Sie einen benutzerdefinierten Anbieter erstellen, der in Ihren Authentifizierungsmechanismus integriert ist, anstatt unsere vordefinierten Anbieter zu verwenden. Das Toolkit bietet zwei Möglichkeiten zum Erstellen neuer Anbieter:

  • Erstellen Sie ein neues SimpleProvider Token, das ein Zugriffstoken aus Ihrem Authentifizierungscode zurückgibt, indem Sie eine Funktion übergeben.
  • Erweitern Sie die IProvider abstrakte Klasse.

Weitere Informationen zu den einzelnen Anbietern finden Sie unter benutzerdefinierte Anbieter.