Freigeben über

Veröffentlichen eines Add-Ins, das die Administratoreinwilligung für Microsoft Graph-Bereiche erfordert

  • Artikel

In diesem Artikel erfahren Sie, wie Sie Updates für ein Office-Add-In veröffentlichen, um Microsoft Graph-Bereiche zu verwenden und die Zustimmung des Administrators zu benötigen. Dies ist ein gängiges Szenario, wenn Sie Ihr Outlook-Add-In von Legacytoken Exchange Online in die Verwendung der Microsoft-Authentifizierungsbibliothek (MSAL) mit geschachtelter App-Authentifizierung (NAA) und Entra-ID-Token mit Microsoft Graph-APIs verschoben haben.

Um Updates zu veröffentlichen, müssen drei Punkte berücksichtigt werden.

  1. Bereitstellen von Änderungen, die im Add-In-Code vorgenommen wurden, auf Ihrem Webserver
  2. Hier erfahren Sie, wie Sie die Administratoreinwilligung für die Microsoft Graph-Bereiche einholen.
  3. Bereitstellen von Updates in Ihrem Manifest.

Bereitstellen von Updates für Ihren Add-In-Code

Nachdem Sie Ihren Add-In-Code aktualisiert und getestet haben, müssen Sie sie auf Ihrem Webserver bereitstellen. Befolgen Sie Ihren eigenen Aktualisierungsprozess (z. B. Staging und Produktion). Nach der Bereitstellung sehen alle Benutzer Ihres Add-Ins die Änderungen und beginnen mit der Verwendung des aktualisierten Add-In-Codes. Administratoren oder Benutzer müssen keine Aktionen ergreifen, um die Updates anzuzeigen.

Alle microsoft Graph-Bereiche, die von Ihrem Add-In verwendet werden, erfordern die Zustimmung des Benutzers oder des Administrators eines Mandanten. Wenn der Administrator nicht zustimmt, wird der Benutzer aufgefordert, seine Zustimmung zu erteilen, wenn Ihr Add-In ein Zugriffstoken über MSAL anfordert. Um eine optimale Benutzererfahrung zu erzielen, vermeiden Sie es, Benutzer überhaupt zur Zustimmung aufzufordern. Bitten Sie stattdessen Ihren Administrator, die Zustimmung für den gesamten Mandanten zu erteilen.

Es gibt zwei Möglichkeiten, die Administratoreinwilligung einzuholen: Verwenden Sie einen Administratoreinwilligungs-URI oder das einheitliche Manifest.

Sie können die Administratoreinwilligung einholen, indem Sie einen URI für die Administratoreinwilligung angeben. Es stellt einen Link bereit, den ein Administrator auswählen kann. In einem Dialogfeld werden sie aufgefordert, sich mit Administratoranmeldeinformationen anzumelden und den Microsoft Graph-Bereichen zuzustimmen, die Ihr Add-In benötigt.

Verwenden Sie zum Erstellen des Administrator-URI das folgende Muster.

https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id={client_id}&scope={scopes}&redirect_uri={redirect_uri}

Dabei gilt:

  • client_id: Die ID Ihrer App-Registrierung.
  • scope: Jeder Bereich (z. B. Microsoft Graph-Bereiche) erfordert die Administratoreinwilligung unter Verwendung des Leerzeichens als Trennzeichen. Da die Microsoft-Authentifizierungsbibliothek (MSAL) immer eine ID und ein Aktualisierungstoken anfordert, sollten Sie immer die openidBereiche , profileund offline_access einschließen. Diese werden standardmäßig von MSAL angefordert, auch wenn das Add-In sie nicht anfordert.
  • redirect_uri: Eine Umleitungsseite für den Zeitpunkt, an dem die Zustimmung abgeschlossen ist. Die Microsoft Identity Platform werden auf diese Seite umgeleitet, nachdem ein Administrator zugestimmt hat. Der Umleitungsseite wird eine ERFOLGS- oder FEHLER-JSON-Nachricht gesendet, wie in Admin Zustimmung für die Microsoft Identity Platform angegeben. Auf der Seite können Sie die Zustimmung status dem Administrator angeben sowie weitere Informationen oder nächste Schritte zu Ihrem Add-In bereitstellen.

