Erweitern der Registerkarten-App mit Microsoft Graph-Berechtigungen und -Bereichen

Artikel
06/26/2024

Sie können Ihre Registerkarten-App erweitern, indem Sie Microsoft Graph verwenden, um zusätzliche Benutzerberechtigungen zuzulassen, z. B. zum Anzeigen eines App-Benutzerprofils, zum Lesen von E-Mails und mehr. Ihre App muss bestimmte Berechtigungsbereiche anfordern, um die Zugriffstoken nach zustimmung des App-Benutzers abzurufen.

Graphbereiche wie User.Read oder Mail.Readgeben an, auf welche Elemente Ihre App über ein Teams-Benutzerkonto zugreifen kann. Sie müssen Ihre Bereiche in der Autorisierungsanforderung angeben. Dieser Artikel führt Sie durch die Schritte zum Konfigurieren von Microsoft Graph-Berechtigungen und -Bereichen für Ihre Teams-Registerkarten-App.

Konfigurieren von API-Berechtigungen in Microsoft Entra ID

Sie können zusätzliche Graph-Bereiche in Microsoft Entra ID für Ihre App konfigurieren. Hierbei handelt es sich um delegierte Berechtigungen, die von Apps verwendet werden, die angemeldeten Zugriff erfordern. Ein angemeldeter App-Benutzer oder Administrator muss ihnen zunächst zustimmen. Danach kann Ihre Registerkarten-App im Namen des angemeldeten Benutzers zustimmen, wenn sie Microsoft Graph aufruft.

Es wird empfohlen, delegierte Berechtigungen für den angemeldeten Benutzer zu verwenden. Wenn Ihre Anwendung keinen angemeldeten Benutzer benötigt, sollten Sie die Verwendung von Anwendungsberechtigungen in Betracht ziehen, die auch als Reine-App-Zugriffsszenario bezeichnet werden. Nur Administratoren können die Zustimmung für Anwendungsberechtigungen erteilen. Weitere Informationen finden Sie unter Anwendungsberechtigungen.

So konfigurieren Sie API-Berechtigungen

Öffnen Sie die App, die Sie im Azure-Portal registriert haben.
Wählen Sie im linken BereichAPI-Berechtigungen verwalten> aus.

Die Seite API-Berechtigungen wird angezeigt.
Wählen Sie + Berechtigung hinzufügen aus, um Microsoft Graph-API-Berechtigungen hinzuzufügen.

Die Seite API-Berechtigungen anfordern wird angezeigt.
Wählen Sie Microsoft Graph aus.

Die Optionen für Graph-Berechtigungen werden angezeigt.
Wählen Sie Delegierte Berechtigungen oder Anwendungsberechtigungen aus, um die Liste der delegierten Berechtigungen bzw. Anwendungsberechtigungen anzuzeigen.
Wählen Sie die relevanten Berechtigungen für Ihre App und dann Berechtigungen hinzufügen aus.

Sie können auch den Berechtigungsnamen in das Suchfeld eingeben, um ihn zu finden.

Im Browser wird eine Meldung angezeigt, die besagt, dass die Berechtigungen aktualisiert wurden.

Die hinzugefügten Berechtigungen werden auf der Seite API-Berechtigungen angezeigt.

Sie haben Ihre App jetzt mit Microsoft Graph-Berechtigungen konfiguriert.

Konfigurieren der Authentifizierung für verschiedene Plattformen

Abhängig von der Plattform oder dem Gerät, auf die Sie Ihre App ausrichten möchten, sind möglicherweise zusätzliche Konfigurationen erforderlich, z. B. Umleitungs-URIs, bestimmte Authentifizierungseinstellungen oder plattformspezifische Details.

Hinweis

Wenn Ihrer Registerkarten-App keine Zustimmung des IT-Administrators erteilt wurde, müssen App-Benutzer ihre Einwilligung erteilen, wenn sie Ihre App zum ersten Mal auf einer anderen Plattform verwenden.
Die implizite Genehmigung ist nicht erforderlich, wenn einmaliges Anmelden (Single Sign-On, SSO) für eine Registerkarten-App aktiviert ist.

Sie können die Authentifizierung für mehrere Plattformen konfigurieren, solange die URL eindeutig ist.

So konfigurieren Sie die Authentifizierung für eine Plattform

Öffnen Sie die App, die Sie im Azure-Portal registriert haben.
Wählen Sie im linken Bereich Verwalten>Authentifizierung aus.

Die Seite Plattformkonfigurationen wird angezeigt.
Wählen Sie Plattform hinzufügen + aus.

Die Seite Plattformen konfigurieren wird angezeigt.
Wählen Sie die Plattform aus, die Sie für Ihre Registerkarten-App konfigurieren möchten. Sie können den Plattformtyp aus der Web- oder Single-Page-Anwendung auswählen.

