Problembehandlung bei Fehlermeldungen für Einmaliges Anmelden (Single Sign-On, SSO)

  • Artikel

Dieser Artikel enthält Hinweise zur Behandlung von Problemen mit einmaligem Anmelden (Single Sign-On, SSO) in Office-Add-Ins und dazu, wie Sie Ihr SSO-fähiges Add-In so entwickeln können, dass besondere Bedingungen oder Fehler zuverlässig behoben werden.

Hinweis

Die Single Sign-On-API wird derzeit für Word, Excel, Outlook und PowerPoint unterstützt. Weitere Informationen dazu, wo die Single Sign-On-API derzeit unterstützt wird, finden Sie unter Identity-API-Anforderungssätze. Wenn Sie mit einem Outlook-Add-In arbeiten, müssen Sie die moderne Authentifizierung für den Microsoft 365-Mandanten aktivieren. Informationen dazu finden Sie unter Aktivieren oder Deaktivieren der modernen Authentifizierung für Outlook in Exchange Online.

Debugging-Tools

Es wird dringend empfohlen, dass Sie beim Entwickeln ein Tool verwenden, das die HTTP-Anforderungen von und die Antworten an den Webdienst des Add-Ins abfangen kann. Zwei der beliebtesten Tools sind:

Ursachen und Behandlung von Fehlern bei getAccessToken

Beispiele für die in diesem Abschnitt beschriebene Fehlerbehandlung finden Sie unter:

13000

Die getAccessToken-API wird vom Add-In oder der Office-Version nicht unterstützt.

  • Die Version von Office unterstützt SSO nicht. Die erforderliche Version ist ein Microsoft 365-Abonnement in jedem monatlichen Kanal.
  • Dem Add-In-Manifest fehlt der korrekte WebApplicationInfo-Abschnitt.

Das Add-in sollte auf diese Fehler reagieren, indem es auf ein alternatives System zur Benutzerauthentifizierung zurückgreift. Weitere Informationen finden Sie unter Anforderungen und bewährte Methoden.

13001

Der Benutzer ist nicht bei Office angemeldet. In den meisten Szenarien sollten Sie verhindern, dass dieser Fehler angezeigt wird, indem Sie die Option allowSignInPrompt: true im AuthOptions-Parameter übergeben.

Möglicherweise gibt es aber Ausnahmen. So möchten Sie beispielsweise, dass das Add-In mit Features geöffnet wird, die einen angemeldeten Benutzer erfordern; aber nur, wenn der Benutzer bereits bei Office angemeldet ist. Wenn der Benutzer nicht angemeldet ist, soll das Add-In mit einer anderen Gruppe von Features geöffnet werden, für die der Benutzer nicht angemeldet sein muss. In diesem Fall ruft die Logik, die ausgeführt wird, wenn das Add-In gestartet wird, getAccessToken ohne allowSignInPrompt: true auf. Verwenden Sie den 13001-Fehler als Kennzeichen, um das Add-In anzuweisen, die alternative Gruppe von Features darzustellen.

Eine weitere Option besteht darin, dass das Add-In auf 13001-Fehler reagiert, indem es auf ein alternatives System zur Benutzerauthentifizierung zurückgreift. Dadurch wird der Benutzer bei AAD, aber nicht bei Office angemeldet.

Dieser Fehler wird in Office im Web nie angezeigt. Nach Ablauf des Benutzer-Cookies gibt Office im Web den Fehler 13006 zurück.

13002

Der Benutzer hat die Anmeldung oder die Erteilung seiner Zustimmung abgebrochen; z. B. durch Klicken auf Abbrechen im Zustimmungsdialogfeld.

  • Wenn Ihr Add-In Funktionen bereitstellt, für die der Benutzer nicht angemeldet sein (oder seine Zustimmung abgegeben haben) muss, sollte Ihr Code diesen Fehler abfangen und ermöglichen, dass das Add-In weiterhin ausgeführt wird.
  • Wenn das Add-In einen angemeldeten Benutzer erfordert, der die Zustimmung erteilt hat, sollte im Code eine Anmeldeschaltfläche angezeigt werden.

