Häufig gestellte Fragen zur Authentifizierung geschachtelter Apps

Was ist die Authentifizierung geschachtelter Apps (Nested App Authentication, NAA)?

Die Authentifizierung geschachtelter Apps ermöglicht einmaliges Anmelden (Single Sign-On, SSO) für Anwendungen, die in unterstützten Microsoft-Anwendungen wie Outlook geschachtelt sind. Im Vergleich zu vorhandenen voll vertrauenswürdigen Authentifizierungsmodellen und dem On-Behalf-of-Flow bietet NAA eine bessere Sicherheit und mehr Flexibilität in der App-Architektur und ermöglicht die Erstellung umfangreicher, clientgesteuerter Anwendungen. Weitere Informationen finden Sie unter Aktivieren des einmaligen Anmeldens in einem Office-Add-In mit geschachtelter App-Authentifizierung.

Kann ich Exchange Online Token anstelle von NAA verwenden?

Legacy-Exchange Online Benutzeridentitätstoken und Rückruftoken werden nicht mehr unterstützt und für alle Microsoft 365-Mandanten deaktiviert. Wenn ein Outlook-Add-In delegierten Benutzerzugriff oder eine Benutzeridentität erfordert, empfehlen wir die Verwendung von MSAL (Microsoft Authentication Library) und geschachtelter App-Authentifizierung.

Wenn Ihr Add-In eine API aufruft, die ein Exchange-Token anfordert, z getUserIdentityTokenAsync. B. , wird ein generischer Fehler ähnlich dem folgenden mit Fehlercodes wie 9017 oder 9018 angezeigt.

  • "GenericTokenError: Ein interner Fehler ist aufgetreten."
  • "InternalServerError: Der Exchange-Server hat einen Fehler zurückgegeben. Weitere Informationen finden Sie im Diagnose-Objekt."

Beachten Sie, dass Exchange-Token für lokale Exchange-Instanzen weiterhin funktionieren und unterstützt werden.

Gewusst wie ein Problem mit NAA melden?

Stellen Sie Fragen zu NAA auf der OfficeDev/office-js GitHub Issues-Website. Bitte fügen Sie "NAA" in den Titel ein, damit wir Probleme gruppieren und priorisieren können.

Wenn Sie ein Problem übermitteln, geben Sie die folgenden Informationen an.

  • Outlook-Clientversion.
  • Zielgruppe des Outlook-Releasekanals (für Client).
  • Screenshot des Problems.
  • Die Plattform, auf der das Problem auftritt (Windows, Outlook (neu), Mac, iOS, Android).
  • Sitzungs-ID, bei der das Problem aufgetreten ist.
  • Typ des verwendeten Kontos.
  • Version von msal-browser.
  • Protokolle aus msal-browser.

Gewusst wie weitere Debuginformationen von MSAL und NAA erhalten?

Verwenden Sie den folgenden Code, um Debuginformationen in msalConfig zu aktivieren, wenn Sie die geschachtelte öffentliche Clientanwendung initialisieren. Dadurch werden zusätzliche Details in der Konsole protokolliert.

const msalConfig = {
  auth: {...},
  system: {
    loggerOptions: {
      logLevel: LogLevel.Verbose,
      loggerCallback: (level, message, containsPii) => {
        switch (level) {
          case LogLevel.Error:
            console.error(message);
            return;
          case LogLevel.Info:
            console.info(message);
            return;
          case LogLevel.Verbose:
            console.debug(message);
            return;
          case LogLevel.Warning:
            console.warn(message);
            return;
        }
      },
    }
  }
};

Welche Token gibt MSAL zurück, und gibt es Mindestbereiche für die Anforderung?

Wenn Sie ein Token über MSAL anfordern, werden immer drei Token zurückgegeben.

Token Zweck Scopes AuthencationResult Eigenschaft
ID-Token Stellt dem Client (Aufgabenbereich) Informationen zum Benutzer bereit. profile und openid authResult.idToken
Aktualisierungstoken Aktualisiert die ID und zugriffstoken, wenn sie ablaufen. offline_access Nicht verfügbar.
Zugriffstoken Authentifiziert den Benutzer für bestimmte Bereiche für eine Ressource, z. B. Microsoft Graph. Alle Ressourcenbereiche, z user.read. B. . authResult.accessToken

