Authentifizierung geschachtelter Apps

Hinweis

Die Authentifizierung geschachtelter Apps (Nested App Authentication, NAA) wird nur in Single-Page-Anwendungen (SPA) wie Registerkarten unterstützt.

NAA ist ein neues Authentifizierungsprotokoll für SPAs, die in Hostumgebungen wie Teams, Outlook und Microsoft 365 eingebettet sind. Es vereinfacht den Authentifizierungsprozess, um einmaliges Anmelden (Single Sign-On, SSO) für Apps zu ermöglichen, die in unterstützten Host-Apps geschachtelt sind. Das NAA-Modell unterstützt eine primäre Identität für die Host-App, die mehrere App-Identitäten für geschachtelte Apps enthält. Microsoft verwendet dieses Modell in Teams-Registerkarten, persönlichen Apps und Office-Add-Ins.

Das NAA-Modell bietet gegenüber dem OBO-Fluss (On-Behalf-Of) mehrere Vorteile:

NaA erfordert, dass Sie nur die MSAL.js-Bibliothek verwenden. Sie müssen die Funktion in der getAuthToken Teams JavaScript-Clientbibliothek (TeamsJS) nicht verwenden.
Sie können Dienste wie Microsoft Graph mit einem Zugriffstoken aus Ihrem Clientcode als SPA aufrufen. Ein Server der mittleren Ebene ist nicht erforderlich.
Sie können die inkrementelle und dynamische Zustimmung für Bereiche (Berechtigungen) verwenden.

Sie müssen Ihre Hosts wie Teams oder Microsoft 365 nicht vorab authentifizieren, um Ihre Endpunkte aufzurufen.

In der folgenden Tabelle wird der Unterschied zwischen Teams Microsoft Entra SSO und NAA beschrieben:

Für die Entwicklung erforderliche Schritte	Herkömmliches einmaliges Anmelden für Teams Entra	NAA
Verfügbarmachen des Umleitungs-URI	Erforderlich	Erforderlich
Registrieren der API in Microsoft Entra-ID	Erforderlich
Definieren eines benutzerdefinierten Bereichs in Microsoft Entra ID	Erforderlich
Autorisieren von Teams-Client-Apps	Erforderlich
Überarbeiten des App-Manifests (zuvor als Teams-App-Manifest bezeichnet)	Erforderlich	Empfohlen*
Abrufen des Zugriffstokens über das TeamsJS SDK	Erforderlich
Anfordern der Benutzer einwilligung für weitere Berechtigungen	Erforderlich
Durchführen eines OBO-Austauschs auf dem Server	Erforderlich

Der IT-Administrator kann die App blockieren oder nur bestimmten Berechtigungen für die App in Microsoft Entra ID zustimmen. Um dies zu vermeiden, müssen Sie die App-ID und die Standardressource in das App-Manifest einschließen, damit der Administrator die Berechtigungen im Teams Admin Center genehmigen kann.

Anwendungsfälle für NAA

Szenario	Beschreibung
Zustimmung zu SSO (und anderen Berechtigungen)	Tom, ein neues Mitglied des Contoso-Designteams, muss die Contoso-App in Teams-Besprechungen verwenden, um an Whiteboards zusammenzuarbeiten. Bei der ersten Verwendung fordert ein Dialogfeld Tom auf, Berechtigungen zu erteilen, einschließlich des Lesens seines Profils für seinen Avatar (User.Read). Nach der Zustimmung kann Tom Contoso in zukünftigen Besprechungen auf allen Geräten nahtlos verwenden.
Erneute Authentifizierung oder Authentifizierung für bedingten Zugriff	Tom trifft bei der Arbeit aus Australien auf einen Trigger für bedingten Zugriff, der die mehrstufige Authentifizierung (MFA) für den Zugriff auf Contoso in Teams erfordert. Ein Dialogfeld informiert Tom, dass eine weitere Überprüfung erforderlich ist, und führt sie durch den MFA-Prozess, um Contoso weiterhin zu verwenden.
Fehler	Tom tritt aufgrund eines Problems beim Abrufen von Kontoinformationen bei Contoso ein Anmeldefehler auf. Tom erkennt eine Wiederholungsschaltfläche, die zur erneuten Authentifizierung auffordert. Sie stellen jedoch fest, dass der Systemadministrator den Zugriff auf Contoso eingeschränkt hat.