Wichtig

Die Umleitungsseite muss der Liste der Spa-Umleitungen (Single-Page Application) in Ihrer App-Registrierung zusammen mit der brk-multihub Umleitung hinzugefügt werden, andernfalls schlägt der Administratoreinwilligungs-URI fehl.

Das folgende Beispiel für einen Administrator-URI zeigt, wie Sie die openidBereiche , profile, offline_accessuser.read und files.read angeben und zu einer Seite auf Ihrem Webserver mit dem Namen consentRedirect.htmlumleiten.

https://login.microsoftonline.com/organizations/v2.0/adminconsent?client_id=63e62b68-c5c7-48f9-82bf-8c41d5637b49&scope=offline_access openid profile user.read files.read&redirect_uri=https://localhost:3000/consentRedirect.html

Hinweis

Wenn der Ressourcenbezeichner im scope-Parameter ausgelassen wird, wird davon ausgegangen, dass es sich bei der Ressource um Microsoft Graph handelt. User.Read entspricht beispielsweise https://graph.microsoft.com/User.Read.

Sie können auch die Administratoreinwilligung als automatischen Teil des Bereitstellungsworkflows einholen, wenn Ihr Add-In bereitgestellt wird. Fügen Sie dazu die webApplicationInfo -Eigenschaft ihrem einheitlichen Manifest hinzu. Anschließend stellt der Administrator das aktualisierte Manifest bereit, entweder über eine zentrale Bereitstellung oder über ein Update über Microsoft AppSource. Wenn der Administrator das aktualisierte Manifest bereitstellt, wird er automatisch aufgefordert, den vom Add-In erforderlichen Bereichen zuzustimmen. Wenn sie nicht zustimmen, wird das aktualisierte Add-In nicht bereitgestellt.

Hinzufügen von Graphbereichen zur App-Registrierung

Wenn der Administrator das aktualisierte Manifest Ihres Add-Ins bereitstellt, liest der Zustimmungsprozess Ihre App-Registrierung, für welche Bereiche der Administrator die Zustimmung anfordern soll. Stellen Sie sicher, dass Sie alle Berechtigungen hinzufügen, die Ihr Add-In benötigt, indem Sie die folgenden Schritte ausführen.

  1. Melden Sie sich beim Azure-Portal an, und öffnen Sie Ihre App-Registrierung.

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

    Der Bereich API-Berechtigungen.

    Der Bereich API-Berechtigungen wird geöffnet.

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

    Hinzufügen einer Berechtigung im Bereich

    Der Bereich API-Berechtigungen anfordern wird geöffnet.

  4. Wählen Sie Microsoft Graph aus.

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

  5. Wählen Sie Delegierte Berechtigungen aus.

    Der Bereich API-Berechtigungen anfordern mit der Schaltfläche

  6. 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.

  7. 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.

Hinzufügen der webApplicationInfo-Eigenschaft

Um die Administratoreinwilligung als Teil des Bereitstellungsworkflows einzuholen, fügen Sie die webApplicationInfo -Eigenschaft Ihrem einheitlichen Manifest hinzu. Legen Sie die id -Eigenschaft auf Ihre App-Registrierungs-ID fest. Legen Sie die resource -Eigenschaft auf den Wert Ihrer Domäne fest. Das folgende Beispiel zeigt die webApplicationInfo -Eigenschaft für eine App-Registrierung für contoso.com.

    "webApplicationInfo": {
        "id": "a92ace55-9daf-47bc-84e9-065e9a6e70e3",
        "resource": "https://contoso.com"
    },

Bereitstellen des aktualisierten Manifests

Wenn Sie Ihr Add-In über Microsoft AppSource bereitgestellt haben, müssen Sie Ihr aktualisiertes einheitliches Manifest zur Genehmigung übermitteln. Weitere Informationen finden Sie unter Häufig gestellte Fragen zur Microsoft AppSource-Übermittlung.

Wenn Sie Ihr Add-In bereitgestellt haben, indem Sie das Manifest für Administratoren für die zentrale Bereitstellung bereitstellen, müssen Sie Administratoren ein aktualisiertes App-Paket bereitstellen, das das aktualisierte Manifest enthält.

Verwandte Inhalte