Registrieren von SharePoint-Add-Ins

Artikel
04/08/2023

Registrieren Sie Ihre SharePoint-Add-Ins in Azure ACS mithilfe von Visual Studio, dem Verkäuferdashboard oder einer AppRegNew.aspx-Seite, und rufen Sie Registrierungsinformationen ab.

Wichtig

Azure ACS (Access Control), ein Dienst von Azure Active Directory (Azure AD), wird am 7. November 2018 eingestellt. Diese Deaktivierung hat keinen Einfluss auf das SharePoint-Add-In-Modell, das den Hostnamen https://accounts.accesscontrol.windows.net verwendet, der von der Deaktivierung nicht betroffen ist. Weitere Informationen finden Sie unter Auswirkungen der Deaktivierung von Azure Access Control für SharePoint-Add-Ins.

Damit die Remotekomponenten eines vom Anbieter gehosteten SharePoint-Add-Ins mit SharePoint über OAuth interagieren können, muss das Add-In zunächst beim cloudbasierten Dienst Azure ACS sowie beim SharePoint App-Verwaltungsdienst der Mandantschaft oder der Farm registriert werden. (Dieser wird als „App-Verwaltungsdienst“ bezeichnet, da SharePoint-Add-Ins ursprünglich „Apps für SharePoint“ hießen.)

Hinweis

Dies ist für von SharePoint gehostete Add-Ins nicht erforderlich.

Um das Add-In bei Azure ACS zu registrieren, geben Sie die folgenden Informationen ein:

Eine GUID für das Add-In, die als Client-ID bezeichnet wird.
Ein Kennwort für das Add-In, das als geheimer Clientschlüssel bezeichnet wird.
Ein Anzeigename für das Add-In, der auf der Zustimmungsseite verwendet wird, auf der der Benutzer aufgefordert wird, dem Add-In zu vertrauen.
Eine URL für die Domäne, in der das Remote-Add-In gehostet wird.
Eine Umleitungs-URL.

Nachdem Sie Ihr Add-In registriert haben, weist es eine Add-In-Identität und ist ein Sicherheitsprinzipal; es wird als Add-In-Prinzipal bezeichnet. Wenn Sie das Add-In installieren, können SharePoint-Administratoren Informationen zu diesem bestimmten Add-In-Prinzipal abrufen.

Wenn ein Benutzer zuerst eine Add-In-Berechtigung zum Zugreifen auf SharePoint-Ressourcen gewährt (entweder bei der Installation oder zur Laufzeit, je nachdem, wie die App entworfen wurde), ruft SharePoint Informationen über das Add-In von Azure ACS ab. SharePoint speichert diese Informationen dann in der Datenbank des App-Verwaltungsdiensts des SharePoint-Mandanten oder der SharePoint-Farm. Der geheime Clientschlüssel wird nur bei Azure ACS gespeichert. SharePoint kennt den geheimen Schlüssel nie. Der Inhaltsdatenbankdienst und andere Komponenten, z. B. der Benutzerprofildienst, können den Anzeigenamen sowie andere grundlegende Inforationen zu dem Add-In direkt aus dem freigegebenen App-Verwaltungsdienst abrufen. Weitere Informationen finden Sie unter Abrufen von Informationen zu Add-In-Registrierung und Add-In-Prinzipal in diesem Artikel.

Hinweis

In diesem Artikel wird davon ausgegangen, dass Sie mit den grundlegenden Konzepten und Prinzipien des OAuth 2.0-Frameworks vertraut sind. Weitere Informationen finden Sie unter OAuth.net und Webautorisierungsprotokoll (oauth).

Registrieren Ihres SharePoint-Add-Ins bei Azure ACS

Es gibt drei Möglichkeiten zum Registrieren eines Add-Ins. Welche Methode Sie auswählen, hängt davon ab, an welcher Stelle des Add-In-Entwicklungslebenszyklus Sie sich befinden, sowie von der Architektur Ihres Add-Ins und dem geplanten Markteinführungsverfahren.

