Registrieren eines Office-Add-Ins, das einmaliges Anmelden (Single Sign-On, SSO) mit dem Microsoft Identity Platform

  • Artikel

In diesem Artikel wird erläutert, wie Sie ein Office-Add-In beim Microsoft Identity Platform registrieren, damit Sie einmaliges Anmelden verwenden können. Registrieren Sie das Add-In, wenn Sie mit der Entwicklung beginnen, damit Sie die vorhandene Registrierung ändern oder separate Registrierungen für Entwicklungs-, Test- und Produktionsversionen des Add-Ins erstellen können.

Die folgende Tabelle enth?lt die Informationen, die Sie zur Durchf?hrung dieser Prozedur ben?tigen, sowie die entsprechenden Platzhalter, die in der Anleitung erscheinen.

Informationen Beispiele Platzhalter
Ein lesbarer Name für das Add-In. (Eindeutigkeit empfohlen, aber nicht erforderlich.) Contoso Marketing Excel Add-in (Prod) <add-in-name>
Eine Anwendungs-ID, die Azure im Rahmen des Registrierungsprozesses für Sie generiert. c6c1f32b-5e55-4997-881a-753cc1d563b7 <app-id>
Der vollqualifizierte Dom?nenname (au?er f?r Protokoll) des Add-Ins. Sie m?ssen eine eigene Dom?ne verwenden. Aus diesem Grund k?nnen Sie bestimmte bekannte Dom?nen wie azurewebsites.net oder cloudapp.netnicht verwenden. Die Domäne muss identisch sein, einschließlich aller Unterdomänen, wie sie in den URLs im <Abschnitt Ressourcen> des Add-In-Manifests verwendet wird. localhost:6789, addins.contoso.com <fully-qualified-domain-name>
Die Berechtigungen für die Microsoft Identity Platform und Microsoft Graph, die Ihr Add-In benötigt. (profile wird immer ben?tigt.) profile, Files.Read.All –

Achtung

Vertrauliche Informationen: Der Anwendungs-ID-URI (<fully-qualified-domain-name>) wird als Teil des Authentifizierungsprozesses protokolliert, wenn ein Add-In mit SSO in Office aktiviert wird, das innerhalb von Microsoft Teams ausgeführt wird. Der URI darf keine vertraulichen Informationen enthalten.

Registrieren des Add-Ins bei Microsoft Identity Platform

Sie müssen eine App-Registrierung in Azure erstellen, die Ihren Webserver darstellt. Dadurch wird die Authentifizierungsunterstützung aktiviert, sodass geeignete Zugriffstoken für den Clientcode in JavaScript ausgestellt werden können. Diese Registrierung unterstützt sowohl das einmalige Anmelden im Client als auch die Fallbackauthentifizierung mithilfe der Microsoft Authentication Library (MSAL).

  1. Melden Sie sich beim Azure-Portal mit den Administratoranmeldeinformationen für Ihren Microsoft 365-Mandanten an. Beispiel: MyName@contoso.onmicrosoft.com.

  2. Wählen Sie App-Registrierungen aus. Wenn das Symbol nicht angezeigt wird, suchen Sie in der Suchleiste nach "App-Registrierung".

    Die Azure-Portal Startseite.

    Die Seite App-Registrierungen wird angezeigt.

  3. Wählen Sie Neue Registrierung aus.

    Neue Registrierung im bereich App-Registrierungen.

    Die Seite Anwendung registrieren wird angezeigt.

  4. Legen Sie auf der Seite Anwendung registrieren die Werte wie folgt fest.

    • Legen Sie Name auf <add-in-name> fest.
    • Legen Sie Unterstützte Kontotypen auf Konten in jedem Organisationsverzeichnis (beliebiges Azure AD-Verzeichnis – mehrinstanzenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) fest.
    • Legen Sie den Umleitungs-URI für die Verwendung der Plattform-Single-Page-Anwendung (SPA) und den URI auf fest https://<fully-qualified-domain-name>/dialog.html.

    Registrieren Sie einen Anwendungsbereich mit dem Namen und dem unterstützten Konto.

  5. Wählen Sie Registrieren aus. Es wird eine Meldung mit dem Hinweis angezeigt, dass die Anwendungsregistrierung erstellt wurde.

    Meldung, dass die Anwendungsregistrierung erstellt wurde.

  6. Kopieren und speichern Sie die Werte für die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant). Beide werden in späteren Verfahren verwendet.

    Bereich

