Geschachtelte App-Authentifizierung

Hinweis

Die geschachtelte App-Authentifizierung (NAA) wird nur in SPAs (Single-Page-Anwendungen) unterstützt, z. B. Registerkarten.

NAA ist ein neues Authentifizierungsprotokoll für SPAs, die in Hostumgebungen wie Teams, Outlook und Microsoft 365 eingebettet sind. Es vereinfacht den Authentifizierungsprozess, um das einmalige Anmelden (Single Sign-On, SSO) für Apps zu erleichtern, 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 auf Registerkarten in Teams, persönlichen Apps und Office-Add-Ins.

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

NAA erfordert, dass Sie nur die MSAL.js Bibliothek verwenden. Sie müssen die Funktion in der getAuthToken JavaScript-Clientbibliothek von Teams (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 vorautorisieren, 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 Teams Entra SSO	NAA
Umleitungs-URI verfügbar machen	Erforderlich	Erforderlich
API in Microsoft Entra ID registrieren	Erforderlich
Definieren eines benutzerdefinierten Bereichs in Microsoft Entra ID	Erforderlich
Autorisieren von Teams-Client-Apps	Erforderlich
App-Manifest überarbeiten (zuvor als Teams-App-Manifest bezeichnet)	Erforderlich	Empfohlen*
Beziehen von Zugriffstoken über TeamsJS SDK	Erforderlich
Einholen der Benutzereinwilligung für weitere Berechtigungen	Erforderlich
OBO-Austausch auf dem Server durchführen	Erforderlich

Der IT-Administrator blockiert möglicherweise die App oder stimmt nur bestimmten Berechtigungen für die App in Microsoft Entra ID zu. Um dies zu vermeiden, müssen Sie die App-ID und die Standardressource im App-Manifest angeben, damit der Administrator die Berechtigungen im Teams Admin Center genehmigen kann.

Anwendungsfälle für NAA

Szenario	Beschreibung
Zustimmen 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 wird Tom in einem Dialogfeld aufgefordert, Berechtigungen zu erteilen, einschließlich des Lesens des Profils für den Avatar (User.Read). Nach seiner Zustimmung kann Tom Contoso nahtlos in zukünftigen Besprechungen geräteübergreifend verwenden.
Erneute Authentifizierung oder erweiterte Authentifizierung für bedingten Zugriff	Wenn Tom von Australien aus arbeitet, stößt er auf einen Trigger für bedingten Zugriff, der eine mehrstufige Authentifizierung (MFA) erfordert, um auf Contoso in Teams zuzugreifen. Ein Dialogfeld informiert Tom, dass eine weitere Überprüfung erforderlich ist, und führt ihn durch den MFA-Prozess, um Contoso weiterhin zu verwenden.
Fehler	Tom sieht sich mit einem Anmeldefehler bei Contoso konfrontiert, der auf ein Problem beim Abrufen von Kontoinformationen zurückzuführen ist. Tom stößt auf eine Schaltfläche zum Wiederholen, die zur erneuten Authentifizierung auffordert. Sie stellen jedoch fest, dass der Systemadministrator eingeschränkten Zugriff auf Contoso hat.

Konfigurieren von NAA

Gehen Sie folgendermaßen vor, um die geschachtelte Authentifizierung zu konfigurieren:

Registrieren Sie Ihre SPA
Vertrauenswürdige Broker hinzufügen
Öffentliche Client-App initialisieren
Erwerben Sie Ihr erstes Token
Aufrufen einer API

Registrieren Sie Ihre 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 das Azure-Portal eine Microsoft Entra-App-Registrierungs-ID. Wenn Ihr Add-In über NAA und SSO hinaus zusätzliche App-Registrierung erfordert, lesen Sie Registrieren Ihrer Single-Page-Anwendung.

Vertrauenswürdige Broker hinzufügen

Um die Authentifizierung geschachtelter Apps zu konfigurieren, muss Ihre App aktiv einen Umleitungs-URI für Ihre App konfigurieren. Der Umleitungs-URI gibt der 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 die Vermittlung Ihrer Authentifizierung durch alle von Microsoft 365 unterstützten Hosts, für deren Ausführung sie konfiguriert ist, z. B. Teams, Outlook oder Microsoft365.com.
< > 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 Teilpfade 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 in Microsoft 365.

Öffentliche Client-App initialisieren

Hinweis

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

Initialisieren Sie MSAL, und rufen Sie eine instance der öffentlichen Client-App ab, um bei Bedarf 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;
    }
  );
}