Registrierungsmethode	Details
Verwenden Sie Visual Studio und Microsoft Office Developer Tools für Visual Studio zum Erstellen einer temporären Add-In-Identität.	Der Assistent für Office Developer Tools für Visual Studio erstellt eine temporäre Registrierung für Ihr Add-In mit ACS und dem App-Verwaltungsdienst Ihrer SharePoint-Testwebsite. Wenn Sie das Add-In von Visual Studio aus ausführen (F5), wird diese Identität verwendet. Die Tools fügen auch die Client-ID sowie den geheimen Schlüssel in die Dateien „web.config“ und „AppManifest.xml“ ein. Wenn Sie bereit sind, das Add-In zu veröffentlichen, können Sie den Veröffentlichungs-Assistenten von Visual Studio verwenden, um dieses im Verkäuferdashboard zu registrieren. Wenn Sie Ihr SharePoint-Add-In nicht im Office Store vermarkten, verwenden Sie für die Registrierung „AppRegNew.aspx“. (Genaue Schritte finden Sie im nächsten Abschnitt.) Hinweis: Wenn Ihr Add-In die Berechtigung zum dynamischen Zugriff auf SharePoint-Ressourcen zur Laufzeit anstelle der Add-In-Installation anfordert, können Sie Visual Studio nicht zum Erstellen von Add-In-Identitäten verwenden.
Registrieren des Add-Ins über das Verkäuferdashboard.	Wenn Sie das Add-In in mehreren SharePoint-Mandanten oder -Farmen verwenden möchten, verwenden Sie das Verkäuferdashboard, um das Add-In zu registrieren, unabhängig davon, ob Sie es im Office Store vermarkten oder über den Add-In-Katalog verfügbar machen. Bei der Registrierung im Verkäuferdashboard können Sie das Add-In mit einer Architektur für mehrere Mandanten entwerfen, ohne dass Mandanten- oder Farmadministratoren diese separat registrieren müssen. Wenn Sie planen, das Add-In im Office Store zu veröffentlichen, müssen Sie das Verkäuferdashboard zum Registrieren des Add-Ins verwenden. Sie müssen nicht den Store verwenden, um ein Add-In zu veröffentlichen, das beim Verkäuferdashboard registriert wurde. Weitere Informationen finden Sie unter Erstellen oder Aktualisieren von Client-IDs und geheimen Clientschlüsseln im Verkäuferdashboard.
Verwenden der Seite „AppRegNew.aspx“	Verwenden Sie das Formular „AppRegNew" zum Registrieren Ihres SharePoint-Add-Ins, wenn Sie das Add-In nur in einem Mandanten oder in einer Farm verwenden möchten. Wenn Sie zum Beispiel Add-Ins für ein einzelnes Unternehmen erstellen und diese über den Add-In-Katalog des Unternehmens veröffentlichen, können Sie das Add-In über jede AppRegNew.aspx-Seite einer beliebigen Website in einer Mandantschaft oder Farm registrieren. Sie können ein Add-In, das über AppRegNew.aspx registriert wurde, nicht im Office Store veröffentliche. Für Add-Ins, die im Office Store veröffentlicht werden, müssen Sie über das Verkäuferdashboard eine Identität abrufen.

So führen Sie die Registrierung mit „AppRegNew.aspx“ durch

Wechseln Sie mithilfe eines Webbrowsers zu <site collection url>/_layouts/15/AppRegNew.aspx.

AppRegNew-Seitenformular
Geben Sie Werte für die folgenden Formularfelder ein:
- Add-In-ID:. Auch bezeichnet als Client-ID; eine GUID, die generiert (durch Auswählen von Generieren) oder in „AppRegNew.aspx“ eingefügt werden kann. Der Wert muss für jedes Add-In eindeutig sein und muss klein geschrieben werden.
- Geheimer Add-In-Schlüssel. Auch bezeichnet als der geheime Clientschlüssel; es handelt sich um eine verdeckte Zeichenfolge. Diese wird auf der Seite „AppRegNew.aspx“ mithilfe der Schaltfläche Generieren generiert. Nachfolgend finden Sie ein Beispiel für einen geheimen Clientschlüssel: xvVpG0AgVIJfch6ldu4dLUlcZyysmGqBRbpFDu6AfJw=.
  
  Wichtig
  
  Geheime Add-In-Schlüssel laufen ab. Wenn Sie das Add-In im Verkäuferdashboard registrieren, können Sie das Ablaufdatum auf bis zu drei Jahre festlegen. Im Dashboard können Sie auch neue geheime Schlüssel hinzufügen, wenn die alten bald ablaufen. Der neue geheime Schlüssel wird in allen Instanzen des Add-Ins aktiviert. Wenn Sie das Add-in mit „AppRegNew.aspx“ registrieren, läuft der geheime Schlüssel in einem Jahr ab. Weitere Informationen finden Sie unter Austauschen eines ablaufenden geheimen Clientschlüssels in einem SharePoint-Add-In.
