Verwenden von SSO zum Abrufen der Identität des angemeldeten Benutzers

  • Artikel

Verwenden Sie die getAccessToken API, um ein Zugriffstoken abzurufen, das die Identität für den aktuellen Benutzer enthält, der bei Office angemeldet ist. Das Zugriffstoken ist auch ein ID-Token, da es Identitätsansprüche über den angemeldeten Benutzer enthält, z. B. seinen Namen und seine E-Mail-Adresse. Sie können auch das ID-Token verwenden, um den Benutzer zu identifizieren, wenn Sie Ihre eigenen Webdienste aufrufen. Um aufzurufen getAccessToken, müssen Sie Ihr Office-Add-In so konfigurieren, dass SSO mit Office verwendet wird.

In diesem Artikel erstellen Sie ein Office-Add-In, das das ID-Token abruft und den Namen, die E-Mail-Adresse und die eindeutige ID des Benutzers im Aufgabenbereich anzeigt.

Hinweis

SSO mit Office und der getAccessToken API funktioniert nicht in allen Szenarien. Implementieren Sie immer ein Fallbackdialogfeld, um den Benutzer anzumelden, wenn SSO nicht verfügbar ist. Weitere Informationen finden Sie unter Authentifizieren und Autorisieren mit der Office-Dialog-API.

Erstellen einer App-Registrierung

