Registerkarten-App mit Microsoft Graph-Berechtigungen und -Bereichen erweitern

Sie können Ihre Registerkarten-App mithilfe von Microsoft Graph erweitern, um zusätzliche Benutzerberechtigungen zu ermöglichen, z. B. zum Anzeigen des App-Benutzerprofils, zum Lesen von E-Mails und mehr. Ihre App muss nach Zustimmung des App-Benutzers bestimmte Berechtigungsbereiche anfordern, um die Zugriffstoken zu erhalten.

Diagrammbereiche wie User.Read oder Mail.Readgeben an, worauf Ihre App über ein Teams-Benutzerkonto zugreifen kann. Sie müssen Ihre Bereiche in der Autorisierungsanforderung angeben. In diesem Artikel werden Sie durch die Schritte zum Konfigurieren von Microsoft Graph-Berechtigungen und -Bereichen für Ihre Teams-Registerkarten-App geführt.

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 Nur-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

1. Öffnen Sie die App, die Sie im Azure-Portal registriert haben.

2. Wählen Sie im linken BereichAPI-Berechtigungenverwalten> aus.

   

   Die Seite API-Berechtigungen wird angezeigt.

3. Wählen Sie "+ Berechtigung hinzufügen" aus, um Microsoft Graph-API-Berechtigungen hinzuzufügen.

   

   Die Seite API-Berechtigungen anfordern wird angezeigt.

4. Wählen Sie Microsoft Graph aus.

   

   Die Optionen für Graph-Berechtigungen werden angezeigt.

5. Wählen Sie Delegierte Berechtigungen oder Anwendungsberechtigungen aus, um die Liste der delegierten Berechtigungen bzw. Anwendungsberechtigungen anzuzeigen.

   

6. 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

Je nach Plattform oder Gerät, auf das Sie Ihre App richten möchten, kann eine zusätzliche Konfiguration erforderlich sein, z. B. Umleitungs-URIs, bestimmte Authentifizierungseinstellungen oder plattformspezifische Details.

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

So konfigurieren Sie die Authentifizierung für eine Plattform

1. Öffnen Sie die App, die Sie im Azure-Portal registriert haben.

2. Wählen Sie im linken Bereich Verwalten>Authentifizierung aus.

   

   Die Seite Plattformkonfigurationen wird angezeigt.

3. Wählen Sie Plattform hinzufügen + aus.

   

   Die Seite Plattformen konfigurieren wird angezeigt.

4. Wählen Sie die Plattform aus, die Sie für Ihre Registerkarten-App konfigurieren möchten. Sie können den Plattformtyp aus 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.

5. 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 Microsoft Entra ID für Ihre App senden soll.

6. 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 erwerben. Dazu können Sie den Microsoft Entra On-Behalf-of(OBO)-Flow verwenden.

Die aktuelle Implementierung für einmaliges Anmelden (Single Sign-On, SSO) ist auf Berechtigungen auf Benutzerebene beschränkt, die nicht für Graph-Aufrufe 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);
        })

Tauschen Sie die Token-ID mit dem serverseitigen Token aus.

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

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;
            }
        }

// 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:

1. Überprüfen des Zugriffstokens. Weitere Informationen finden Sie unter Überprüfen des Zugriffstokens.
2. 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.
3. Rufen Sie Daten aus Microsoft Graph unter Verwendung des neuen Tokens ab.
4. Verwenden Sie die Tokencacheserialisierung in MSAL.NET, um das neue Zugriffstoken bei Bedarf für mehrere zwischenzuspeichern.

Einwilligung einholen

Sie können die App-Zustimmung für Graph-Berechtigungen global vom Administrator oder individuell pro Benutzer erhalten.

Vom Administrator

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

Vom Benutzer

Wenn Sie mithilfe der Authentifizierungsfunktion Microsoft Teams JavaScript Client Library (TeamsJS) eine zusätzliche Benutzereinwilligung anfordern, beachten Sie die folgenden Überlegungen:

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

1. Das mitgerufene getAuthToken() Token muss serverseitig über den Microsoft Entra OBO-Fluss 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.