- Titel. Ein benutzerfreundlicher Titel; beispielsweise Contoso-Add-In zum Drucken von Fotos. Benutzer werden aufgefordert, dem Add-In die Berechtigungen zu erteilen, die es anfordert, oder diese abzulehnen. Dieser Titel wird als Name des Add-Ins in der Eingabeaufforderung zur Zustimmung angezeigt.
- Add-In-Domäne. Der Hostname der Remotekomponente des SharePoint-Add-Ins. Wenn die Remoteanwendung nicht Port 443 verwendet, muss die Add-In-Domäne auch die Portnummer enthalten. Die Add-In-Domäne muss mit den URL-Bindungen übereinstimmen, die Sie für Ihre Webanwendung verwenden. Fügen Sie in diesen Wert nicht das Protokoll („https:“) oder Zeichen wie „/“ ein. Wenn Ihr Webanwendungshost einen DNS-CNAME-Alias verwendet, verwenden Sie den Alias. Beispiele:
  - www.contoso.com:3333
  - www.fabrikam.com
- Umleitungs-URI:. Der Endpunkt in Ihrer Remoteanwendung oder in Ihrem Dienst, an den ACS einen Authentifizierungscode sendet. Genau genommen verwenden SharePoint-Add-Ins diesen Wert nicht. Der Umleitungs-URI ist für Webanwendungen erforderlich, die außerhalb von SharePoint gestartet werden und die den Authentifizierungscode-Ablauf verwenden, um autorisierten Zugriff auf SharePoint-Daten zu erhalten.
  
  Der Umleitungs-URI wird für echte SharePoint-Add-Ins (die aus SharePoint gestartet werden und den Kontexttokenablauf verwenden) ignoriert.
  
  Bei dem Umleitungs-URI handelt es sich in der Regel um dieselbe Seite, dieselbe Controllermethode oder dieselbe Webdienstmethode, die den Authentifizierungscode von ACS angefordert hat, es kann sich jedoch um einen anderen Endpunkt handeln. Der Endpunkt muss eine Logik aufweisen, die den Autorisierungscode von der HTTP-Antwort abruft, die von ACS gesendet wird, und die diesen Code dann zum Anfordern eines Zugriffs- und Aktualisierungstokens verwendet. Weitere Informationen finden Sie unter Autorisierungscode-OAuth-Fluss für SharePoint-Add-Ins.
  
  Sie müssen in dem Formular auch für echte SharePoint-Add-Ins einen gültigen Wert eingeben, auch wenn dieser nicht verwendet wird. Der Wert muss eine vollständige Endpunkt-URL, einschließlich des Protokolls, sein; dieses muss HTTPS sein. Beispiel:
Wählen Sie im Formular Erstellen aus. Die Seite wird neu geladen und zeigt eine Bestätigung der eingegebenen Werte. Notieren Sie sich diese Wert so, dass Sie sie einfach kopieren und einfügen können. Sie müssen die Werte in die Dateien „web.config“ und „AppManifest.xml“ oder in den Veröffentlichungs-Assistenten von Visual Studio eingeben.

Unabhängig davon, wie Sie Ihr SharePoint-Add-In registrieren, wenn Sie bereit sind, das Add-In für Staging oder Produktion bereitzustellen, müssen Sie Eingeben der Registrierungswerte in die Dateien web.config und AppManifest.xml. Wenn Sie Visual Studio verwenden, übernehmen die Microsoft Office Developer Tools für Visual Studio diese Konfiguration für Sie.

Eingeben der Registrierungswerte in die Dateien „web.config“ und „AppManifest.xml“

Bevor Sie das SharePoint-Add-In verpacken und seine Remotekomponenten bereitstellen, geben Sie einige der Registrierungswerte in die Dateien „AppManifest.xml" und „web.config" ein.

Tipp

Wenn Sie Ihr SharePoint-Add-In mithilfe des Visual Studio-Veröffentlichungs-Assistenten veröffentlichen, werden Sie von Visual Studio während des Veröffentlichungsprozesses zur Eingabe einer Client-ID und eines geheimen Clientschlüssels aufgefordert. Diese Informationen werden für Sie jeweils an der richtigen Stelle eingefügt.

Geben Sie im Visual Studio-Projekt in der Web.config-Datei den Add-In-ID-Wert als ClientId-Wert ein (der den temporären Wert ersetzt, den die Tools eingegeben haben).

Wichtig

Alle Buchstaben in der Client-ID-GUID müssen klein geschrieben sein.

Es folgt ein Beispiel.
```
<appSettings>
  <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
  .  .  .
</appSettings>
```
Geben Sie den Wert für den geheimen Add-In-Schlüssel als ClientSecret-Wert ein (der den temporären Wert ersetzt, den die Tools eingegeben haben).

Nachfolgend sehen Sie ein Beispiel für die Verwendung der Werte in der Datei „Web.config“ einer Webanwendung.
```
<appSettings>
  <add key="ClientId" value="a044e184-7de2-4d05-aacf-52118008c44e " />
  <add key="ClientSecret" value="l0z/8TzWN0yQBzMBSEZtYts2Vt3Eo/oE3rfCdPaogKQ= " />
</appSettings>
```
Geben Sie im Visual Studio-Projekt in der Datei „AppManifest.xml“ den Add-In-ID-Wert als ClientIdin Kleinbuchstaben ein.