Hinzufügen eines geheimen Clientschlüssels

Manchmal auch als Anwendungskennwort bezeichnet, ist ein geheimer Clientschlüssel ein Zeichenfolgenwert, den Ihre App anstelle eines Zertifikats verwenden kann, um sich selbst zu identifizieren.

  1. Wählen Sie im linken Bereich Zertifikate & Geheimnisse aus. Wählen Sie dann auf der Registerkarte Geheime Clientschlüsseldie Option Neuer geheimer Clientschlüssel aus.

    Der Bereich Zertifikate & Geheimnisse.

    Der Bereich Geheimen Clientschlüssel hinzufügen wird angezeigt.

  2. Fügen Sie eine Beschreibung für Ihren geheimen Clientschlüssel hinzu.

  3. Wählen Sie einen Ablauf für das Geheimnis aus, oder geben Sie eine benutzerdefinierte Lebensdauer an.

    • Die Lebensdauer des geheimen Clientschlüssels ist auf maximal zwei Jahre (24 Monate) beschränkt. Sie können keine benutzerdefinierte Lebensdauer angeben, die länger als 24 Monate ist.
    • Microsoft empfiehlt, einen Ablaufwert von weniger als 12 Monaten festzulegen.

    Hinzufügen eines Bereichs für geheimen Clientschlüssel mit beschreibung und ablaufen abgeschlossen.

  4. Wählen Sie Hinzufügen. Das neue Geheimnis wird erstellt, und der Wert wird vorübergehend angezeigt.

Wichtig

Notieren Sie sich den Wert des Geheimnisses zur Verwendung in Ihrem Clientanwendungscode. Dieser Geheimniswert wird nie wieder angezeigt , nachdem Sie diesen Bereich verlassen haben.

Verfügbarmachen einer Web-API

  1. Wählen Sie im linken Bereich Api verfügbar machen aus.

    Der Bereich API verfügbar machen wird angezeigt.

    Der Bereich

  2. Wählen Sie Festlegen aus, um einen Anwendungs-ID-URI zu generieren.

    Schaltfläche

    Der Abschnitt zum Festlegen des Anwendungs-ID-URI wird mit einem generierten Anwendungs-ID-URI im Format api://<app-id>angezeigt.

  3. Aktualisieren Sie den Anwendungs-ID-URI auf api://<fully-qualified-domain-name>/<app-id>.

    Bearbeiten Sie den Bereich App-ID-URI mit localhost-Port, der auf 44355 festgelegt ist.

    • Der Anwendungs-ID-URI wird mit der App-ID (GUID) im Format api://<app-id> vorausgefüllt.
    • Das URI-Format der Anwendungs-ID sollte wie folgt sein: api://<fully-qualified-domain-name>/<app-id>
    • Fügen Sie zwischen fully-qualified-domain-nameapi:// und <app-id> (eine GUID) ein. Beispiel: api://contoso.com/<app-id>.
    • Wenn Sie localhost verwenden, sollte das Format sein api://localhost:<port>/<app-id>. Beispiel: api://localhost:3000/c6c1f32b-5e55-4997-881a-753cc1d563b7.

    Weitere Informationen zum Anwendungs-ID-URI finden Sie unter Bezeichner-Attribut des Anwendungsmanifests.

    Hinweis

    Wenn eine Fehlermeldung angezeigt wird, die besagt, dass die Domäne bereits beansprucht wird, Sie jedoch der Eigentümer sind, folgen Sie dem Verfahren unter Schnellstart: Hinzufügen eines benutzerdefinierten Domänennamens zu Azure Active Directory, um sie zu registrieren. Wiederholen Sie dann den Vorgang. (Dieser Fehler kann auch auftreten, wenn Sie nicht mit den Anmeldeinformationen eines Administrators im Microsoft 365-Mandanten angemeldet sind. Siehe Schritt 2. Melden Sie sich ab, und melden Sie sich erneut mit Administratoranmeldeinformationen an, und wiederholen Sie den Vorgang aus Schritt 3.)