Konfigurieren von NAA

Führen Sie die folgenden Schritte aus, um die geschachtelte Authentifizierung zu konfigurieren:

Registrieren Ihres SPA
Hinzufügen vertrauenswürdiger Broker
Initialisieren einer öffentlichen Client-App
Abrufen Ihres ersten Tokens
Aufrufen einer API

Registrieren Ihres SPA

Sie müssen eine Microsoft Entra-ID-App-Registrierung für Ihr Add-In auf Azure-Portal erstellen. Die App-Registrierung muss einen Namen, einen unterstützten Kontotyp und eine SPA-Umleitung aufweisen. Nach der Registrierung Ihrer App generiert Azure-Portal eine Microsoft Entra App-Registrierungs-ID. Wenn Ihr Add-In eine zusätzliche App-Registrierung erfordert, die über NAA und SSO hinausgeht, finden Sie weitere Informationen unter Registrieren Ihrer Single-Page-Anwendung.

Hinzufügen vertrauenswürdiger Broker

Um die Authentifizierung geschachtelter Apps zu konfigurieren, muss Ihre App aktiv einen Umleitungs-URI für Ihre App konfigurieren. Der Umleitungs-URI gibt dem Microsoft Identity Platform an, dass Ihre App von unterstützten Hosts vermittelt werden kann. Der Umleitungs-URI der App muss vom Typ Single-Page-Anwendung sein und dem folgenden Schema entsprechen:

brk-multihub://<your_domain>

Dabei gilt:

brk-multihub ermöglicht, dass Ihre Authentifizierung von allen von Microsoft 365 unterstützten Hosts vermittelt wird, die für die Ausführung in Microsoft Teams, Outlook oder Microsoft365.com konfiguriert sind.
< > your_domain ist der vollqualifizierte Domänenname, in dem Ihre App gehostet wird. Beispiel: brk-multihub://contoso.com.

Ihre Domäne darf nur den Ursprung und nicht seine Unterpfade enthalten. Zum Beispiel:

✔️ brk-multihub://myapp.teams.microsoft.com
❌ brk-multihub://myapp.teams.microsoft.com/go

Weitere Informationen zum Aktualisieren Ihrer Teams-App auf die Ausführung in Outlook und Microsoft365.com finden Sie unter Erweitern von Teams-Apps auf Microsoft 365.

Initialisieren einer öffentlichen Client-App

Hinweis

Um eine erfolgreiche Authentifizierung sicherzustellen, initialisieren Sie TeamsJS, bevor Sie MSAL initialisieren.

Initialisieren Sie MSAL, und rufen Sie bei Bedarf eine instance der öffentlichen Client-App ab, um Zugriffstoken abzurufen.

import {
  AccountInfo,
  IPublicClientApplication,
  createNestablePublicClientApplication,
} from "@azure/msal-browser";

const msalConfig = {
  auth: {
    clientId: "your_client_id",
    authority: "https://login.microsoftonline.com/{your_tenant_id}",
    supportsNestedAppAuth: true
  },
};

let pca: IPublicClientApplication;

export function initializePublicClient() {
  console.log("Starting initializePublicClient");
  return createNestablePublicClientApplication(msalConfig).then(
    (result) => {
      console.log("Client app created");
      pca = result;
      return pca;
    }
  );
}

Abrufen Ihres ersten Tokens