MSAL gibt immer diese drei Token zurück. Sie fordert , profileopenidund offline_access als Standardbereiche an, auch wenn Ihre Tokenanforderung diese nicht enthält. Dadurch wird sichergestellt, dass die ID und Aktualisierungstoken angefordert werden. Sie müssen jedoch mindestens einen Ressourcenbereich einschließen, z user.read . B. damit Sie ein Zugriffstoken erhalten. Andernfalls kann die Anforderung fehlschlagen.

Sollte ich das ID-Token von MSAL überprüfen?

Nein Dies ist ein Legacyauthentifizierungsmuster, das mit Exchange-Token verwendet wurde, um den Zugriff auf Ihre eigenen Ressourcen zu autorisieren. Die Übergabe des ID-Tokens über einen Netzwerkaufruf, um den Zugriff auf einen Dienst zu aktivieren oder zu autorisieren, ist ein Sicherheits-Antimuster. Das ID-Token ist nur für den Client (Aufgabenbereich) vorgesehen, und es gibt keine Möglichkeit für den Dienst, das Token zuverlässig zu verwenden, um sicherzustellen, dass der Benutzer über autorisierten Zugriff verfügt. Weitere Informationen zu ID-Tokenansprüchen finden Sie unter Referenz zu ID-Tokenansprüchen.

Es ist sehr wichtig, dass Sie immer ein Zugriffstoken für Ihre eigenen Dienste anfordern. Das Zugriffstoken enthält auch die gleichen ID-Ansprüche, sodass Sie das ID-Token nicht übergeben müssen. Erstellen Sie stattdessen einen benutzerdefinierten Bereich für Ihren Dienst. Weitere Informationen zu App-Registrierungseinstellungen für Ihre eigenen Dienste finden Sie unter Geschützte Web-API: App-Registrierung. Wenn Ihr Dienst das Zugriffstoken empfängt, kann er es überprüfen und ID-Ansprüche aus dem Zugriffstoken verwenden.

Warum erhalte ich Fehler von Richtlinien für bedingten Zugriff?

Die genehmigte Gewährung des bedingten Zugriffs für Client-Apps ist veraltet und wird im März 2026 eingestellt. MSAL NAA unterstützt diese Richtlinie nicht und gibt Fehler zurück (auch wenn Sie dem Add-In eine Ausnahme für diese Richtlinie gewähren.) Informationen zum Migrieren von dieser Richtlinie finden Sie unter Migrieren einer genehmigten Client-App zur Anwendungsschutzrichtlinie unter Bedingter Zugriff.

Einige Richtlinien für bedingten Zugriff verursachen Probleme für Add-Ins, die MSAL NAA verwenden, je nachdem, was sie vom Client benötigen. Häufig stehen diese im Zusammenhang mit Geräteverwaltungsrichtlinien. Weitere Informationen finden Sie unter Geräteverwaltungstypen unter Erstellen und Zuweisen von App-Schutzrichtlinien.

Manchmal müssen Sie anspruchsbezogene Herausforderungen basierend auf Richtlinien bewältigen. Weitere Informationen zum Behandeln einer Anspruchsaufforderung in Ihrem Add-In finden Sie unter Anspruchsaufforderungen, Anspruchsanforderungen und Clientfunktionen.

Warum wird das ID-Token nicht aktualisiert?

Es gibt ein bekanntes Problem, bei dem MSAL das ID-Token manchmal nicht aktualisiert, nachdem es abgelaufen ist. Dies sollte keine Probleme in Ihrem Add-In verursachen, da das ID-Token nur für die Verwendung in Ihrem Aufgabenbereich vorgesehen ist, um grundlegende Benutzeridentitätsinformationen wie Name und E-Mail abzurufen. Es gibt keinen Grund, das ID-Token zu überprüfen oder den Ablaufanspruch zu überprüfen. Wenn Sie den Benutzer bei Ihren eigenen Ressourcen authentifizieren müssen, verwenden Sie das Zugriffstoken, das auch Informationen zur Benutzeridentität enthält. Das ID-Token darf niemals außerhalb Ihres Clientcodes übergeben werden, von dem es empfangen wurde.

Wie kann ich in Outlook feststellen, ob der Benutzer ein Online- oder lokales Konto ist?

