Anbieter des Microsoft Graph-Toolkits
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.
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter:Einreichen und Feedback anzeigen für