Hinzufügen eines Bereichs

  1. Wählen Sie auf der Seite API verfügbar machen die Option Bereich hinzufügen aus.

    Wählen Sie die Schaltfläche Bereich hinzufügen aus.

    Der Bereich Bereich hinzufügen wird geöffnet.

  2. Geben Sie im Bereich Bereich hinzufügen die Attribute des Bereichs an. Die folgende Tabelle enthält Beispielwerte für und das Outlook-Add-In, das die profileBerechtigungen , openid, Files.ReadWriteund Mail.Read erfordert. Ändern Sie den Text so, dass er den Berechtigungen entspricht, die Ihr Add-In benötigt.

    Feld Beschreibung Werte
    Bereichsname Der Name Ihres Bereichs. Eine gängige Benennungskonvention für Bereiche ist resource.operation.constraint. Für einmaliges Anmelden muss dies auf access_as_userfestgelegt werden.
    Wer kann zustimmen? Bestimmt, ob die Administratoreinwilligung erforderlich ist oder ob Benutzer ohne Administratorgenehmigung zustimmen können. Zum Erlernen des einmaligen Anmeldens und von Beispielen empfehlen wir, dies auf Administratoren und Benutzer festzulegen.

    Wählen Sie Nur Administratoren für Berechtigungen mit höheren Berechtigungen aus.
    Admin Anzeigename der Zustimmung Eine kurze Beschreibung des Zwecks des Bereichs, der nur für Administratoren sichtbar ist. Read/write permissions to user files. Read permissions to user mail and profiles.
    Admin Beschreibung der Einwilligung Eine ausführlichere Beschreibung der Berechtigung, die von dem Bereich gewährt wird, der nur Administratoren angezeigt wird. Allow Office to have read/write permissions to all user files and read permissions to all user mail. Office can call the app's web APIs as the current user.
    Anzeigename der Benutzer einwilligung Eine kurze Beschreibung des Zwecks des Bereichs. Wird benutzern nur angezeigt, wenn Sie Wer kann zustimmen für Administratoren und Benutzer festlegen. Read/write permissions to your files. Read permissions to your mail and profile.
    Beschreibung der Benutzer einwilligung Eine ausführlichere Beschreibung der berechtigung, die vom Bereich gewährt wird. Wird benutzern nur angezeigt, wenn Sie Wer kann zustimmen für Administratoren und Benutzer festlegen. Allow Office to have read/write permissions to your files, and read permissions to your mail and profile.

  3. Legen Sie den Status auf Aktiviert fest, und wählen Sie dann Bereich hinzufügen aus.

    Legen Sie den Status auf aktiviert fest, und wählen Sie die Schaltfläche Bereich hinzufügen aus.

    Der von Ihnen definierte neue Bereich wird im Bereich angezeigt.

    Der neue Bereich, der im Bereich Api verfügbar machen angezeigt wird.

    Hinweis

    Der Domänenteil des von Bereichsname, der direkt unter dem Textfeld angezeigt wird, sollte automatisch mit dem im vorherigen Schritt festgelegten Anwendungs-ID-URI übereinstimmen, mit /access_as_user am Ende angefügt, z. B. api://localhost:6789/c6c1f32b-5e55-4997-881a-753cc1d563b7/access_as_user.

  4. Hinzufügen einer Clientanwendung auswählen.

    Wählen Sie Clientanwendung hinzufügen aus.

    Der Bereich Clientanwendung hinzufügen wird angezeigt.

  5. Geben Sie in der Client-ID ein ea5a67f6-b6f3-4338-b240-c655ddc3cc8e. Mit diesem Wert werden alle Microsoft Office-Anwendungsendpunkte vorab autorisiert. Wenn Sie Office auch vorautorisieren möchten, wenn es innerhalb von Microsoft Teams verwendet wird, fügen Sie 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Microsoft Teams Desktop und Teams mobile) und 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams im Web) hinzu.

    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. Wenn Sie dies tun, lassen Sie 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)

  6. Aktivieren Sie unter Autorisierte Bereiche das api://<fully-qualified-domain-name>/<app-id>/access_as_user Kontrollkästchen.

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

    Der Bereich Clientanwendung hinzufügen.