Die Token, die von MSAL.js über die geschachtelte App-Authentifizierung abgerufen werden, werden für Ihre Microsoft Entra App-Registrierungs-ID ausgestellt. MSAL.js übernimmt den Tokenabruf für die Benutzerauthentifizierung. Es wird versucht, im Hintergrund ein Zugriffstoken abzurufen. Wenn dies nicht erfolgreich ist, wird der Benutzer zur Zustimmung aufgefordert. Das Token wird dann verwendet, um die Microsoft Graph-API oder andere Microsoft Entra-ID-geschützte Ressourcen aufzurufen. Im Gegensatz zum OBO-Fluss müssen Sie Ihre Hosts nicht vorab authentifizieren, um die Endpunkte aufzurufen.

Führen Sie die folgenden Schritte aus, um ein Token abzurufen:

Verwenden Sie MSAL.js, um Token für Ihre App-ID abzurufen. Weitere Informationen finden Sie unter Abrufen und Verwenden eines Zugriffstokens.
Verwenden Sie getActiveAccount die API, um zu überprüfen, ob ein aktives Konto zum Aufrufen von publicClientApplicationvorhanden ist. Wenn kein aktives Konto vorhanden ist, versuchen Sie, mit zusätzlichen Filterparametern wie tenantID, homeAccountIdund loginHint aus der Kontextschnittstelle ein Konto aus dem Cache getAccountabzurufen.

Hinweis

Die homeAccountId -Eigenschaft entspricht userObjectId in TeamsJS.
Rufen Sie auf publicClientApplication.acquireTokenSilent(accessTokenRequest) , um das Token ohne Benutzerinteraktion automatisch abzurufen. accessTokenRequest gibt die Bereiche an, für die das Zugriffstoken angefordert wird. NAA unterstützt inkrementelle und dynamische Zustimmung. Stellen Sie sicher, dass Sie immer die Mindestbereiche anfordern, die für den Code erforderlich sind, um seine Aufgabe abzuschließen.

Wenn kein Konto verfügbar ist, gibt MSAL.js zurück InteractionRequiredAuthError. Rufen Sie publicClientApplication.acquireTokenPopup(accessTokenRequest) auf, um ein interaktives Dialogfeld für den Benutzer anzuzeigen. acquireTokenSilent kann fehlschlagen, wenn das Token abgelaufen ist oder der Benutzer nicht allen angeforderten Bereichen zugestimmt hat.

Der folgende Codeausschnitt zeigt ein Beispiel für den Zugriff auf ein Token:


  // MSAL.js exposes several account APIs, logic to determine which account to use is the responsibility of the developer
  const account = publicClientApplication.getActiveAccount();

  const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
  };

  publicClientApplication
    .acquireTokenSilent(accessTokenRequest)
    .then(function (accessTokenResponse) {
      // Acquire token silent success
      let accessToken = accessTokenResponse.accessToken;
      // Call your API with token
      callApi(accessToken);
    })
    .catch(function (error) {
      //Acquire token silent failure, and send an interactive request
      if (error instanceof InteractionRequiredAuthError) {
        publicClientApplication
          .acquireTokenPopup(accessTokenRequest)
          .then(function (accessTokenResponse) {
            // Acquire token interactive success
            let accessToken = accessTokenResponse.accessToken;
            // Call your API with token
            callApi(accessToken);
          })
          .catch(function (error) {
            // Acquire token interactive failure
            console.log(error);
          });
      }
      console.log(error);
    });

Aufrufen einer API

Nachdem Sie das Token erhalten haben, verwenden Sie es, um die API aufzurufen. Dadurch wird sichergestellt, dass die API mit einem gültigen Token aufgerufen wird, um authentifizierte Anforderungen an den Server zu senden.

Das folgende Beispiel zeigt, wie Sie eine authentifizierte Anforderung an Microsoft Graph-API für den Zugriff auf Microsoft 365-Daten senden:


var headers = new Headers();
var bearer = "Bearer " + access_token;
headers.append("Authorization", bearer);
var options = {
    method: "GET",
    headers: headers
};

var graphEndpoint = "<https://graph.microsoft.com/v1.0/me>";

fetch(graphEndpoint, options)
    .then(function (response) {
        //do something with response
    });