Um einmaliges Anmelden mit Office zu verwenden, müssen Sie eine App-Registrierung im Azure-Portal erstellen, damit die Microsoft Identity Platform Authentifizierungs- und Autorisierungsdienste für Ihr Office-Add-In und seine Benutzer bereitstellen kann.

  1. Um Ihre App zu registrieren, wechseln Sie zur Seite Azure-Portal – App-Registrierungen.

  2. Melden Sie sich mit den Administratoranmeldeinformationen bei Ihrem Microsoft 365-Mandanten an. Beispiel: MyName@contoso.onmicrosoft.com.

  3. Wählen Sie Neue Registrierung aus. Legen Sie auf der Seite Anwendung registrieren die Werte wie folgt fest.

    • Legen Sie Name auf Office-Add-in-SSO fest.
    • Legen Sie Unterstützte Kontotypen auf Konten in allen Organisationsverzeichnissen und persönliche Microsoft-Konten (z. B. Skype, Xbox, Outlook.com) fest.
    • Legen Sie den Anwendungstyp auf Web und dann den Umleitungs-URI auf fest https://localhost:[port]/dialog.html. Ersetzen Sie durch [port] die richtige Portnummer für Ihre Webanwendung. Wenn Sie das Add-In mit Yo Office erstellt haben, lautet die Portnummer in der Regel 3000 und befindet sich in der package.json-Datei. Wenn Sie das Add-In mit Visual Studio 2019 erstellt haben, befindet sich der Port in der SSL-URL-Eigenschaft des Webprojekts.
    • Wählen Sie Registrieren aus.

  4. Kopieren Und speichern Sie auf der Seite Office-Add-in-SSO die Werte für die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant). Beide werden in späteren Verfahren verwendet.

    Hinweis

    Diese Anwendungs-ID (Client-ID) ist der "Audience"-Wert, wenn andere Anwendungen, z. B. die Office-Clientanwendung (z. B. PowerPoint, Word, Excel), autorisierten Zugriff auf die Anwendung suchen. Dies ist auch die "Client-ID" der Anwendung, wenn sie wiederum autorisierten Zugriff auf Microsoft Graph anstrebt.

  5. Wählen Sie unter Verwalten die Option Authentifizierung aus. Aktivieren Sie im Abschnitt Implizite Genehmigung die Kontrollkästchen sowohl für Zugriffstoken als auch für ID-Token.

  6. Wählen Sie am oberen Rand des Formulars Speichern aus.

  7. Wählen Sie unter Verwalten die Option Eine API verfügbar machen aus. Wählen Sie den Link Festlegen aus. Dadurch wird der Anwendungs-ID-URI im Format api://[app-id-guid]generiert, wobei [app-id-guid] die Anwendungs-ID (Client-ID) ist.

  8. Fügen Sie localhost:[port]/ in der generierten ID (beachten Sie den am Ende angefügten Schrägstrich "/") zwischen den doppelten Schrägstrichen und der GUID ein. Ersetzen Sie durch [port] die richtige Portnummer für Ihre Webanwendung. Wenn Sie das Add-In mit Yo Office erstellt haben, lautet die Portnummer in der Regel 3000 und befindet sich in der package.json-Datei. Wenn Sie das Add-In mit Visual Studio 2019 erstellt haben, befindet sich der Port in der SSL-URL-Eigenschaft des Webprojekts.

    Wenn Sie fertig sind, sollte die gesamte ID das Formular api://localhost:[port]/[app-id-guid]haben, z. B api://localhost:44355/c6c1f32b-5e55-4997-881a-753cc1d563b7. .

  9. Wählen Sie die SchaltflächeBereich hinzufügen aus. Geben Sie access_as_user im daraufhin geöffneten Bereich als Bereichsnamen<> ein.

  10. Legen Sie Wer darf einwilligen? auf Administratoren und Benutzer fest.

  11. Füllen Sie die Felder zum Konfigurieren der Eingabeaufforderungen für die Administrator- und Benutzereinwilligung mit Werten aus, die für den access_as_user Bereich geeignet sind, sodass die Office-Clientanwendung die Web-APIs Ihres Add-Ins mit den gleichen Rechten wie der aktuelle Benutzer verwenden kann. Vorschläge:

    • Admin Anzeigename der Zustimmung: Office kann als Benutzer fungieren.
    • Beschreibung der Administratoreinwilligung: Office ermöglichen, die Web-APIs des Add-Ins mit den gleichen Berechtigungen wie der aktuelle Benutzer aufzurufen.
    • Anzeigename der Benutzer-Zustimmung: Office kann wie Sie handeln.
    • Beschreibung der Benutzerzustimmung: Aktivieren Sie Office das Aufrufen der Web-APIs des Add-Ins mit den gleichen Rechten wie Sie.

  12. Stellen Sie sicher, Zustand auf Aktiviert festgelegt ist.

  13. Klicken Sie auf Bereich hinzufügen.

    Hinweis

    Der Domänenteil des Bereichsnamens>, der< direkt unterhalb des Textfelds angezeigt wird, sollte automatisch mit dem anwendungs-ID-URI übereinstimmen, den Sie zuvor festgelegt haben, wobei /access_as_user an das Ende angefügt wird, api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_userz. B. .

  14. Geben Sie im Abschnitt Autorisierte Clientanwendungen die folgende ID ein, um alle Microsoft Office-Anwendungsendpunkte vorab zu autorisieren.

    • ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (Alle Microsoft Office-Anwendungsendpunkte)

    Hinweis

    Die ea5a67f6-b6f3-4338-b240-c655ddc3cc8e ID autorisiert Office auf allen folgenden Plattformen vorab. Alternativ können Sie eine ordnungsgemäße Teilmenge der folgenden IDs eingeben, wenn Sie aus irgendeinem Grund die Autorisierung für Office auf einigen Plattformen verweigern möchten. Lassen Sie einfach die IDs der Plattformen weg, von denen Sie die Autorisierung verweigern möchten. Benutzer Ihres Add-Ins auf diesen Plattformen können Ihre Web-APIs nicht aufrufen, aber andere Funktionen in Ihrem Add-In funktionieren weiterhin.

    • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)
    • 93d53678-613d-4013-afc1-62e9e444a0a5 (Office im Web)
    • bc59ab01-8403-45c6-8796-ac3ef710b3e3 (Outlook im Web)

  15. Wählen Sie die Schaltfläche Clientanwendung hinzufügen aus, und legen Sie dann im daraufhin geöffneten Bereich den [app-id-guid] auf die Anwendungs-ID (Client-ID) fest, und aktivieren Sie das Kontrollkästchen für api://localhost:44355/[app-id-guid]/access_as_user.

  16. Wählen Sie Anwendung hinzufügen aus.

  17. Wählen Sie unter Verwalten die Option API-Berechtigungen und dann Berechtigung hinzufügen aus. Wählen Sie im Bereich, der geöffnet wird, Microsoft Graph und dann Delegierte Berechtigungen aus.

  18. Verwenden Sie das Suchfeld Berechtigungen auswählen, um die Berechtigungen zu suchen, die das Add-In benötigt. Suchen Sie nach der Profilberechtigung , und wählen Sie sie aus. Die profile Berechtigung ist erforderlich, damit die Office-Anwendung ein Token für Ihre Add-In-Webanwendung abrufen kann.

    • profile

    Hinweis

    Die Berechtigung User.Read wird möglicherweise bereits standardmäßig aufgeführt. Es empfiehlt sich, nicht nach Berechtigungen zu fragen, die nicht benötigt werden. Daher wird empfohlen, das Kontrollkästchen für diese Berechtigung zu deaktivieren, wenn Ihr Add-In sie nicht benötigt.

  19. Wählen Sie am unteren Rand des Bereichs die Schaltfläche Berechtigungen hinzufügen aus.

  20. Wählen Sie auf derselben Seite die Schaltfläche Administratoreinwilligung für <Mandantenname> erteilen und dann Ja für die angezeigte Bestätigung aus.

