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

Artikel
08/01/2023

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 Azure AD

Sie können in Azure AD zusätzliche Graph-Bereiche 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.

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 aus, um die Liste der Berechtigungen 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 als Ziel verwenden 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 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 Azure AD 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 OBO-Fluss (On-Behalf-Of) von Azure AD 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 Azure AD 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. Die 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.
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 eines organization 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:

Tipp

Das SSO-Authentifizierungsbeispiel für die persönliche Registerkarte von Teams enthält Code, der die folgenden Schritte veranschaulicht.

Das mit getAuthToken() abgerufene Token muss serverseitig mithilfe des Azure AD-OBO-Flusses ausgetauscht werden, um Zugriff auf diese anderen Graph-APIs zu erhalten. Stellen Sie sicher, dass Sie den Azure AD 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 Azure AD den Tokenaustausch 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 Azure AD-Zustimmungsdialogfeld auslöst.
Um den Benutzer um zustimmung für ihre App für den Zugriff auf seine Daten zu bitten, müssen Sie die prompt=consent -Eigenschaft in Ihren Abfragezeichenfolgenparameter in Azure AD 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.

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

Wenn ein Benutzer keine Einwilligung der Azure AD-Anwendung für diese Bereiche 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 erteilt hat und Sie versuchen, sofort einen OBO-Aufruf zu tätigen, gibt es manchmal eine Racebedingung zwischen Azure AD, der diese Zustimmung weitergibt, und der OBO-Anforderung. 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.

Dieser Warte- und Wiederholungsmechanismus sollte 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 Azure AD 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 Für Azure AD SSO	Microsoft Teams-Beispiel-App für Registerkarten Azure AD SSO, die den OBO-Fluss verwendet, um Graph-APIs aufzurufen.	View	Anzeigen

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

Konfigurieren von API-Berechtigungen in Azure AD

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

Zusätzliche Ressourcen

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

Konfigurieren von API-Berechtigungen in Azure AD

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

Zusätzliche Ressourcen