Tokenvorruf für die Authentifizierung geschachtelter Apps (NAA)

Um die Leistung zu verbessern und die Authentifizierungslatenz zu verringern, unterstützt die geschachtelte App-Authentifizierung (NAA) das Vorabrufen von Token. Mit diesem Feature kann der Host proaktiv Authentifizierungstoken abrufen, bevor die App gestartet wird, sodass schneller auf geschützte Ressourcen zugegriffen werden kann.

Aktivieren des Vorabrufs für Token

Um das Vorabrufen von Token zu aktivieren, aktualisieren Sie Ihr Teams-App-Manifest auf Version 1.22 oder höher, und fügen Sie den nestedAppAuthInfo Abschnitt in ein webApplicationInfo.

{
 "webApplicationInfo": {
   "id": "33333ddd-0000-0000-0000-88888757bbbb",
   "resource": "api://app.com/botid-33333ddd-0000-0000-0000-88888757bbbb",
   "nestedAppAuthInfo": [
     {
       "redirectUri": "brk-multihub://app.com",
       "scopes": ["openid", "profile", "offline_access"],
       "claims": "{\"access_token\":{\"xms_cc\":{\"values\":[\"CP1\"]}}}"
     }
   ]
 }
}

Wichtig

Der Wert von webApplicationInfo.id muss mit der Client-ID der Microsoft Entra ID-Registrierung der App übereinstimmen. Dies ist die gleiche Client-ID, die die App beim Ausführen tatsächlicher NAA-Tokenanforderungen verwendet. Der Host verwendet diese ID, um den Tokenvorrufprozess zu initiieren.
Die Werte in webApplicationInfo.id und alle Felder in nestedAppAuthInfo müssen genau mit den Parametern übereinstimmen, die in der NAA-Laufzeittokenanforderung der App verwendet werden. Jegliche Nichtübereinstimmung, z. B. Unterschiede in Bereichen, Umleitungs-URIs oder Ansprüchen, hindert den Host daran, das Token aus dem Cache zu verarbeiten.
Vorab abgerufene Token werden für kurze Zeit im Arbeitsspeicher gespeichert und sind nur für die Verwendung während des anfänglichen Ladens der App vorgesehen. Wenn die App später versucht, ein Token abzurufen, z. B. als Reaktion auf eine Benutzeraktion, ist das vorab abgerufene Token möglicherweise nicht mehr verfügbar. In solchen Fällen muss die App eine neue Tokenanforderung mithilfe von Standardauthentifizierungsflows initiieren.

So funktioniert es

Wenn token prefetching aktiviert ist, versucht die Hostumgebung, die erforderlichen Token abzurufen und zwischenzuspeichern, bevor die App gerendert wird. Diese Token werden im Arbeitsspeicher gespeichert und der App sofort nach dem Start zur Verfügung gestellt.

Dieses Verhalten ähnelt der Vorabruffunktion im älteren Teams-SSO-Modell, bei dem die API beim Laden der getAuthToken Registerkarte automatisch ausgelöst wurde. Mit der Authentifizierung geschachtelter Apps (Nested App Authentication, NAA) wird diese Funktionalität durch die Manifestkonfiguration eingeführt, wodurch die Leistung verbessert wird, ohne dass ein Back-End-Tokenaustausch erforderlich ist.

Vorteile des Tokenvorrufs in NAA

Verbessern der Leistung durch Reduzieren von Authentifizierungsverzögerungen während des App-Starts
Aktivieren des einmaligen Anmeldens (Single Sign-On, SSO) für geschachtelte Apps ohne wiederholte Anmeldungen

Hinweis

Das Vorabrufen von Token wird derzeit nur in den Microsoft Teams-Web- und Desktopclients unterstützt.

Bewährte Methoden