2. Wenn Sie zum ersten Mal versuchen, den Tokenaustausch für einen Benutzer auszuführen, wenn Microsoft Entra den Austausch von Token verweigert, kann dies daran liegen, dass der Benutzer nicht zugestimmt hat, Ihrer App die Berechtigung für die Daten des Benutzers zu erteilen. In diesen Fällen schlägt Ihr Exchange mit dem invalid_grant ODER-Fehler interaction_required fehl. Beispiele für invalid_grant Fehler sind, wenn die Zustimmung erforderlich ist oder auth_code, eine Assertion oder das Aktualisierungstoken abgelaufen, widerrufen, falsch formatiert oder nicht vorhanden ist. Beispiele für interaction_required sind, wenn eine mehrstufige Authentifizierung oder die Registrierung von Unternehmensgeräten erforderlich ist.

3. Wenn der Austausch aufgrund des Fehlers invalid_grant oder interaction_required fehlschlägt, müssen Sie den Benutzer zur Zustimmung auffordern. Da Benutzerinteraktion nur vom Client aus erfolgen kann, muss der Server einen Hinweis an Ihre Client-App zurückgeben, dass die Zustimmung erforderlich ist. Sie können dann über die Benutzeroberfläche (UI) den App-Benutzer um eine weitere Zustimmung bitten. Die Benutzeroberfläche muss eine Schaltfläche enthalten, die ein Microsoft Entra-Zustimmungsdialogfeld auslöst.

4. 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 query-string-parameter für Microsoft Entra ID einschließen.

   • Verwenden Sie ?prompt=consent&scope={scopes} anstelle von ?scope={scopes}
   • Stellen Sie sicher, dass die Eigenschaft alle Bereiche enthält, für die {scopes} Sie den Benutzer auffordern. Zum Beispiel Mail.Read oder User.Read.

   Informationen zum Behandeln der inkrementellen Zustimmung für die Registerkarten-App finden Sie unter Inkrementelle und dynamische Benutzereinwilligung.

5. Nachdem der App-Benutzer weitere Berechtigungen erteilt hat, versuchen Sie den OBO-Flow erneut, um Zugriff auf zusätzliche Graph-APIs zu erhalten. Weitere Informationen finden Sie unter Beispielcode für die SSO-Authentifizierung auf persönlichen Registerkarten von Teams .

Racebedingung beim Ausführen eines OBO-Aufrufs nach ungültiger Gewährungsausnahme

Wenn ein Benutzer der Microsoft Entra-Anwendung keine Zustimmung für diese Bereiche erteilt hat, schlägt Ihr OBO-Aufruf mit einem Fehler fehl invalid_grantinteraction_required. Dieser Fehler informiert Sie darüber, dass Sie den Benutzer um seine Zustimmung bitten müssen.

Wenn der Benutzer seine Zustimmung erteilt hat und Sie versuchen, sofort einen OBO-Anruf zu tätigen, gibt es manchmal eine Racebedingung zwischen der Weitergabe dieser Zustimmung durch Microsoft Entra ID und der stattfindenden OBO-Anfrage. Dies kann dazu führen, dass der OBO-Anruf mit denselben invalid_grantinteraction_required Fehlern fehlschlägt.

Wenn Ihre Anwendung dieses Verhalten nicht kennt, fordert sie den Benutzer möglicherweise mehrmals um Zustimmung an. Die bewährte Methode besteht darin, einen sinnvollen Mechanismus für Warte- und Wiederholungsversuche zu erstellen, um diese suboptimale Benutzererfahrung zu vermeiden.

Der Warte-und-Wiederholungs-Mechanismus muss nachverfolgen, ob 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. Normalerweise sendet Microsoft Entra ID die Zustimmung innerhalb von drei bis fünf Sekunden. In einer unserer Beispielanwendungen wiederholen wir bis zu drei Wiederholungsversuche mit doppelter Wartezeit zwischen jedem Wiederholungsversuch, beginnend mit einer Wartezeit von einer Sekunde.

Wenn der OBO-Flow nach drei bis fünf Versuchen immer noch fehlschlägt, hat der Benutzer möglicherweise nicht allen erforderlichen Bereichen zugestimmt, und Sie müssen ihn möglicherweise erneut auffordern, zuzustimmen.

Durch diesen Ansatz wird die Wahrscheinlichkeit verringert, dass Benutzer mehrmals zur Zustimmung aufgefordert werden.

Codebeispiel

Siehe auch

• OAuth 2.0 – On-Behalf-Of-Fluss.
• Zugriff für MS Graph erhalten
• Token-Cache-Serialisierung in MSAL.NET
• Microsoft Teams MSAL2-Anbieter