Erstellen des Office-Add-Ins

  1. Starten Sie Visual Studio 2019, und wählen Sie Neues Projekt erstellen aus.
  2. Suchen Sie nach der Projektvorlage Excel Web Add-In , und wählen Sie sie aus. Wählen Sie dann Weiter aus. Hinweis: SSO funktioniert mit jeder Office-Anwendung, aber Excel ist die Anwendung, die mit diesem Artikel verwendet wird.
  3. Geben Sie einen Projektnamen ein, z. B. sso-display-user-info, und wählen Sie Erstellen aus. Sie können die Standardwerte für die anderen Felder beibehalten.
  4. Wählen Sie im Dialogfeld Add-In-Typ auswählen die Option Neue Funktionalität zu Excel hinzufügen und dann Fertig stellen aus.

Das Projekt wird erstellt und enthält zwei Projekte in der Projektmappe.

  • sso-display-user-info: Enthält das Manifest und Details zum Querladen des Add-Ins in Excel.
  • sso-display-user-infoWeb: Das ASP.NET Projekt, das die Webseiten für das Add-In hostet.

Konfigurieren des Manifests

Öffnen Sie in Projektmappen-Explorersso-display-user-info>sso-display-user-infoManifest>sso-display-user-info.xml.

  1. Am unteren Rand des Manifests befindet sich ein schließende </Resources> Element. Fügen Sie den folgenden XML-Code direkt unterhalb des </Resources> Elements, aber vor dem schließende </VersionOverrides> Element ein. Fügen Sie für andere Office-Anwendungen als Outlook das Markup am Ende des <VersionOverrides ... xsi:type="VersionOverridesV1_0"> Abschnitts hinzu. Für Outlook fügen Sie das Markup dem Ende des <VersionOverrides ... xsi:type="VersionOverridesV1_1">-Abschnitts hinzu.

    <WebApplicationInfo>
    <Id>[application-id]</Id>
    <Resource>api://localhost:[port]/[application-id]</Resource>
    <Scopes>
        <Scope>openid</Scope>
        <Scope>user.read</Scope>
        <Scope>profile</Scope>
    </Scopes>
</WebApplicationInfo>

  2. Ersetzen Sie durch [port] die richtige Portnummer für Ihr Projekt. Wenn Sie das Add-In mit Yo Office erstellt haben, lautet die Portnummer in der Regel 3000 und befindet sich in der package.json-Datei. Wenn Sie das Add-In mit Visual Studio 2019 erstellt haben, befindet sich der Port in der SSL-URL-Eigenschaft des Webprojekts.

  3. Ersetzen Sie beide [application-id] Platzhalter durch die tatsächliche Anwendungs-ID aus Ihrer App-Registrierung.

  4. Speichern Sie die Datei.

Der eingefügte XML-Code enthält die folgenden Elemente und Informationen.

  • <WebApplicationInfo> : Das übergeordnete Element der folgenden Elemente.
  • <ID> : Die Client-ID des Add-Ins. Hierbei handelt es sich um eine Anwendungs-ID, die Sie beim Registrieren des Add-Ins erhalten. Weitere Informationen finden Sie unter Registrieren eines Office-Add-Ins, das SSO mit dem Azure AD v2.0-Endpunkt verwendet.
  • <Ressource> : Die URL des Add-Ins. Hierbei handelt es sich um den gleichen URI (einschließlich des Protokolls api:), den Sie bei der Registrierung des Add-Ins in AAD verwendet haben. Der Domänenteil dieses URI muss mit der Domäne übereinstimmen, einschließlich aller Unterdomänen, die <in den URLs im Abschnitt Ressourcen> des Add-In-Manifests verwendet werden, und der URI muss mit der Client-ID in der <ID> enden.
  • <Bereiche:> Das übergeordnete Element eines oder mehrerer Scope-Elemente<>.
  • <Bereich> : Gibt eine Berechtigung an, die das Add-In für AAD benötigt. Die profile Berechtigungen und openID sind immer erforderlich und können die einzigen erforderlichen Berechtigungen sein, wenn Ihr Add-In nicht auf Microsoft Graph zugreift. Wenn dies der Fall ist, benötigen <Sie auch Scope-Elemente> für die erforderlichen Microsoft Graph-Berechtigungen, User.Readz. B. , Mail.Read. Für Bibliotheken, die Sie in Ihrem Code für den Zugriff auf Microsoft Graph verwenden, sind möglicherweise zusätzliche Berechtigungen erforderlich. Beispielsweise erfordert die Microsoft Authentication Library (MSAL) für .NET die offline_access -Berechtigung. Weitere Informationen finden Sie unter Berechtigung für Microsoft Graph in Ihrem Office-Add-In (Vorschau).

