Authentifizierung geschachtelter Apps

Artikel
09/23/2024

Hinweis

Die Authentifizierung geschachtelter Apps (Nested App Authentication, NAA) ist nur in der öffentlichen Entwicklervorschau verfügbar.
NAA wird nur in Single-Page-Anwendungen (SPA) 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 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

Hinweis

Da sich NAA in der Entwicklervorschau befindet und nicht von allen Hostumgebungen unterstützt wird, sollten Sie die Unterstützung status mithilfe der isNAAChannelRecommended()-Funktion überprüfen und eine Fallbackerfahrung für nicht unterstützte Umgebungen bereitstellen.
Wenn die API den Wert als truezurückgibt, rufen Sie die Microsoft Authentication Library (MSAL) für den NAA-Fluss auf. Wenn zurückgegeben falsewird, verwenden Sie weiterhin Ihre vorhandene Tokenabrufmethode.

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.

JavaScript

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:

JavaScript


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

JavaScript


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

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 (die durch ein im Browser auf der Microsoft Entra Domäne festgelegtes Cookie bestimmt wird), 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 eine 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 gezeigt, wie Sie ein NAA-Protokoll für SPA erstellen, das in Hostumgebungen wie Teams, Outlook und Microsoft 365 eingebettet ist.	View	Anzeigen

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

Bewährte Methoden

Codebeispiel

Siehe auch

Zusätzliche Ressourcen