Sie können mehrere Plattformen für einen bestimmten Plattformtyp konfigurieren. Stellen Sie sicher, dass der Umleitungs-URI für jede von Ihnen konfigurierte Plattform eindeutig ist.

Die Seite "Web konfigurieren" wird angezeigt.

Hinweis

Die Konfigurationen unterscheiden sich je nach ausgewählter Plattform.
Geben Sie die Konfigurationsdetails für die Plattform ein.
1. Geben Sie den Umleitungs-URI ein. Der URI sollte eindeutig sein.
2. Geben Sie die URL für Front-Channel-Abmeldung ein.
3. Wählen Sie die Token aus, die Die Microsoft Entra-ID für Ihre App senden soll.
Wählen Sie Konfigurieren aus.

Die Plattform wird konfiguriert und auf der Seite Plattformkonfigurationen angezeigt.

Abrufen des Zugriffstokens für MS Graph

Sie müssen ein Zugriffstoken für Microsoft Graph abrufen. Dazu können Sie den Microsoft Entra-On-Behalf-of-Flow (OBO) verwenden.

Die aktuelle Implementierung für einmaliges Anmelden (Single Sign-On, SSO) ist auf Berechtigungen auf Benutzerebene beschränkt, die für Graph-Aufrufe nicht verwendet werden können. Um die Berechtigungen und Bereiche zu erhalten, die für einen Graph-Aufruf erforderlich sind, müssen SSO-Apps einen benutzerdefinierten Webdienst implementieren, um das von der Teams JavaScript-Bibliothek empfangene Token gegen ein Token auszutauschen, das die erforderlichen Bereiche enthält. Sie können die Microsoft-Authentifizierungsbibliothek (MSAL) verwenden, um das Token von der Clientseite abzurufen.

Nachdem Sie Graph-Berechtigungen in Microsoft Entra ID konfiguriert haben, müssen Sie die Token-ID vom Teams-Client abrufen und dann mit dem serverseitigen Token austauschen.

Abrufen der Token-ID vom Teams-Client

Im Folgenden finden Sie ein Beispiel für das Abrufen der Token-ID vom Teams-Client:

microsoftTeams.authentication.getAuthToken().then((result) => {
    //result contains the id token
            console.log(result);
        })

Austauschen der Token-ID mit dem serverseitigen Token

Im Folgenden finden Sie ein Beispiel für den OBO-Fluss zum Abrufen des Zugriffstokens vom Teams-Client mithilfe von MSAL:

C#
Node.js

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(<"Client id">)
                                                .WithClientSecret(<"Client secret">)
                                                .WithAuthority($"https://login.microsoftonline.com/<"Tenant id">")
                                                .Build();
            try
            {
                var idToken = <"Client side token">;
                UserAssertion assert = new UserAssertion(idToken);
                List<string> scopes = new List<string>();
                scopes.Add("https://graph.microsoft.com/User.Read");
                // Acquires an access token for this application (usually a Web API) from the authority configured in the application.
                var responseToken = await app.AcquireTokenOnBehalfOf(scopes, assert).ExecuteAsync();
                return responseToken.AccessToken.ToString();
            }
            catch (Exception ex)
            {
                return ex.Message;
            }
        }

ConfidentiaClientApplication-Klasse SDK-Referenz | Beispielcode