Hinzufügen von Microsoft Graph-Berechtigungen

  1. Wählen Sie im linken Bereich API-Berechtigungen aus.

    Der Bereich API-Berechtigungen.

    Der Bereich API-Berechtigungen wird geöffnet.

  2. Wählen Sie Berechtigung hinzufügen aus.

    Hinzufügen einer Berechtigung im Bereich

    Der Bereich API-Berechtigungen anfordern wird geöffnet.

  3. Wählen Sie Microsoft Graph aus.

    Der Bereich API-Berechtigungen anfordern mit der Microsoft Graph-Schaltfläche.

  4. Wählen Sie Delegierte Berechtigungen aus.

    Der Bereich API-Berechtigungen anfordern mit der Schaltfläche

  5. Suchen Sie im Suchfeld Berechtigungen auswählen nach den Berechtigungen, die Ihr Add-In benötigt. Für ein Outlook-Add-In können Sie beispielsweise , openid, Files.ReadWriteund Mail.Readverwendenprofile.

    Hinweis

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

  6. Aktivieren Sie das Kontrollkästchen für jede Berechtigung, wie sie angezeigt wird. Beachten Sie, dass die Berechtigungen in der Liste nicht sichtbar bleiben, wenn Sie jede auswählen. Nachdem Sie die Berechtigungen ausgewählt haben, die Ihr Add-In benötigt, wählen Sie Berechtigungen hinzufügen aus.

    Der Bereich API-Berechtigungen anfordern, in dem einige Berechtigungen ausgewählt sind.

  7. Wählen Sie Administratoreinwilligung für [Mandantenname] erteilen aus. Wählen Sie Ja für die angezeigte Bestätigung aus.

Konfigurieren der Zugriffstokenversion

Sie müssen die Zugriffstokenversion definieren, die für Ihre App akzeptabel ist. Diese Konfiguration erfolgt im Azure Active Directory-Anwendungsmanifest.

Definieren der Zugriffstokenversion

Die Version des Zugriffstokens kann sich ändern, wenn Sie einen anderen Kontotyp als Konten in einem Organisationsverzeichnis (Beliebiges Azure AD-Verzeichnis – mehrinstanzenfähig) und persönliche Microsoft-Konten (z. B. Skype, Xbox) ausgewählt haben. Führen Sie die folgenden Schritte aus, um sicherzustellen, dass die Zugriffstokenversion für die Verwendung von Office SSO korrekt ist.

  1. Wählen Sie im linken Bereich Manifest aus.

    Wählen Sie Azure-Manifest aus.

    Das Azure Active Directory-Anwendungsmanifest wird angezeigt.

  2. Geben Sie 2 als Wert für die Eigenschaft accessTokenAcceptedVersion ein.

    Wert für akzeptierte Zugriffstokenversion.

  3. Klicken Sie auf Speichern.

    Im Browser wird eine Meldung angezeigt, die besagt, dass das Manifest erfolgreich aktualisiert wurde.

    Aktualisierte Manifestnachricht.

Herzlichen Glückwunsch! Sie haben die App-Registrierung abgeschlossen, um einmaliges Anmelden für Ihr Office-Add-In zu aktivieren.