13003

Benutzertyp nicht unterstützt. Der Benutzer ist nicht mit einem gültigen Microsoft-Konto oder Microsoft 365 Education- oder Geschäftskonto bei Office angemeldet. Dies kann passieren, wenn Office beispielsweise mit einem lokalen Domänenkonto ausgeführt wird. Der Code sollte auf ein alternatives System zur Benutzerauthentifizierung zurückgreifen. In Outlook kann dieser Fehler auch auftreten, wenn die moderne Authentifizierung für den Mandanten des Benutzers in Exchange Online deaktiviert ist. Weitere Informationen finden Sie unter Anforderungen und bewährte Methoden.

13004

Ungültige Ressource. (Dieser Fehler sollte nur in der Entwicklung auftreten.) Das Add-In-Manifest wurde nicht ordnungsgemäß konfiguriert. Aktualisieren Sie das Manifest. Weitere Informationen finden Sie unter Validieren eines Office-Add-In-Manifests. Das häufigste Problem besteht darin, dass das <Resource-Element> (im <WebApplicationInfo-Element> ) über eine Domäne verfügt, die nicht mit der Domäne des Add-Ins übereinstimmt. Obwohl der Protokollteil des Ressourcewerts „api“ statt „https“ lauten sollte, müssen alle anderen Teile des Domänennamens (inklusive Port, wenn vorhanden) mit denen des Add-Ins übereinstimmen.

13005

Ungültige Gewährung. Dies bedeutet normalerweise, dass Office nicht vorab für den Webdienst des Add-Ins autorisiert wurde. Weitere Informationen finden Sie unter Erstellen der Dienstanwendung und Registrieren des Add-Ins beim Azure AD v2.0-Endpunkt. Dies auch kann passieren, wenn der Benutzer Ihrer Dienstanwendung keine Berechtigungen für profile erteilt oder seine Zustimmung zurückgezogen hat. Der Code sollte auf ein alternatives System zur Benutzerauthentifizierung zurückgreifen.

Eine weitere mögliche Ursache während der Entwicklung ist, dass das Add-In mit Internet Explorer verwendet wird und Sie ein selbstsigniertes Zertifikat verwenden. (Informationen dazu, welcher Browser oder welche Webansicht vom Add-In verwendet wird, finden Sie unter Browser und Webview-Steuerelemente, die von Office-Add-Ins verwendet werden.)

13006

Clientfehler. Dieser Fehler wird nur in Office im Web angezeigt. Der Code sollte darauf hinweisen, dass der Benutzer sich abmeldet und dann die Office-Browsersitzung neu startet.

13007

Die Office-Anwendung konnte kein Zugriffstoken für den Webdienst des Add-Ins abrufen.

  • Wenn dieser Fehler bei der Entwicklung auftritt, achten Sie darauf, dass Ihre Add-In-Registrierung und das Add-In-Manifest die profile-Berechtigung (und die openid-Berechtigung, wenn Sie MSAL.NET verwenden) angeben. Weitere Informationen finden Sie unter Registrieren des Add-Ins beim Azure AD v2.0-Endpunkt.
  • In der Produktion kann ein Kontokonflikt diesen Fehler verursachen. Wenn der Benutzer beispielsweise versucht, sich mit einem persönlichen Microsoft-Konto (MSA) anzumelden, wenn ein Geschäfts-, Schul- oder Unikonto erwartet wurde. In diesen Fällen sollte Ihr Code auf ein alternatives System der Benutzerauthentifizierung zurückgreifen. Weitere Informationen zu Kontotypen finden Sie unter Identitäts- und Kontotypen für Apps mit und mehreren Mandanten.

13008

Der Benutzer hat einen Vorgang ausgelöst, der getAccessToken aufruft, bevor ein vorheriger Aufruf von getAccessToken abgeschlossen wurde. Dieser Fehler wird nur in Office im Web angezeigt. Ihr Code sollte den Benutzer auffordern, den Vorgang zu wiederholen, nachdem der vorherige Vorgang abgeschlossen wurde.