// Exchange client Id side token with server token
  app.post('/getProfileOnBehalfOf', function(req, res) {
        var tid = < "Tenant id" >
    var token = < "Client side token" >
    var scopes = ["https://graph.microsoft.com/User.Read"];

        // Creating MSAL client
        const msalClient = new msal.ConfidentialClientApplication({
            auth: {
                clientId: < "Client ID" >,
                clientSecret: < "Client Secret" >
      }
        });

        var oboPromise = new Promise((resolve, reject) => {
            msalClient.acquireTokenOnBehalfOf({
                authority: `https://login.microsoftonline.com/${tid}`,
                oboAssertion: token,
                scopes: scopes,
                skipCache: true
            }).then(result => {
                console.log("Token is: " + result.accessToken);
            }).catch(error => {
                reject({ "error": error.errorCode });
            });
        });

Wenn Sie auf Microsoft Graph-Daten zugreifen müssen, konfigurieren Sie Ihren serverseitigen Code wie folgt:

Überprüfen des Zugriffstokens. Weitere Informationen finden Sie unter Überprüfen des Zugriffstokens.
Initiieren Sie den OAuth 2.0 OBO-Fluss mit einem Aufruf an die Microsoft-Identitätsplattform, der das Zugriffstoken, einige Metadaten über den Benutzer und die Anmeldedaten der Registerkarten-App (ihre App-ID und ihren geheimen Clientschlüssel) enthält. Microsoft Identity Platform gibt ein neues Zugriffstoken zurück, das für den Zugriff auf Microsoft Graph verwendet werden kann.
Rufen Sie Daten aus Microsoft Graph unter Verwendung des neuen Tokens ab.
Verwenden Sie die Tokencacheserialisierung in MSAL.NET, um das neue Zugriffstoken bei Bedarf für mehrere zwischenzuspeichern.

Wichtig

Als bewährte Methode für die Sicherheit sollten Sie immer serverseitigen Code verwenden, um Microsoft Graph-Aufrufe oder andere Aufrufe zu tätigen, die die Übergabe eines Zugriffstokens erfordern. Dadurch wird verhindert, dass der Token abgefangen oder weitergegeben werden kann. Geben Sie das OBO-Token NICHT an den Client zurück, da es dem Client dann ermöglichen würde, direkte Aufrufe an Microsoft Graph zu tätigen.
Zwei separate Apps, die in Microsoft Entra ID registriert sind, erfordern individuelle Token für jede App. Verwenden Sie den OBO-Fluss , um die Kommunikation zwischen den Apps zu ermöglichen.
Verwenden notifySuccess Sie result nicht, um die Tokeninformationen an die übergeordnete Seite zurückzugeben. Verwenden Sie localStorage , um das Token zu speichern und den Elementschlüssel über notifySuccesszu übergeben.

Ihre App kann die Zustimmung für Graph-Berechtigungen global vom Mandantenadministrator oder einzeln pro Benutzer einholen.

Vom Mandantenadministrator

Eine einfache Möglichkeit der Zustimmung im Namen einer Organisation besteht darin, die Administratoreinwilligung einzuholen.

Vom Benutzer

Wenn Sie eine zusätzliche Benutzerzustimmung mithilfe der Microsoft TeamsJS-Authentifizierungsfunktion (JavaScript-Clientbibliothek) anfordern, beachten Sie die folgenden Überlegungen:

Führen Sie die folgenden Schritte aus, um die SSO-Authentifizierung auf einer persönlichen Registerkarte zu implementieren:

Das mit getAuthToken() abgerufene Token muss serverseitig mithilfe des Microsoft Entra OBO-Flusses ausgetauscht werden, um Zugriff auf diese anderen Graph-APIs zu erhalten. Stellen Sie sicher, dass Sie den Microsoft Entra v2-Endpunkt für diesen Austausch verwenden.
Wenn Sie versuchen, den Tokenaustausch für einen Benutzer zum ersten Mal auszuführen, kann es sein, dass Microsoft Entra den Austausch von Token ablehnt, weil der Benutzer nicht zugestimmt hat, Ihrer App die Berechtigung für die Daten des Benutzers zu erteilen. In diesen Fällen schlägt Ihr Austausch entweder mit dem invalid_grant Fehler oder interaction_required fehl. Beispiele für invalid_grant Fehler sind, wenn die Zustimmung erforderlich ist oder auth_code, Assertion oder das Aktualisierungstoken abgelaufen ist, widerrufen, falsch formatiert oder nicht vorhanden ist. Beispiele für interaction_required umfassen, wenn die mehrstufige Authentifizierung oder die Registrierung von Unternehmensgeräten erforderlich ist.
Wenn der Austausch aufgrund des Fehlers invalid_grant oder interaction_required fehlschlägt, müssen Sie den Benutzer zur Zustimmung auffordern. Da eine Benutzerinteraktion nur vom Client aus erfolgen kann, muss Ihr Server ihrer Client-App einen Hinweis zurückgeben, dass eine Zustimmung erforderlich ist. Anschließend können Sie die Benutzeroberfläche (UI) verwenden, um den App-Benutzer aufzufordern, eine andere Zustimmung zu erteilen. Die Benutzeroberfläche muss eine Schaltfläche enthalten, die ein Microsoft Entra-Zustimmungsdialogfeld auslöst.
Um den Benutzer um Zustimmung für den Zugriff ihrer App auf seine Daten zu bitten, müssen Sie die prompt=consent -Eigenschaft in Ihren Abfragezeichenfolgenparameter in Microsoft Entra ID einschließen.
- Verwenden Sie ?prompt=consent&scope={scopes} anstelle von ?scope={scopes}
- Stellen Sie sicher, dass die {scopes} -Eigenschaft alle Bereiche enthält, für die Sie den Benutzer auffordern. Zum Beispiel Mail.Read oder User.Read.
Informationen zum Verarbeiten der inkrementellen Zustimmung für tab-Apps finden Sie unter Inkrementelle und dynamische Benutzerzustimmung.
Nachdem der App-Benutzer weitere Berechtigungen erteilt hat, wiederholen Sie den OBO-Fluss, um Zugriff auf zusätzliche Graph-APIs zu erhalten. Weitere Informationen finden Sie unter Beispielcode für die SSO-Authentifizierung mit der persönlichen Registerkarte von Teams .

Racebedingung beim Ausführen eines OBO-Aufrufs nach einer Ungültigen Genehmigungsausnahme

Wenn ein Benutzer die Microsoft Entra-Anwendungseinwilligung für diese Bereiche nicht erteilt hat, schlägt Ihr OBO-Aufruf mit invalid_grant oder interaction_required fehler fehl. Dieser Fehler informiert Sie darüber, dass Sie den Benutzer zur Zustimmung auffordern müssen.

Wenn der Benutzer seine Zustimmung gegeben hat und Sie versuchen, sofort einen OBO-Aufruf zu tätigen, gibt es manchmal eine Racebedingung zwischen der Weitergabe dieser Zustimmung durch Microsoft Entra ID und der OBO-Anforderung, die ausgeführt wird. Dies kann dazu führen, dass der OBO-Aufruf mit demselben invalid_grant Fehler oder interaction_required fehlschlägt.

Wenn Ihre Anwendung dieses Verhalten nicht kennen, fordert sie den Benutzer möglicherweise mehrmals um seine Zustimmung. Die bewährte Methode besteht darin, einen sinnvollen Warte- und Wiederholungsmechanismus zu erstellen, um diese suboptimale Benutzererfahrung zu vermeiden.

Der Warte- und Wiederholungsmechanismus muss nachverfolgt werden, wenn ein Benutzer den erforderlichen Bereichen zugestimmt hat. Wenn ein API-Aufruf, der eine OBO-Anforderung enthält, mit den oben genannten Fehlern fehlschlägt, der Benutzer aber bereits zugestimmt hat, vermeiden Sie es, dem Benutzer die Zustimmungsaufforderung anzuzeigen. Warten Sie stattdessen einige Zeit, bevor Sie den API-Aufruf wiederholen. In der Regel sendet Microsoft Entra ID die Zustimmung innerhalb von drei bis fünf Sekunden. In einer unserer Beispielanwendungen versuchen wir es bis zu dreimal mit doppelter Wartezeit zwischen den einzelnen Wiederholungsversuchen, beginnend mit einer Wartezeit von einer Sekunde.

Wenn der OBO-Fluss nach drei bis fünf Versuchen weiterhin fehlschlägt, hat der Benutzer möglicherweise nicht allen erforderlichen Bereichen zugestimmt, und Sie müssen den Benutzer möglicherweise erneut zur Zustimmung auffordern.

Dieser Ansatz trägt dazu bei, die Wahrscheinlichkeit zu verringern, dass Benutzer mehrmals zur Zustimmung aufgefordert werden.

Codebeispiel

Beispielname	Beschreibung	C#	Node.js
Registerkarten Microsoft Entra SSO	Microsoft Teams-Beispiel-App für Registerkarten Microsoft Entra SSO, die den OBO-Fluss zum Aufrufen von Graph-APIs verwendet.	View	Anzeigen

Freigeben über

Erweitern der Registerkarten-App mit Microsoft Graph-Berechtigungen und -Bereichen

Konfigurieren von API-Berechtigungen in Microsoft Entra ID

So konfigurieren Sie API-Berechtigungen

Konfigurieren der Authentifizierung für verschiedene Plattformen

So konfigurieren Sie die Authentifizierung für eine Plattform

Abrufen des Zugriffstokens für MS Graph

Abrufen der Token-ID vom Teams-Client

Austauschen der Token-ID mit dem serverseitigen Token

Vom Mandantenadministrator

Vom Benutzer

Racebedingung beim Ausführen eines OBO-Aufrufs nach einer Ungültigen Genehmigungsausnahme

Codebeispiel

Siehe auch

Zusätzliche Ressourcen

Freigeben über

Erweitern der Registerkarten-App mit Microsoft Graph-Berechtigungen und -Bereichen

Konfigurieren von API-Berechtigungen in Microsoft Entra ID

So konfigurieren Sie API-Berechtigungen

Konfigurieren der Authentifizierung für verschiedene Plattformen

So konfigurieren Sie die Authentifizierung für eine Plattform

Abrufen des Zugriffstokens für MS Graph

Abrufen der Token-ID vom Teams-Client

Austauschen der Token-ID mit dem serverseitigen Token

Zustimmung einholen

Vom Mandantenadministrator

Vom Benutzer

Racebedingung beim Ausführen eines OBO-Aufrufs nach einer Ungültigen Genehmigungsausnahme

Codebeispiel

Siehe auch

Zusätzliche Ressourcen