Aktivieren des einmaligen Anmeldens in einem Office-Add-In mit geschachtelter App-Authentifizierung

Sie können die MSAL.js-Bibliothek mit geschachtelter App-Authentifizierung verwenden, um SSO aus Ihrem Office-Add-In zu verwenden. Die Verwendung der geschachtelten App-Authentifizierung bietet mehrere Vorteile gegenüber dem On-Behalf-Of-Flow (OBO).

• Sie müssen nur die MSAL.js-Bibliothek verwenden und benötigen die getAccessToken Funktion nicht in Office.js.
• 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 verwenden.
• Sie müssen Ihre Hosts (z. B. Teams, Office) nicht vorab authentifizieren , um Ihre Endpunkte aufzurufen.

NAA-unterstützte Konten und Hosts

NAA unterstützt sowohl Microsoft-Konten als auch Microsoft Entra ID-Identitäten (Geschäfts-, Schul- oder Uniidentitäten). Azure Active Directory B2C für Business-to-Consumer-Identitätsverwaltungsszenarien wird nicht unterstützt. In der folgenden Tabelle wird die aktuelle Unterstützung nach Plattform erläutert. Plattformen, die als allgemein verfügbar (GA) aufgeführt sind, sind für die Produktionsnutzung in Ihrem Add-In bereit.

App	Web	Windows	Mac	iOS/iPad	Android
Excel	In der Vorschau	In der Vorschau	In der Vorschau	In der Vorschau auf dem iPad	Nicht zutreffend
Outlook	Allgemein verfügbar	GA im aktuellen Kanal, Vorschau in allen anderen Kanälen	Allgemein verfügbar	Allgemeine Verfügbarkeit (iOS)	Allgemein verfügbar
PowerPoint	In der Vorschau	In der Vorschau	In der Vorschau	In der Vorschau auf dem iPad	Nicht zutreffend
Word	In der Vorschau	In der Vorschau	In der Vorschau	In der Vorschau auf dem iPad	Nicht zutreffend

Wichtig

Um NAA auf Plattformen zu verwenden, die sich noch in der Vorschau befinden, treten Sie dem Microsoft 365 Insider-Programm (https://insider.microsoft365.com/join) bei, und wählen Sie Aktueller Kanal (Vorschau) aus. Verwenden Sie NAA nicht in Produktions-Add-Ins für Vorschauplattformen. Wir laden Sie ein, NAA in Test- oder Entwicklungsumgebungen auszuprobieren und Feedback zu Ihrer Erfahrung über GitHub zu begrüßen ( siehe Feedbackabschnitt am Ende dieser Seite).

Registrieren Ihrer Single-Page-Anwendung

Sie müssen eine Microsoft Azure-App-Registrierung für Ihr Add-In auf dem Azure-Portal erstellen. Die App-Registrierung muss mindestens folgendes aufweisen:

• Ein Name
• Ein unterstützter Kontotyp
• Eine SPA-Umleitung

Wenn Ihr Add-In eine zusätzliche App-Registrierung erfordert, die über NAA und SSO hinausgeht, finden Sie weitere Informationen unter Single-Page Application: App-Registrierung.

Hinzufügen eines vertrauenswürdigen Brokers über SPA-Umleitung

Um NAA zu aktivieren, muss Ihre App-Registrierung einen bestimmten Umleitungs-URI enthalten, um dem Microsoft Identity Platform mitzuteilen, dass ihr Add-In selbst von unterstützten Hosts vermittelt werden kann. Der Umleitungs-URI der Anwendung muss vom Typ Single Page Application sein und dem folgenden Schema entsprechen.

brk-multihub://your-add-in-domain

Wenn Sie beispielsweise Ihr Add-In an Port 3000 auf dem localhost-Server testen würden, würden Sie als Umleitungswert verwenden brk-multihub://localhost:3000 .

Vertrauenswürdige Brokergruppen sind beabsichtigt dynamisch und können in Zukunft aktualisiert werden, um zusätzliche Hosts einzuschließen, auf denen Ihr Add-In NAA-Flows verwenden kann. Derzeit umfasst die Gruppe brk-multihub Office Word, Excel, PowerPoint, Outlook und Teams (für den Zeitpunkt, in dem Office aktiviert ist).

Konfigurieren der MSAL-Konfiguration für die Verwendung von NAA

Konfigurieren Sie Ihr Add-In für die Verwendung von NAA, indem Sie die createNestablePublicClientApplication Funktion in MSAL aufrufen. MSAL gibt eine öffentliche Clientanwendung zurück, die in einem nativen Anwendungshost (z. B. Outlook) geschachtelt werden kann, um Token für Ihre Anwendung abzurufen.

Die folgenden Schritte zeigen, wie Sie NAA in der Datei oder taskpane.ts in einem Projekt aktivieren, das taskpane.js mit yo office (Office-Add-In-Aufgabenbereich-Projekt) erstellt wurde.

1. Fügen Sie das @azure/msal-browser Paket dem dependencies Abschnitt der package.json Datei für Ihr Projekt hinzu. Weitere Informationen zu diesem Paket finden Sie unter Microsoft Authentication Library for JavaScript (MSAL.js) for Browser-Based Single-Page Applications. Es wird empfohlen, die neueste Version des Pakets zu verwenden (zum Zeitpunkt des letzten Artikelupdates war es 3.26.0).

   "dependencies": {
       "@azure/msal-browser": "^3.26.0",
       ...
   

2. Speichern Sie , und führen Sie aus npm install , um zu installieren @azure/msal-browser.

3. Fügen Sie den folgenden Code am Anfang der Datei oder taskpane.ts hinzutaskpane.js. Dadurch wird die MSAL-Browserbibliothek importiert.

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

Initialisieren der öffentlichen Clientanwendung

Als Nächstes müssen Sie MSAL initialisieren und eine instance der öffentlichen Clientanwendung abrufen. Dies wird verwendet, um bei Bedarf Zugriffstoken abzurufen. Es wird empfohlen, den Code, der die öffentliche Clientanwendung erstellt, in die Office.onReady -Methode einzufügen.

• Fügen Sie in Ihrer Office.onReady Funktion wie unten gezeigt einen Aufruf von createNestablePublicClientApplication hinzu. Ersetzen Sie den Enter_the_Application_Id_Here Platzhalter durch die Zuvor gespeicherte Azure-App-ID.

  let pca = undefined;
  Office.onReady(async (info) => {
    if (info.host) {
      document.getElementById("sideload-msg").style.display = "none";
      document.getElementById("app-body").style.display = "flex";
      document.getElementById("run").onclick = run;
  
      // Initialize the public client application
      pca = await createNestablePublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
          authority: "https://login.microsoftonline.com/common"
        },
      });
    }
  });
  