13010

Der Benutzer führt das Add-In in Office in Microsoft Edge aus. Die Microsoft 365-Domäne des Benutzers und die login.microsoftonline.com Domäne befinden sich in den Browsereinstellungen in anderen Sicherheitszonen. Dieser Fehler wird nur in Office im Web angezeigt. Wenn dieser Fehler zurückgegeben wird, wurde dem Benutzer bereits ein Fehler mit den entsprechenden Erläuterungen und einem Link zu einer Seite angezeigt, auf der das Ändern der Zonenkonfiguration erklärt wird. Wenn Ihr Add-In Funktionen bereitstellt, für die der Benutzer nicht angemeldet sein muss, sollte Ihr Code diesen Fehler abfangen und ermöglichen, dass das Add-In weiterhin ausgeführt wird.

13012

Es gibt mehrere mögliche Ursachen.

  • Das Add-In wird auf einer Plattform ausgeführt, die die getAccessToken-API nicht unterstützt. Es wird beispielsweise nicht auf dem iPad unterstützt. Siehe auch Identitäts-API-Anforderungssätze.
  • Das Office-Dokument wurde über die Registerkarte Dateien eines Teams-Kanals mit der Option In Teams bearbeiten im Dropdownmenü Öffnen geöffnet. Die getAccessToken API wird in diesem Szenario nicht unterstützt.
  • Die Option forMSGraphAccess wurde beim Aufruf von getAccessToken übergeben, und der Benutzer hat das Add-In von AppSource abgerufen. In diesem Szenario hat der Mandantenadministrator dem Add-In für die Microsoft Graph-Bereiche (Berechtigungen), die dieses benötigt, keine Zustimmung erteilt. Wenn Sie getAccessToken mit allowConsentPrompt zurückrufen, wird das Problem dadurch nicht gelöst, da Office den Benutzer auffordert, seine Zustimmung nur für den AAD profile-Bereich zu erteilen.

Der Code sollte auf ein alternatives System zur Benutzerauthentifizierung zurückgreifen.

In der Entwicklung wird das Add-In in Outlook quergeladen, und die Option forMSGraphAccess wurde im Aufruf von getAccessToken übergeben.

13013

Der getAccessToken wurde in kurzer Zeit zu oft aufgerufen, sodass Office den letzten Aufruf gedrosselt hat. Dies wird in der Regel durch eine Endlosschleife von Aufrufen der -Methode verursacht. Es gibt Szenarien, in denen ein Rückruf der Methode ratsam ist. Ihr Code sollte jedoch einen Zähler oder eine Flagvariable verwenden, um sicherzustellen, dass die Methode nicht wiederholt zurückgerufen wird. Wenn derselbe "Wiederholungscodepfad" erneut ausgeführt wird, sollte der Code auf ein alternatives System der Benutzerauthentifizierung zurückgreifen. Ein Codebeispiel finden Sie unter Verwendung der retryGetAccessToken Variablen in HomeES6.js oder ssoAuthES6.js.

50001

Dieser Fehler (der nicht spezifisch für getAccessToken ist) kann bedeuten, dass im Browser eine alte Kopie der office.js-Dateien zwischengespeichert ist. Löschen Sie bei der Entwicklung den Cache des Browsers. Eine weitere Möglichkeit besteht darin, dass die Version von Office nicht neu genug ist, um SSO zu unterstützen. Unter Windows ist der Mindestbuild 16.0.12215.20006. Auf dem Mac lautet dies 16.32.19102902.

In einem Production-Add-Inn sollte das Add-in auf diese Fehler reagieren, indem es auf ein alternatives System zur Benutzerauthentifizierung zurückgreift. Weitere Informationen finden Sie unter Anforderungen und bewährte Methoden.

Fehler auf der Serverseite von Azure Active Directory

Beispiele für die in diesem Abschnitt beschriebene Fehlerbehandlung finden Sie unter:

Fehler beim bedingten Zugriff/bei der multifaktoriellen Authentifizierung