Erwerben Sie Ihr erstes Token

Die Token, die von MSAL.js durch die geschachtelte App-Authentifizierung erworben werden, werden für Ihre Microsoft Entra-App-Registrierungs-ID ausgestellt. MSAL.js übernimmt die Erfassung von Token für die Benutzerauthentifizierung. Es wird im Hintergrund versucht, 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 durch Microsoft Entra ID geschützte Ressourcen aufzurufen. Im Gegensatz zum OBO-Flow müssen Sie Ihre Hosts nicht vorautorisieren, um die Endpunkte aufzurufen.

Gehen Sie folgendermaßen vor, um ein Token zu beziehen:

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

Hinweis

Die homeAccountId Eigenschaft entspricht userObjectId in TeamsJS.
Aufruf publicClientApplication.acquireTokenSilent(accessTokenRequest) zum automatischen Abrufen des Tokens ohne Benutzerinteraktion. accessTokenRequest Gibt die Bereiche an, für die das Zugriffstoken angefordert wird. Die NAA unterstützt die inkrementelle und dynamische Zustimmung. Stelle sicher, dass du immer die Mindestbereiche anforderst, die dein Code zum Erfüllen seiner Aufgabe benötigt.

Wenn kein Konto verfügbar ist, gibt MSAL.js einen zurück InteractionRequiredAuthError. Aufruf publicClientApplication.acquireTokenPopup(accessTokenRequest) , um einen interaktiven Dialog 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 stellen.

Das folgende Beispiel zeigt, wie Sie eine authentifizierte Anforderung an die 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
    });

Tokenvorabruf für die Authentifizierung geschachtelter Apps (NAA)

Um die Leistung zu verbessern und die Authentifizierungslatenz zu verringern, unterstützt die geschachtelte App-Authentifizierung (Nested App Authentication, NAA) Token-Prefetching. Mit diesem Feature kann der Host proaktiv Authentifizierungstoken abrufen, bevor die App gestartet wird, was einen schnelleren Zugriff auf geschützte Ressourcen ermöglicht.

So aktivieren Sie Token-Prefetching

Um Token-Prefetching zu aktivieren, aktualisieren Sie Ihr Teams-App-Manifest auf Version 1.22 oder höher, und schließen Sie den nestedAppAuthInfo Abschnitt darin webApplicationInfoein.