Mithilfe der Office.UserProfile.accountType-Eigenschaft können Sie ermitteln, ob der angemeldete Benutzer über ein Exchange Online-Konto oder ein lokales Exchange-Konto verfügt. Wenn der Wert der Kontotypeigenschaft enterprise ist, befindet sich das Postfach auf einem lokalen Exchange-Server. Beachten Sie, dass volumenlizenzierte unbefristete Outlook 2016 die accountType-Eigenschaft nicht unterstützt. Um dies zu umgehen, rufen Sie den ResolveNames-Vorgang im Exchange-Webdienst (EWS) auf dem lokalen Exchange-Server auf, um die Empfängertypen abzurufen.

Hinweis

Outlook 2016 und Outlook 2019 werden nicht mehr unterstützt. Weitere Informationen finden Sie unter Ende des Supports für Office 2016 und Office 2019.

Die accountType-Eigenschaft erfordert den Postfachanforderungssatz 1.6. Auf älteren Outlook-Clients müssen Sie den AutoErmittlungsdienst wie folgt verwenden.

Rufen Sie den AutoErmittlungsendpunkt für die outlook.office365.com-Domäne auf. https://outlook.office365.com/autodiscover/autodiscover.json/v1.0/{email}?Protocol=EWS&ServerLocation=true

  • Bei Onlinekonten gibt der Dienst ein Ergebnis zurück, bei dem der ServerLocation Schlüssel auf Exchange Online festgelegt ist.
  • Bei lokalen Konten gibt der Dienst keinen Schlüssel zurück ServerLocation .

Hinweis

Für Kunden, die Vanity-URLs verwenden, müssen Sie Ihr Add-In speziell so konfigurieren, dass der AutoErmittlungsdienst auf dem Vanity-URL-Endpunkt aufgerufen wird.

Gewusst wie Bereitstellen meines Add-Ins im Microsoft Marketplace

Wenn Sie ein neues Add-In im Microsoft Marketplace veröffentlichen, muss es einen Zertifizierungsprozess durchlaufen. Weitere Informationen finden Sie unter Veröffentlichen Ihres Office-Add-Ins im Microsoft Marketplace. Wenn Sie das Manifest eines Add-Ins aktualisieren, das bereits im Microsoft Marketplace veröffentlicht wurde, müssen Sie den Zertifizierungsprozess erneut durchlaufen. Sie können den Quellcode des Add-Ins jederzeit auf Ihrem Webserver aktualisieren, ohne den Zertifizierungsprozess durchlaufen zu müssen.

Wenn Ihr Add-In SSO über NAA verwendet, muss Ihr Add-In den folgenden Veröffentlichungsrichtlinien entsprechen.

Achten Sie darauf, die Administratoreinwilligung ordnungsgemäß zu behandeln. Weitere Informationen finden Sie unter Veröffentlichen eines Add-Ins, das die Administratoreinwilligung für Microsoft Graph-Bereiche erfordert.

Weitere Informationen zur Bereitstellung finden Sie unter Bereitstellen Ihrer Lösungen im Microsoft Marketplace und in Office. Wenn Sie Ihr Add-In aktualisieren (das Manifest ändern), müssen Sie den Zertifizierungsprozess erneut durchlaufen. Sie können Ihren Webservercode jederzeit aktualisieren, ohne dass eine Überprüfung erforderlich ist.

Benutzer erhalten bei der Anmeldung einen unerklärlichen Fehler.

Wenn Ihr Add-In ein Token anfordert, wird benutzern möglicherweise ein Anmelde-Popupdialogfeld mit einem der folgenden Fehler angezeigt.

  • Ein Problem ist aufgetreten. [Fehlercode]
  • Sie können von hier aus nicht dorthin gelangen

Überprüfen Sie, ob für den Administrator Richtlinien für bedingten Zugriff angewendet wurden, die bestimmte Clienteinschränkungen erzwingen, z. B. mobiler Standort oder Plattformtyp. Außerdem ist die genehmigte Client-App-Gewährung für bedingten Zugriff veraltet und verursacht diese Fehler bei NAA-Tokenanforderungen. Ein Administrator muss diese Richtlinie vollständig entfernen und zur neueren Anwendungsschutzrichtlinie wechseln, damit NAA funktioniert. Weitere Informationen finden Sie unter Migrieren einer genehmigten Client-App zur Anwendungsschutzrichtlinie unter Bedingter Zugriff.

Verwandte Inhalte

  • Last updated on