In bestimmten Identitätskonfigurationen in AAD und Microsoft 365 ist es möglich, dass für einige Ressourcen, auf die mit Microsoft Graph zugegriffen werden kann, die mehrstufige Authentifizierung (Multi-Factor Authentication, MFA) erforderlich ist, auch wenn der Microsoft 365-Mandanten des Benutzers dies nicht tut. Wenn AAD eine Anforderung für ein Token für die MFA-geschützte Ressource über den Im-Auftrag-von-Fluss empfängt, wird an den Webdienst des Add-Ins eine JSON-Nachricht zurückgegeben, die eine claims-Eigenschaft enthält. Die claims-Eigenschaft hat keine Informationen darüber, welche weiteren Authentifizierungsfaktoren erforderlich sind.

In Ihrem Code sollte eine Prüfung auf diese claims-Eigenschaft erfolgen. Abhängig von der Architektur des Add-Ins können Sie auf der Clientseite eine Prüfung auf diese Eigenschaft durchführen oder auf der Serverseite; dann müssen Sie sie an den Client weiterleiten. Sie benötigen diese Informationen im Client, da Office die Authentifizierung für SSO-Add-Ins verarbeitet. Wenn Sie diese Informationen von der Serverweite weiterleiten, kann die Nachricht an den Client entweder ein Fehler (z. B. 500 Server Error oder 401 Unauthorized) oder im Textkörper einer Erfolgsantwort sein (z. B. 200 OK). In beiden Fällen sollte der Rückruf (Fehler oder Erfolg) des clientseitigen AJAX-Aufrufs Ihres Codes für die Web-API des Add-Ins diese Antwort testen.

Unabhängig von Ihrer Architektur sollte Ihr Code die Option authChallenge: CLAIMS-STRING-HERE im options Parameter abrufen getAccessToken und übergeben, wenn der Anspruchswert von AAD gesendet wurde. Wenn AAD diese Zeichenfolge erkennt, wird der Benutzer aufgefordert, die weiteren Faktoren einzugeben. Es wird dann ein neues Zugriffstoken zurückgegeben, das im Im-Auftrag-von-Fluss akzeptiert wird.

Wenn AAD nicht über einen Datensatz verfügt, dass die Zustimmung (zur Microsoft Graph-Ressource) dem Add-In vom Benutzer (oder Mandantenadministrator) gewährt wurde, sendet AAD eine Fehlermeldung an den Webdienst. Ihr Code muss den Client anweisen (z. B. im Textkörper einer 403 Forbidden-Antwort).

Wenn das Add-In Microsoft Graph-Bereiche benötigt, die nur von einem Administrator zugewiesen werden können, sollte Ihr Code einen Fehler auslösen. Wenn die einzigen Bereiche, die benötigt werden, vom Benutzer zugewiesen werden können, sollte Ihr Code auf ein alternatives System zur Benutzerauthentifizierung zurückgreifen.

Fehler bei ungültigen oder fehlenden Bereichen (Berechtigungen)

Diese Art von Fehler sollte nur in der Entwicklung zu sehen sein.

  • Ihr serverseitiger Code sollte eine 403 Forbidden-Antwort an den Client senden, der den Fehler in der Konsole oder in einem Protokoll protokollieren sollte.
  • Vergewissern Sie sich, dass im Abschnitt Bereiche Ihres Add-In-Manifests alle erforderlichen Berechtigungen angegeben werden. Und achten Sie unbedingt darauf, dass die Registrierung des Webdiensts des Add-Ins dieselben Berechtigungen angibt. Führen Sie auch eine Rechtschreibprüfung durch. Weitere Informationen finden Sie unter Registrieren des Add-Ins beim Azure AD v2.0-Endpunkt.

Fehler "Ungültige Zielgruppe" im Zugriffstoken für Microsoft Graph

Ihr serverseitiger Code sollte eine 403 Forbidden-Antwort an den Client senden, der eine aussagekräftige Nachricht für den Benutzer anzeigt und auch den Fehler möglicherweise in der Konsole oder in einem Protokoll protokolliert.