Hinzufügen des Pakets "jwt-decode"

Sie können die getAccessToken API aufrufen, um das ID-Token von Office abzurufen. Fügen Sie zunächst das Paket jwt-decode hinzu, um das Decodieren und Anzeigen des ID-Tokens zu vereinfachen.

  1. Öffnen Sie die Visual Studio-Projektmappe.

  2. Wählen Sie im Menü Extras>NuGet-Paket-Manager-Paket-Manager-Konsole> aus.

  3. Geben Sie in der Paket-Manager-Konsole den folgenden Befehl ein.

    Install-Package jwt-decode -Projectname sso-display-user-infoWeb

Hinzufügen der Benutzeroberfläche zum Aufgabenbereich

Ändern Sie den Aufgabenbereich so, dass er die Benutzerinformationen anzeigen kann, die Sie aus dem ID-Token erhalten.

  1. Öffnen Sie die Home.html Datei.

  2. Fügen Sie dem Abschnitt der Seite das <head> folgende Skripttag hinzu. Dies schließt das paket jwt-decode ein, das zuvor hinzugefügt wurde.

    <script src="Scripts/jwt-decode-2.2.0.js" type="text/javascript"></script>

  3. Ersetzen Sie den <body> Abschnitt durch den folgenden HTML-Code.

    <body>
  <h1>Welcome</h1>
  <p>
    Sign in to Office, then choose the <b>Get ID Token</b> button to see your
    ID token information.
  </p>
  <button id="getIDToken">Get ID Token</button>
  <div>
    <span id="userInfo"></span>
  </div>
</body>

Aufrufen der getAccessToken-API

Der letzte Schritt besteht darin, das ID-Token durch Aufrufen getAccessTokenvon abzurufen.

  1. Öffnen Sie die dateiHome.js .

  2. Ersetzen Sie den gesamten Inhalt der Datei durch den folgenden Code:

    (function () {
  "use strict";

  // The initialize function must be run each time a new page is loaded.
  Office.initialize = function (reason) {
    $(document).ready(function () {
      $("#getIDToken").on("click", getIDToken);
    });
  };

  async function getIDToken() {
    try {
      let userTokenEncoded = await OfficeRuntime.auth.getAccessToken({
        allowSignInPrompt: true,
      });
      let userToken = jwt_decode(userTokenEncoded);
      document.getElementById("userInfo").innerHTML =
        "name: " +
        userToken.name +
        "<br>email: " +
        userToken.preferred_username +
        "<br>id: " +
        userToken.oid;
      console.log(userToken);
    } catch (error) {
      document.getElementById("userInfo").innerHTML =
        "An error occurred. <br>Name: " +
        error.name +
        "<br>Code: " +
        error.code +
        "<br>Message: " +
        error.message;
      console.log(error);
    }
  }
})();

  3. Speichern Sie die Datei.

Ausführen des Add-Ins

Wählen Sie Debuggen>Debuggen starten aus, oder drücken Sie F5.

  1. Melden Sie sich beim Start von Excel bei Office mit demselben Mandantenkonto an, das Sie zum Erstellen der App-Registrierung verwendet haben.
  2. Wählen Sie im Menüband Start die Option Aufgabenbereich anzeigen aus, um das Add-In zu öffnen.
  3. Wählen Sie im Aufgabenbereich des Add-Ins ID-Token abrufen aus.

Das Add-In zeigt den Namen, die E-Mail-Adresse und die ID des Kontos an, mit dem Sie sich angemeldet haben.

Hinweis

Wenn Fehler auftreten, lesen Sie die Registrierungsschritte in diesem Artikel für die App-Registrierung. Das Fehlen eines Details beim Einrichten der App-Registrierung ist eine häufige Ursache für Probleme bei der Verwendung von SSO. Wenn Das Add-In immer noch nicht erfolgreich ausgeführt werden kann, finden Sie weitere Informationen unter Problembehandlung bei Fehlermeldungen für einmaliges Anmelden (Single Sign-On, SSO).

Siehe auch

Verwenden von Ansprüchen zur zuverlässigen Identifizierung eines Benutzers (Betreff und Objekt-ID)