Anbieter des Microsoft Graph-Toolkits

Artikel
10/18/2023

Die Anbieter des Microsoft Graph-Toolkits ermöglichen es Ihrer Anwendung, sich mit Microsoft Identity zu authentifizieren und in nur wenigen Codezeilen auf Microsoft Graph zuzugreifen. Jeder Anbieter übernimmt die Benutzerauthentifizierung und das Abrufen der Zugriffstoken zum Aufrufen von Microsoft Graph-APIs, sodass Sie diesen Code nicht selbst schreiben müssen.

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

Die Anbieter sind erforderlich, wenn Sie die Komponenten des Microsoft Graph-Toolkits verwenden, da die Komponenten 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 enthält die folgenden Anbieter.

Anbieter	Beschreibung
Custom	Erstellt einen benutzerdefinierten Anbieter, um die Authentifizierung und den Zugriff auf Microsoft Graph mithilfe des vorhandenen Authentifizierungscodes Ihrer Anwendung zu ermöglichen.
Elektron	Authentifiziert und bietet Microsoft Graph-Zugriff auf Komponenten innerhalb von Electron-Apps.
MSAL2	Verwendet den MSAL-Browser, um Benutzer anzumelden und Token für die Verwendung mit Microsoft Graph abzurufen.
Proxy	Ermöglicht die Verwendung der Back-End-Authentifizierung, indem alle Aufrufe an Microsoft Graph über Ihr Back-End weitergeleitet werden.
SharePoint	Authentifiziert und bietet Microsoft Graph-Zugriff auf Komponenten innerhalb von SharePoint-Webparts.
TeamsFx	Verwenden Sie den TeamsFx-Anbieter in Ihren Microsoft Teams-Anwendungen, um Komponenten des Microsoft Graph-Toolkits Zugriff auf Microsoft Graph zu gewähren.

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 Providers-Namespace festlegen. Es wird empfohlen, dies zu tun, bevor Sie mit der Verwendung einer der Komponenten beginnen. Hierfür gibt es zwei Möglichkeiten:

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 type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</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 hierzu einen neuen Anbieter instance 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 } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
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 Microsoft Entra-App.

Berechtigungsbereiche

Es wird empfohlen, alle Berechtigungsbereiche, die Ihre Anwendung benötigt, dem Attribut oder der scopes Eigenschaft hinzuzufügen, wenn Sie Ihren Anbieter initialisieren (dies gilt nicht für den SharePoint-Anbieter). Dies ist optional, verbessert jedoch Die Benutzerfreundlichkeit, 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. Die folgenden Beispiele zeigen, wie dies mit dem MSAL2-Anbieter funktioniert.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</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 } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
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.

Benutzerdefinierte Hosts

Sie können benutzerdefinierte Hosts für den Microsoft Graph-Client angeben. Dadurch können Sie nicht von Microsoft Graph Microsoft Entra ID gesicherte APIs aufrufen. Wenn Sie benutzerdefinierte Hosts angeben, stellen Sie sicher, dass Sie den Bereich für das Zugriffstoken anfordern.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider 
  client-id="YOUR_CLIENT_ID"
  custom-hosts="myapi.com,anotherapi.com"
></mgt-msal2-provider>

Wenn Sie den Anbieter im Code initialisieren, geben Sie die Hostnamen in einem Array in der -Eigenschaft an customHosts .

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: 'YOUR_CLIENT_ID',
  customHosts: ['myapi.com','anotherapi.com']
});

Hinweis: Dies sind Hostnamen, keine URIs.

Um die benutzerdefinierten APIs aufzurufen, fordern Sie diesen API-Bereich an.

<mgt-get resource="https://myapi.com/v1.0/api" scopes="api://CUSTOM_API_GUID/SCOPE">
  ...
</mgt-get>

Oder über Javascript/Typescript:

import { prepScopes } from "@microsoft/mgt-element";

graphClient
  .api("https://myapi.com/v1.0/api")
  .middlewareOptions(prepScopes("api://CUSTOM_API_GUID/SCOPE"))
  .get();
...

Anbieterstatus

Der Anbieter verfolgt den Authentifizierungsstatus des Benutzers nach und kommuniziert ihn an die Komponenten. Wenn sich ein Benutzer beispielsweise erfolgreich anmeldet, wird auf ProviderState aktualisiert SignedIn, was den Komponenten signalisiert, dass sie jetzt Aufrufe an Microsoft Graph senden können. Die ProviderState Enumeration definiert drei Zustände, wie gezeigt.

export enum ProviderState {
  Loading,
  SignedOut,
  SignedIn,
}

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

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

//assuming a provider has already been initialized

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

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

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

//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 Funktion namens getAccessToken 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-element";

//assuming a provider has already been initialized

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

Eigene Aufrufe 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 eigene Aufrufe an Microsoft Graph senden möchten, können Sie dazu einen Verweis auf dasselbe Microsoft Graph SDK abrufen, das von den Komponenten verwendet wird. Rufen Sie zunächst einen Verweis auf die globale IProvider ab, und verwenden Sie dann das graph -Objekt wie gezeigt:

import { Providers } from "@microsoft/mgt-element";

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 abhängig von der API, die Sie aufrufen, zusätzliche Berechtigungen übergeben müssen. Im folgenden Beispiel wird dies veranschaulicht.

import { prepScopes } from "@microsoft/mgt-element";

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. Dies bedeutet, dass Sie möglicherweise sowohl den MSAL2-Anbieter als auch den Microsoft 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 gezeigt.

<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 auch im Code zu erreichen, können Sie die isAvailable -Eigenschaft für den Anbieter verwenden, wie gezeigt.

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 die gesamte Authentifizierungslogik und Die Anmelde-/Abmeldefunktionalität zu verarbeiten. Im folgenden Beispiel werden der MSAL2-Anbieter und die Anmeldekomponente verwendet.

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</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 Methoden und logout des Anbieters tun.

Implementieren Eines eigenen Anbieters

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

Erstellen Sie eine neue SimpleProvider , die 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.