Hinweis

Das Add-In-Manifest gilt nicht für Webanwendungen, die spontan die Berechtigungen zum Zugreifen auf SharePoint-Ressourcen anfordern. Dabei handelt es sich nicht um echte „SharePoint-Add-Ins“. Sie sind nicht in SharePoint installiert und weisen kein Add-In-Manifest auf. Weitere Informationen finden Sie unter Autorisierungscode-OAuth-Fluss für SharePoint-Add-Ins.

Das folgende Beispiel veranschaulicht die Verwendung des ClientId-Werts in der Datei „AppManifest.xml".
```
<AppPrincipal>
  <RemoteWebApplication ClientId="a044e184-7de2-4d05-aacf-52118008c44e"/>
</AppPrincipal>
```
Die Office Developer Tools für Visual Studio verwenden das Token ~remoteAppUrl im StartPage-Element. (Zum Beispiel <StartPage>~remoteAppUrl/Pages/Default.aspx?{StandardTokens}</StartPage>.) Dieses Token wird in die URL der Remotekomponenten aufgelöst, wenn Sie den Veröffentlichungs-Assistenten in Visual Studio verwenden. Wenn Sie den Assistenten nicht verwenden (oder wenn Sie den Assistenten verwenden, die Remotekomponenten aber in Azure veröffentlichen), müssen Sie das Token manuell durch den Wert der Add-In-Domäne ersetzen, der beim Registrieren des Add-Ins verwendet wird. Es muss genau derselbe Wert, einschließlich Portnummer (falls vorhanden), sein, es sei denn, Sie schließen auch das HTTPS-Protokoll mit ein. Es folgt ein Beispiel.
```
<StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
```
Ziehen Sie die Verwendung desselben Werts für das Title-Element in der AppManifest.xml-Datei in Betracht, den Sie für das Feld Titel in AppRegNew.aspx verwendet haben. Der Wert für das Title-Element ist der Name des Add-Ins, den Benutzer nach der Installation des Add-Ins sehen. Für Benutzer ist es möglicherweise verwirrend, wenn das Add-In im Zustimmungsdialogfeld einen anderen Namen hat als in der SharePoint-Benutzeroberfläche.

Nachfolgend ist ein Beispiel für diese Werte im App-Manifest aufgeführt.
```
<Properties>
  <Title>Contoso photo printing app</Title>
  <StartPage>https://www.contoso.com/Pages/Default.aspx?{StandardTokens}</StartPage>
</Properties>
```

Verwenden der Umleitungs-URL in einem Add-In, das Berechtigungen im laufenden Betrieb anfordert

Wenn Ihre Webanwendung außerhalb von SharePoint gestartet wird (und also kein echtes SharePoint-Add-In ist), muss diese so konzipiert sein, dass sie zur Laufzeit nach Berechtigungen von SharePoint fragt. Sie muss Code umfassen, der den Umleitungs-URI, zusammen mit anderen Informationen, verwendet, um ein Zugriffstoken von ACS abzurufen. Suchen Sie die Stelle, an der dieser URI festgelegt ist, und verwenden Sie genau den Wert, den Sie für das Feld Umleitungs-URI auf AppRegNew.aspx oder im Verkäuferdashboard verwendet haben. Dies kann in einer Codedatei oder in einer Konfigurationsdatei sein.

Abrufen von Informationen zu Add-In-Registrierung und Add-In-Prinzipal

Sie können die Informationen zur Add-In-Registrierung und zum Add-In-Prinzipal für die Add-Ins abrufen, die Sie in SharePoint installiert oder registriert haben.

Um nach Registrierungsinformationen für ein Add-In suchen, das Sie registriert haben, wechseln Sie zu http://<SharePointWebsite>/_layouts/15/AppInv.aspx.

Zum Nachschlagen benötigen Sie die Client-ID (auch als Add-In-ID bezeichnet), die Sie bei der Registrierung des Add-Ins verwendet haben. Der Nachschlagevorgang gibt für die entsprechende Client-ID die folgenden Informationen zurück:

Titel
Add-In-Domäne
Umleitungs-URL (dieselbe wie der Umleitungs-URI)

Der Nachschlagevorgang gibt nicht den Wert des geheimen Add-In-Schlüssels zurück.

Um eine Liste der registrierten Add-In-Prinzipale anzuzeigen, wechseln Sie zu: http://<SharePointWebsite>/_layouts/15/AppPrincipals.aspx.

Share via