Verwenden Sie nach Möglichkeit die automatische Authentifizierung: MSAL.js stellt die acquireTokenSilent -Methode bereit, die die Tokenerneuerung verarbeitet, indem automatisch Tokenanforderungen ausgeführt werden, ohne den Benutzer dazu aufzufordern. Die -Methode sucht zunächst im Browserspeicher nach einem gültigen zwischengespeicherten Token. Wenn keines gefunden wird, sendet die Bibliothek eine automatische Anforderung an Microsoft Entra ID. Wenn eine aktive Benutzersitzung vorhanden ist (bestimmt durch ein Cookie im Browser in der Microsoft Entra Domäne), gibt Microsoft Entra ID ein neues Token zurück. Die -Bibliothek ruft die acquireTokenSilent -Methode nicht automatisch auf. Es wird empfohlen, dass Sie in Ihrer App aufrufen acquireTokenSilent , bevor Sie einen API-Aufruf ausführen, um ein gültiges Token abzurufen.

In bestimmten Fällen schlägt der Versuch, das Token mithilfe der acquireTokenSilent -Methode abzurufen, fehl. Wenn beispielsweise eine abgelaufene Benutzersitzung mit Microsoft Entra ID oder einer Kennwortänderung durch den App-Benutzer auftritt, acquireTokenSilent tritt ein Fehler auf. Rufen Sie die interaktive Methode zum Abrufen von Token auf (acquireTokenPopup).
Fallback: Die NAA-Flows bieten Kompatibilität im gesamten Microsoft-Ökosystem. Ihre App wird jedoch möglicherweise in down-level- oder Legacyclients angezeigt, die nicht aktualisiert wurden, um NAA zu unterstützen. In solchen Fällen kann Ihre App das nahtlose einmalige Anmelden nicht unterstützen, und Sie müssen möglicherweise spezielle APIs für die Interaktion mit dem Benutzer aufrufen, um Authentifizierungsdialogfelde zu öffnen. Weitere Informationen finden Sie unter Aktivieren des einmaligen Anmeldens für die Registerkarten-App.

Hinweis

Sie dürfen keine NAA verwenden, wenn Sie einen Nicht-Microsoft Entra Identitätsanbieter verwenden. Stattdessen können Sie die Popupauthentifizierung verwenden.
Unterstützung für NAA: NAA wird möglicherweise nicht in allen Host-App-Umgebungen unterstützt. Um zu überprüfen, ob der aktuelle Client dieses Feature unterstützt, können Sie die angegebene API aufrufen, um deren status zu bestimmen. Ein Rückgabewert von true gibt die Unterstützung für NAA an, während false dies nicht unterstützt wird.
Testen Sie Ihre App in mehreren Umgebungen: Wenn ihre App sowohl in der Webansicht als auch in Browserbereitstellungen funktioniert, empfehlen wir, Ihre App in beiden Bereitstellungsumgebungen zu testen, um sicherzustellen, dass sie sich wie erwartet verhält. Bestimmte APIs, die im Browser funktionieren, funktionieren möglicherweise nicht in Webansichten.

Codebeispiel

Beispielname	Beschreibung	.NET	Node.js
Authentifizierung geschachtelter Apps	In diesem Beispiel wird Microsoft Entra einmaliges Anmelden (Single Sign-On, SSO) auf einer Microsoft Teams-Registerkarte veranschaulicht, wobei der OBO-Flow (Im Auftrag von) verwendet wird, um Microsoft Graph-API im Namen des Benutzers aufzurufen.	View	Anzeigen

Siehe auch

Feedback

War diese Seite hilfreich?

Last updated on 2025-10-02

Freigeben über

Authentifizierung geschachtelter Apps

Anwendungsfälle für NAA

Konfigurieren von NAA

Registrieren Ihres SPA

Hinzufügen vertrauenswürdiger Broker

Initialisieren einer öffentlichen Client-App

Abrufen Ihres ersten Tokens

Aufrufen einer API

Tokenvorruf für die Authentifizierung geschachtelter Apps (NAA)

Aktivieren des Vorabrufs für Token

So funktioniert es

Vorteile des Tokenvorrufs in NAA

Bewährte Methoden

Codebeispiel

Siehe auch

Feedback

Zusätzliche Ressourcen