{
 "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

Geben Sie für jede NAA-Token-Prefetch-Anforderung die Microsoft Entra ID-Registrierungsclient-ID des Agenten oder der App in das optionale clientId Feld des entsprechenden nestedAppAuthInfo Eintrags ein. Wenn angegeben, wird dieser Wert verwendet, um das Token für diesen Eintrag vorab abzurufen. Wenn ein Eintrag nicht enthält clientId, verwendet webApplicationInfo.id der Host als Client-ID für die NAA-Token-Prefetch-Anforderung dieses Eintrags.
webApplicationInfo.id ist die Fallbackclient-ID für Einträge, die clientId nicht angeben. Sie muss nicht mit jeder clientId der Einstiegsebene übereinstimmen. Wenn eine App nur webApplicationInfo.id für den NAA-Token-Prefetch verwendet wird, muss dieser Wert mit der Client-ID der Microsoft Entra ID Registrierung der App übereinstimmen, die für die tatsächlichen NAA-Tokenanforderungen verwendet wird.
Die Werte in webApplicationInfo.id und alle Felder darin nestedAppAuthInfo müssen genau mit den Parametern übereinstimmen, die in der NAA-Tokenanforderung der App zur Laufzeit verwendet werden. Alle Konflikte, z. B. Unterschiede in Bereichen, Umleitungs-URIs oder Ansprüchen, verhindern, dass der Host das Token aus dem Cache bereitstellt.
Vorab abgerufene Token werden für kurze Zeit im Arbeitsspeicher gespeichert und sind nur für die Verwendung während des ersten 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 Standardauthentifizierungsabläufen initiieren.

So funktioniert es

Wenn der Tokenvorabruf 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 Prefetch-Funktion im älteren Teams-SSO-Modell, bei dem die API automatisch während des Ladens der getAuthToken Registerkarte ausgelöst wurde. Bei der Nested App Authentication (NAA) wird diese Funktionalität über die Manifestkonfiguration eingeführt, wodurch die Leistung verbessert wird, ohne dass ein Back-End-Tokenaustausch erforderlich ist.

Vorteile von Token Prefetching in NAA

Verbessern Sie die Leistung, indem Sie die Authentifizierungsverzögerungen beim Starten der App verringern.
Einmaliges Anmelden (Single Sign-On, SSO) für geschachtelte Apps ohne wiederholte Anmeldung aktivieren

Hinweis

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

Bewährte Methoden

Verwenden Sie nach Möglichkeit die automatische Authentifizierung: MSAL.js stellt die Methode bereit, die die acquireTokenSilent Tokenerneuerung verarbeitet, indem stille Tokenanforderungen gestellt werden, ohne den Benutzer aufzufordern. Die Methode sucht zunächst nach einem gültigen zwischengespeicherten Token im Browserspeicher. Wenn keine gefunden wird, sendet die Bibliothek eine unbeaufsichtigte Anforderung an Microsoft Entra ID, und wenn eine aktive Benutzersitzung vorhanden ist (bestimmt durch ein Cookie, das im Browser auf der Microsoft Entra-Domäne festgelegt wird), gibt Microsoft Entra ID ein neues Token zurück. Die Bibliothek ruft die acquireTokenSilent Methode nicht automatisch auf. Es wird empfohlen, Ihre App aufzurufen acquireTokenSilent , bevor Sie einen API-Aufruf durchfü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 Benutzersitzung mit Microsoft Entra ID abgelaufen ist oder eine Kennwortänderung durch den App-Benutzer, acquireTokenSilent schlägt fehl. Rufen Sie die interaktive Methode zum Erfassen von Token (acquireTokenPopup) auf.
Haben Sie einen Fallback: Die NAA-Flows bieten Kompatibilität für das gesamte Microsoft-Ökosystem. Ihre App kann jedoch in älteren oder älteren Clients angezeigt werden, die nicht aktualisiert werden, um NAA zu unterstützen. In solchen Fällen kann Ihre App kein nahtloses SSO unterstützen, und Sie müssen möglicherweise spezielle APIs für die Interaktion mit dem Benutzer aufrufen, um Authentifizierungsdialoge zu öffnen. Weitere Informationen finden Sie unter Aktivieren von SSO für die Registerkarten-App.

Hinweis

Sie dürfen NAA nicht verwenden, wenn Sie einen Identitätsanbieter verwenden, der nicht von Microsoft Entra stammt. Sie können stattdessen 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 seinen Status zu ermitteln. Ein Rückgabewert von true gibt die Unterstützung für NAA an, schlägt jedoch false vor, dass sie nicht unterstützt wird.
Testen Sie Ihre App in mehreren Umgebungen: Wenn Ihre App voraussichtlich sowohl in der Webansichts- als auch in der Browserbereitstellung 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
Geschachtelte App-Authentifizierung	Dieses Beispiel zeigt Microsoft Entra Single Sign-On (SSO) auf einer Microsoft Teams-Registerkarte unter Verwendung des OBO-Flusses (On-Behalf-Of) zum Aufrufen der Microsoft Graph-API im Namen des Benutzers.	View	Anzeigen

Siehe auch

Feedback

War diese Seite hilfreich?

Last updated on 2026-09-30

Geschachtelte App-Authentifizierung

Anwendungsfälle für NAA

Konfigurieren von NAA

Registrieren Sie Ihre SPA

Vertrauenswürdige Broker hinzufügen

Öffentliche Client-App initialisieren

Erwerben Sie Ihr erstes Token

Aufrufen einer API

Tokenvorabruf für die Authentifizierung geschachtelter Apps (NAA)

So aktivieren Sie Token-Prefetching

So funktioniert es

Vorteile von Token Prefetching in NAA

Bewährte Methoden

Codebeispiel

Siehe auch

Feedback

Zusätzliche Ressourcen