Hinweis

Im vorherigen Codebeispiel wird die Autorität auf common festgelegt, was Geschäfts-, Schul- und Unikonten oder persönliche Microsoft-Konten unterstützt. Wenn Sie einen einzelnen Mandanten oder andere Kontotypen konfigurieren möchten, finden Sie weitere Autoritätsoptionen unter Optionen für die Anwendungskonfiguration .

Abrufen Ihres ersten Tokens

Die von MSAL.js über NAA erworbenen Token werden für Ihre Azure-App-Registrierungs-ID ausgestellt. In diesem Codebeispiel erhalten Sie ein Token für die Microsoft Graph-API. Wenn der Benutzer über eine aktive Sitzung mit Microsoft Entra ID wird das Token automatisch abgerufen. Andernfalls fordert die Bibliothek den Benutzer auf, sich interaktiv anzumelden. Das Token wird dann verwendet, um die Microsoft-Graph-API aufzurufen.

Die folgenden Schritte zeigen das Muster, das zum Abrufen eines Tokens verwendet werden soll.

1. Geben Sie Ihre Bereiche an. NAA unterstützt inkrementelle und dynamische Zustimmung. Fordern Sie daher immer die Mindestbereiche an, die für ihren Code erforderlich sind, um die Aufgabe abzuschließen.
2. Aufrufen von acquireTokenSilent Dadurch wird das Token abgerufen, ohne dass eine Benutzerinteraktion erforderlich ist.
3. Wenn acquireTokenSilent ein Fehler auftritt, rufen Sie auf acquireTokenPopup , um ein interaktives Dialogfeld für den Benutzer anzuzeigen. acquireTokenSilent kann fehlschlagen, wenn das Token abgelaufen ist oder der Benutzer noch nicht allen angeforderten Bereichen zugestimmt hat.

Der folgende Code zeigt, wie Sie dieses Authentifizierungsmuster in Ihrem eigenen Projekt implementieren.

1. Ersetzen Sie die run Funktion in taskpane.js oder taskpane.ts durch den folgenden Code. Der Code gibt die Mindestbereiche an, die zum Lesen der Dateien des Benutzers erforderlich sind.

   async function run() {
   // Specify minimum scopes needed for the access token.
   const tokenRequest = {
     scopes: ["Files.Read", "User.Read", "openid", "profile"],
   };
   let accessToken = null;
   
   // TODO 1: Call acquireTokenSilent.
   
   // TODO 2: Call acquireTokenPopup.
   
   // TODO 3: Log error if token still null.
   
   // TODO 4: Call the Microsoft Graph API.
   
   }
   

2. Ersetzen Sie TODO 1 durch den folgenden Code. Dieser Code ruft auf acquireTokenSilent , um das Zugriffstoken abzurufen.

   try {
     console.log("Trying to acquire token silently...");
     const userAccount = await pca.acquireTokenSilent(tokenRequest);
     console.log("Acquired token silently.");
     accessToken = userAccount.accessToken;
   } catch (error) {
     console.log(`Unable to acquire token silently: ${error}`);
   }
   

3. Ersetzen Sie TODO 2 durch den folgenden Code. Dieser Code überprüft, ob das Zugriffstoken abgerufen wird. Andernfalls wird versucht, das Zugriffstoken interaktiv abzurufen, indem aufgerufen acquireTokenPopupwird.

   if (accessToken === null) {
     // Acquire token silent failure. Send an interactive request via popup.
     try {
       console.log("Trying to acquire token interactively...");
       const userAccount = await pca.acquireTokenPopup(tokenRequest);
       console.log("Acquired token interactively.");
       accessToken = userAccount.accessToken;
     } catch (popupError) {
       // Acquire token interactive failure.
       console.log(`Unable to acquire token interactively: ${popupError}`);
     }
   }
   

4. Ersetzen Sie TODO 3 durch den folgenden Code. Wenn sowohl die automatische als auch die interaktive Anmeldung fehlgeschlagen ist, protokollieren Sie den Fehler, und geben Sie zurück.

   // Log error if both silent and popup requests failed.
   if (accessToken === null) {
     console.error(`Unable to acquire access token.`);
     return;
   }
   

Aufrufen einer API

Nachdem Sie das Token abgerufen haben, verwenden Sie es, um eine API aufzurufen. Im folgenden Beispiel wird gezeigt, wie Sie die Microsoft-Graph-API aufrufen, indem Sie fetch mit dem Token aufrufen, das im Autorisierungsheader angefügt ist.

• Ersetzen Sie TODO 4 durch den folgenden Code.

  // Call the Microsoft Graph API with the access token.
  const response = await fetch(
    `https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name&$top=10`,
    {
      headers: { Authorization: accessToken },
    }
  );
  
  if (response.ok) {
    // Write file names to the console.
    const data = await response.json();
    const names = data.value.map((item) => item.name);
  
    // Be sure the taskpane.html has an element with Id = item-subject.
    const label = document.getElementById("item-subject");
  
    // Write file names to task pane and the console.
    const nameText = names.join(", ");
    if (label) label.textContent = nameText;
    console.log(nameText);
  } else {
    const errorText = await response.text();
    console.error("Microsoft Graph call failed - error text: " + errorText);
  }
  

Nachdem der gesamte vorherige Code der run Funktion hinzugefügt wurde, stellen Sie sicher, dass eine Schaltfläche im Aufgabenbereich die run Funktion aufruft. Anschließend können Sie das Add-In querladen und den Code ausprobieren.

Was ist die Authentifizierung geschachtelter Apps?

Die Authentifizierung geschachtelter Apps ermöglicht einmaliges Anmelden für Anwendungen, die in unterstützten Microsoft-Anwendungen geschachtelt sind. Beispielsweise führt Excel unter Windows Ihr Add-In in einer Webansicht aus. In diesem Szenario ist Ihr Add-In eine geschachtelte Anwendung, die in Excel ausgeführt wird, dem Host. NAA unterstützt auch geschachtelte Apps in Teams. Wenn beispielsweise eine Teams-Registerkarte Excel hostet und Ihr Add-In geladen ist, wird es in Excel geschachtelt, das ebenfalls in Teams geschachtelt ist. Auch hier unterstützt NAA dieses geschachtelte Szenario, und Sie können auf SSO zugreifen, um die Benutzeridentität und Zugriffstoken des angemeldeten Benutzers abzurufen.

Bewährte Methoden

Wir empfehlen die folgenden bewährten Methoden, wenn Sie MSAL.js mit NAA verwenden.

Verwenden der automatischen Authentifizierung, wann immer möglich

MSAL.js stellt die -Methode bereit, die acquireTokenSilent die Tokenerneuerung verarbeitet, indem automatische Tokenanforderungen ohne Benutzeraufforderungen ausgeführt werden. Die -Methode sucht zuerst nach einem gültigen zwischengespeicherten Token. Wenn keines gefunden wird, sendet die Bibliothek die automatische Anforderung an Microsoft Entra ID und wenn eine aktive Benutzersitzung vorhanden ist, wird ein neues Token zurückgegeben.

In bestimmten Fällen schlägt der Versuch der acquireTokenSilent Methode, das Token abzurufen, fehl. Beispiele hierfür sind eine abgelaufene Benutzersitzung mit Microsoft Entra ID oder eine Kennwortänderung durch den Benutzer, die eine Benutzerinteraktion erfordert. Wenn acquireTokenSilent fehlschlägt, müssen Sie die interaktive acquireTokenPopup Tokenmethode aufrufen.

Fallback, wenn NAA nicht unterstützt wird

Obwohl wir bestrebt sind, ein hohes Maß an Kompatibilität mit diesen Flows im gesamten Microsoft-Ökosystem bereitzustellen, wird Ihr Add-In möglicherweise in einen älteren Office-Host geladen, der NAA nicht unterstützt. In diesen Fällen unterstützt Ihr Add-In kein nahtloses einmaliges Anmelden, und Sie müssen möglicherweise auf eine alternative Methode zur Authentifizierung des Benutzers zurückgreifen. Im Allgemeinen sollten Sie das MSAL SPA-Authentifizierungsmuster mit der Office JS-Dialog-API verwenden.

Verwenden Sie den folgenden Code, um zu überprüfen, ob NAA beim Laden des Add-Ins unterstützt wird.

   Office.context.requirements.isSetSupported("NestedAppAuth", "1.1");

Weitere Informationen finden Sie in den folgenden Ressourcen.

• Outlook-Beispiel: Fallback und Unterstützung von Internet Explorer 11
• Authentifizieren und Autorisieren mit der Office-Dialog-API.
• Microsoft-Identitätsbeispiel für SPA und JavaScript
• Microsoft-Identitätsbeispiele für verschiedene App-Typen und Frameworks

MSAL.js-APIs, die von NAA unterstützt werden

Die folgende Tabelle zeigt, welche APIs unterstützt werden, wenn NAA in der MSAL-Konfiguration aktiviert ist.

Methode	Unterstützt von NAA
acquireTokenByCode	Nein (löst eine Ausnahme aus)
acquireTokenPopup	Ja
acquireTokenRedirect	Nein (löst eine Ausnahme aus)
acquireTokenSilent	Ja
addEventCallback	Ja
addPerformanceCallback	Nein (löst eine Ausnahme aus)
disableAccountStorageEvents	Nein (löst eine Ausnahme aus)
enableAccountStorageEvents	Nein (löst eine Ausnahme aus)
getAccountByHomeId	Ja
getAccountByLocalId	Ja
getAccountByUsername	Ja
getActiveAccount	Ja
getAllAccounts	Ja
getConfiguration	Ja
getLogger	Ja
getTokenCache	Nein (löst eine Ausnahme aus)
handleRedirectPromise	Nein
initialize	Ja
initializeWrapperLibrary	Ja
loginPopup	Ja
loginRedirect	Nein (löst eine Ausnahme aus)
logout	Nein (löst eine Ausnahme aus)
logoutPopup	Nein (löst eine Ausnahme aus)
logoutRedirect	Nein (löst eine Ausnahme aus)
removeEventCallback	Ja
removePerformanceCallback	Nein (löst eine Ausnahme aus)
setActiveAccount	Nein
setLogger	Ja
ssoSilent	Ja

Sicherheitsberichte

Wenn Sie ein Sicherheitsproblem mit unseren Bibliotheken oder Diensten feststellen, melden Sie das Problem mit secure@microsoft.com so vielen Details, wie Sie angeben können. Ihre Übermittlung kann über das Microsoft Bounty-Programm für eine Bounty-Belohnung berechtigt sein. Veröffentlichen Sie keine Sicherheitsprobleme auf GitHub oder auf einer anderen öffentlichen Website. Wir setzen uns kurz nach Erhalt Ihres Problemberichts mit Ihnen in Verbindung. Wir empfehlen Ihnen, neue Benachrichtigungen zu Sicherheitsvorfällen zu erhalten, indem Sie microsoft technical security notifications besuchen, um Sicherheitsempfehlungswarnungen zu abonnieren.

Codebeispiele

Beispielname	Beschreibung
Office-Add-In mit SSO mit geschachtelter App-Authentifizierung	Zeigt, wie Sie MSAL.js geschachtelte App-Authentifizierung (NAA) in einem Office-Add-In verwenden, um auf Microsoft Graph-APIs für den angemeldeten Benutzer zuzugreifen. Im Beispiel werden der Name und die E-Mail-Adresse des angemeldeten Benutzers angezeigt. Außerdem werden die Namen von Dateien aus dem Microsoft OneDrive-Konto des Benutzers in das Dokument eingefügt.
Outlook-Add-In mit SSO mit geschachtelter App-Authentifizierung	Zeigt, wie Sie MSAL.js geschachtelte App-Authentifizierung (NAA) in einem Outlook-Add-In verwenden, um auf Microsoft Graph-APIs für den angemeldeten Benutzer zuzugreifen. Im Beispiel werden der Name und die E-Mail-Adresse des angemeldeten Benutzers angezeigt. Außerdem werden die Namen von Dateien aus dem Microsoft OneDrive-Konto des Benutzers in einen neuen Nachrichtentext eingefügt.

Siehe auch

• Häufig gestellte Fragen zu NAA