Yavuz Bogazci
How to: Installation einer OnPremises Umgebung für die Evaluierung des Microsoft SharePoint 2016 Development & BI-Stacks (mit Microsoft SQL Server 2017)

Part 8 – Konfigurieren des lokalen IIS für die Verwendung von Low-Trust Add-ins in Verbindung mit SharePoint Online

Als nächstes steht die Einrichtung und Vorbereitung des lokalen IIS für die Verwendung mit sogenannten Microsoft SharePoint Provider Hosted Low Trust Add-ins. Es gibt grundsätzlich drei unterschiedliche Authorisierungssysteme für Microsoft SharePoint Add-ins:

  • Low Trust
  • High Trust
  • Cross-domain library

Low Trust bedeutet, dass ein Microsoft SharePoint Provider Hosted Add-in im Microsoft Azure Access Control Service (ACS) registriert wird und anschließend fungiert dieser als ein Authorisierungs-Server in einer OAuth 2.0 Transaktion. Ein Add-in muss im Microsoft Azure Access Control Service (ACS) als auch im App Management Service der Microsoft SharePoint Farm oder SharePoint Online mit Hilfe der Seite _Layouts\15\AppRegNew.aspx registriert werden.

High Trust bedeutet, dass die Vertrauensstellung zwischen dem Add-in und Microsoft SharePoint mit Hilfe eines Zertifikats geschaffen wird. Ein High Trust Add-in ist “high-trust”, da sie jedwede User-Identität annehmen und dann diese dem Access Token hinzufügt. Ein High Trust Add-in kann nicht unter Microsoft SharePoint Online genutzt werden und ist auch nicht zu verwechseln mit einer Full Trust Lösung!

Cross-domain library kommt zum Einsatz, wenn die Business-Logik der Anwendung mit Javascript umgesetzt wurde. Wenn Domain übergreifende Calls (zum Beispiel ein Aufruf aus einer Remote Web Domain zu einer Add-in Web Domain) erforderlich sind um Daten aus SharePoint Listen etc. abzurufen, bietet die CDL ein sicheres System um diese Einschränkung zu umgehen. Eine Verwendung von OAuth Tokens ist entsprechend nicht erforderlich.

Die einzelnen erforderlichen Schritte um den lokalen IIS Low Trust ready zu machen als auch eine beispielhafte Implementierung eines Low Trust Add-ins, werden in diesem Beitrag detailliert und Schritt für Schritt erklärt.

Die Serie besteht aus folgenden Teilen:

Part 1 – Installation und Konfiguration Microsoft Azure VM mit Microsoft Windows Server 2012R2

Part 2 – Installation und Konfiguration von Microsoft SQL Server 2017 (Datenbankmodul)

Part 3 – Installation und Konfiguration von Microsoft SharePoint 2016

Part 4 – Installation und Konfiguration Microsoft SharePoint 2016 Managed Metadata Service

Part 5 – Installation und Konfiguration der Microsoft SharePoint 2016 User Profile Service und MySites

Part 6 – Installation und Konfiguration des Microsoft SharePoint 2016 Search Service

Part 7 – Konfiguration der SharePoint-Umgebung für Apps (Add-ins)

Part 8 – Konfigurieren des lokalen IIS für die Verwendung von Low-Trust Add-ins in Verbindung mit SharePoint Online

Part 9 – Konfigurieren der On-Premises Umgebung für Verwendung von Low-Trust Authentifizierung

Part 10 – Low Trust AddIn und Microsoft Azure WebSite als AppWeb

Part 11 – Installation Microsoft SharePoint 2016 Sprachpaket Deutsch

Part 12 – Installation und Konfiguration von Microsoft Power BI Report Server

Part 13 – Installation und Konfiguration von Microsoft Office Online Server for SharePoint 2016 (OOS)

Folgende Schritte werden wir im Detail durchführen um Low Trust Add-ins einzurichten und zu entwickeln:

  • Eine App Domain im DNS Server einrichten
  • Eine Website im IIS anlegen
  • Ein Self-signed Certificate im IIS erstellen und installieren
  • Eine Microsoft SharePoint Online Developer SiteCollection anlegen
  • Einen minimalen Low-Trust Add-in entwickeln
  • Eine Application im IIS anlegen
  • Ein Add-in in Microsoft SharePoint Online registrieren
  • Ein Low-Trust Add-in deployen

Eine App Domain im DNS Server einrichten

Apps haben ihre eigene isolierte Url. Diese sind getrennt von der Url der Website auf die App verwendet wird. Die Verwendung eines anderen Domain Namens für Apps verhindert Cross-Site-Scripting zwischen Apps und SharePoint. Die App-Url ist nach folgendem Muster aufgebaut:

http(s):// [App-Präfix] [App-Hash] . [App-Domain] / [relative Website Url] / [App-Name]

Um eine App-Domain einzurichten klicken wir auf Start > Administrative Tools > DNS. Im DNS Manager klicken wir mit der rechten Maustaste auf den Punkt Forward Lookup Zone unterhalb unseres Server-Namens (OneSP2016) und wählen im Kontext-Menü auf den Punkt New Zone … .

Es öffnet sich daraufhin der New Zone Wizard. Mit Next wechseln wir zum Zone Type Dialog.

Im Zone Type Dialog wählen wir Primary Zone aus und checken den Punkt Store the zone in Active Directory

Mit Next gelangen wir zum Active Directory Zone Replication Scope Dialog. Hier wählen wir To all DNS servers running on domain controllers in this domain: lab.com aus und machen mit Next weiter.

Im Dialog Zone Name geben wir die App Domain an. In meinem Fall custombi-apps.com und bestätigen die Eingabe mit Next.

Im nächsten Dialog Dynamic Update wählen wir den Punkt Allow only secure dynamic updates (recommended for Active Directory) aus und klicken auf Next.

Damit wäre die Forward Lookup Zone Einrichtung abgeschlossen. Mit Finish schließen wir die Konfiguration ab.

Im nächsten Schritt müssen wir für die App Domain einen neuen CNAME Wildcard Alias anlegen. Dazu klicken mit der rechten Maustaste auf die neue Forward Lookup Zone und wählen aus dem Kontextmenü New Alias (CNAME) aus.

Im Fenster New Record Source geben wir als Alias name ein * an und wählen oder geben beim Fully qualified domain name (FDQN) for target host den FDQN an oder wählen diesen via Browse aus. In meinem Fall ist es der Rechnername (blogsp2016).domain (lab.com), also blogsp2016.lab.com.

Damit ist die Einrichtung der App Domain nun vollständig und abgeschlossen. Im nächsten Schritt legen wir die Website unter der die Apps gehostet werden sollen im IIS an.

Eine Website im IIS anlegen

Dazu öffnen wir den Internet Information Services (IIS) Mananger. Klicken in der linken Navigation mit der rechten Maustaste auf den Servernamen und wählen im Kontextmenü den Punkt Add Website.

Im Dialog Add Website geben wir einen Namen für die Website an (in meinem Fall apps) und wählen den Pfad. Anschließend geben wir einen Hostnamen an (www.custombi-apps.com) und bestätigen mit OK.

Entsprechend unserer Auswahl im Add Website Dialog wurde auch ein entsprechender Application Pool für diese Website angelegt:

Ein Self-signed Certificate im IIS erstellen und installieren

Nun müssen wir ein Zertifikat erstellen und einrichten. Dazu reicht es aus, wenn wir ein Self Signed Certificate verwenden. Hierzu Klicken wir im IIS Manager auf den Servernamen und wählen aus dem mittleren Bereich den Punkt Server Certificates aus.

Mit einem Doppelklick auf Server Certificates öffnen wir diesen und klicken nun aus der rechten Navigation auf den Punkt Create Self-Signed Certificate aus.

Im Dialog Create Self-Signed Certificate geben wir dem Zertifikat einen Namen und wählen unter Select a certificate store for the new certificate > Personal aus und bestätigen mit OK.

Unter Server Certificates erscheint nun unser Zertifikat. Mit einem Doppenklick auf das Zertifikat öffnen wir das Certificate Dialog mit den Zertifikat-Details.

Im Certificate Dialog wechseln wir zum Reiter Details und klicken auf die Schaltfläche Copy to File.

Es öffnet sich der Certificate Export Wizard. Die Startseite bestätigen wir mit einem Klick auf Next.

Bei Export Private Key wählen wir No, do not export the private key aus und klicken auf Next.

Im Dialog Export File Format wählen wir DER encoded binary X.509 (.CER) aus und klicken wieder auf Next.

Nun geben wir ein Ziel an, an der das Zertifikat exportiert werden soll und klicken auf Next.

Im letzten Schritt wird eine Zusammenfassung der Einstellungen gezeigt und diesen Dialog bestätigen wir erneut mit Next.

Mit The export was successful wird der Vorgang abgeschlossen und das Zertifikat sollte nun an das von uns ausgewählte Ziel exportiert worden sein.

Dazu öffnen wir den Windows Explorer und wechseln in das Verzeichnis, was wir als Export-Ziel zuvor angegeben hatten. Klicken anschließend mit der rechten Maustaste auf das Zertifikat und wählen im Kontextmenü den Punkt Install Certificate aus.

Im Dialog Certificate Import Wizard wählen wir unter Store Location den Punkt Local Machine aus und klicken auf Next.

Im Dialog Certificate Store wählen wir den Punkt Place all certificates in the following store aus und klicken anschließend auf Browse… .

Im Dialog Select Certificate Store wählen wir Trusted Root Certificate Authorities aus und bestätigen die Auswahl mit OK.

Anschließend bestätigen wir den Dialog mit Next.

Im letzten Schritt wird die Auswahl zusammengefasst und wir bestätigen diesen Dialog mit Finish.

Nach einem erfolgreich Import wird dieser Vorgang mit der Nachricht The import was successful bestätigt.

Nun müssen wir unsere zuvor erstellte Website so konfigurieren, dass diese per HTTPS aufrufbar ist, also wir eine gesicherte Verbindung haben. Dazu öffnen wir erneut den IIS Manager und wählen die zuvor erstellte Website apps mit einem Klick auf diesen aus. Danach klicken wir in der rechten Navigation auf den Punkt Bindings.

Im Dialog Site Bindings klicken wir auf Add… um ein weiteres Binding hinzuzufügen.

Im Dialog Add Site Binding wählen wir als Type > https aus, bei IP address > All unassigned und Port > 443. Als Hostname verwenden wir weiterhin die von uns zuvor festgelegte App Domain (custombi-apps.com). Aus der Dropdown-Liste SSL certificates wählen wir das eben erstellt Zertifikat aus und bestätigen die Einstellungen mit OK.

Nachdem das neue Binding erfolgreich erstellt wurde, wird es im Dialog Site Bindings aufgelistet. Mit Close können wir diesen Dialog schließen.

Eine Microsoft SharePoint Online Developer SiteCollection anlegen

Bevor wir ein simples Low Trust Add-in erstellen erstellen wir eine Developer SiteCollection auf unserem SharePoint an. Dazu loggen wir via http://portal.office.com in unseren Tenant ein und öffnen Administrator.

Im Admin center wählen wir unter Admin center > SharePoint aus um das SharePoint Admin Center zu öffnen.

Im SharePoint Admin Center wählen wir den Punkt Websitesammlungen aus der linken Navigation und klicken auf Neu > Private Websitesammlung im Ribbon Websitesammlungen.

Wir erstellen eine neue SiteCollection und geben einen gewünschten Titel und eine beliebige Adresse an. Als Vorlage wählen wir hier Entwicklerwebsite oder im englischen Developer Site aus. Man kann als Entwickler auch Add-ins auf “normalen” SiteCollections entwickeln, aber dann sollte man das App Sideloading auf diesen aktivieren. Auf einer Developer SiteCollection kann man Apps direkt deployen ohne vorher im zentralen App-Catalog die App deployen zu müssen. Das geschieht mit dem sogenannten SiteCollection App-Catalog Apps in Test. Zudem kann man remote direkt aus dem Visual Studio heraus deployen und debuggen. Falls man keine Developer SiteCollection hat oder auf einer “normalen” SiteCollection entwickeln und testen möchte, so muss man das App SideLoading aktivieren. Sehr gute Artikel hierzu sind Enable app SideLoading in your non-developer site collection und Overview of SharePoint 2013 Developer Site Template.

Als Sidenote möchte ich hier noch die Enable- und DisableSideLoading Skripte posten, falls die oben genannten Links nicht mehr zu erreichen sein sollten. Hier das EnableSideLoading-Skript:

Und hier das DisableSideLoading-Skript:

So, nun aber die SiteCollection anlegen und mit OK bestätigen.

Einen minimalen Low-Trust Add-in entwickeln

Um unsere Low-Trust Einrichtung auch mit einem echten Low-Trust Add-in testen zu können, erstellen wir ein sehr simples Low-Trust Add-in. Ich habe als Beispiel auch den von Microsoft im Get started creating provider-hosted SharePoint Add-ins Beitrag bereitgestellten Code verwendet, nur hat sich hier ein kleiner Fehler bei Microsoft eingeschlichen! Ich habe trotzdem dann die einzelnen Schritte hier inklusive Code dokumentiert.

Im ersten Schritt öffnen wir Microsoft Visual Studio (ich verwende die Version 2017 – 15.5.6).

Erstellen ein neues Projekt vom Typ SharePoint Add-in unter Visual C# > Office/SharePoint > Add-ins.

Im Dialog New SharePoint Add-in müssen wir nun die Adresse der zuvor erstellten Developer SiteCollection oder aber einer anderen SiteCollection auf der wir die Anwendung installieren und testen möchten angeben. Bei How do you want to host your SharePoint Add-in wählen wir den Punkt Provider-hosted aus, da wir ein Provider-hosted Low-Trust Add-in entwickeln werden. Klicken anschließend auf Next.

Bei Specify the target SharePoint version sollte automatisch SharePoint Online ausgewählt sein. Falls nicht, wählen wir SharePoint Online aus und klicken auf Next.

Als project type wählen wir ASP.NET Web Forms Application aus und klicken auf Next.

Als Authentifizierungsmethode wählen wir Use Windows Azure Access Control Service (for SharePoint cloud add-ins) aus und klicken auf Finish.

Auf der Seite Default.aspx geben wir folgenden Code zwischen <Div> und </Div> innerhalb von <form id=”form1″ runat=”server”> ein:

Und im Code-Behind der Default.aspx Datei können wir den gesamten Code-Block innerhalb der Klasse mit dem folgenden ersetzen:

Anschließend doppelklicken wir auf die Datei AppManifest.xml und wählen den Reiter Permissions aus. Unter Scope wählen wir Site Collection aus, als PermissionRead.

Eine Application im IIS anlegen

Wir haben zwar bisher die Website im IIS angelegt aber noch keine Application. Dazu öffnen wir wieder den IIS Manager und klicken mit der rechten Maustaste auf die zuvor angelegt Website und wählen im Kontextmenü Add Application… aus.

Im Dialog Add Application geben wir einen Alias für die diesen an sowie einen Ordner in welchem die Application deployed werden kann. Klicken danach auf OK.

Nachdem die Application erfolgreich angelegt wurde, erscheint sie in der linken Navigation unterhalb unserer Website.

Ein Add-in in Microsoft SharePoint Online registrieren

Langsam nähern wir uns dem Ende und müssen als nächstes ein Add-in in Microsoft SharePoint Online registrieren. Dazu rufen wir die folgende Url auf:

http://mydomain.sharepoint.com/sites/app-dev/_layouts/15/appregnew.aspx

Hier klicken wir auf beide Generieren Buttons, so dass eine GUID für die Client-ID und ein geheimer Schlüssel erzeugt werden. Wir geben noch einen Titel ein und nun müssen wir folgende sehr wichtige Eingaben tätigen, denn falls diese nicht korrekt eingegeben werden, so wird das Add-in niemals laufen.

Die App-Domäne ist unsere App-Domäne die wir im ersten Schritt erstellt hatten. Falls jemand auf die Idee kam und eine App-Domäne als Sub-Domäne angelegt hat zum Beispiel apphost.custombi-apps.com, dann muss hier auch genau diese (apphost.custombi-apps.com) eingetragen werden und nicht custombi-apps.com. Wenn man sich an die Schritte gehalten hat und nur eine “normale” Domäne hat, dann wird hier die Domäne OHNE www. angegeben. In meinem Fall custombi-apps.com. Danach klicken wir auf Erstellen und das Add-in wird erstellt und eine Zusammenfassung wird angezeigt.

In unserem Low-Trust Add-in müssen wir in der web.config die Client-ID und den Client-Secret eintragen. Dazu öffnen wir die web.config und tragen diese Werte innerhalb vom Abschnitt appSettings in die entsprechenden Keys.

Ein Low-Trust Add-in deployen

Das Provider-hosted Low-Trust Add-in besteht aus zwei Komponenten:

  • Add-in
  • WebApplication

Zuerst deployen wir die WebApplication. Dazu klicken wir innerhalb von Microsoft Visual Studio mit der rechten Maustaste auf das WebApplication-Projekt und wählen im Kontextmenü Publish… .

Im Publish Dialog wählen wir Folder aus und wählen unter Choose a folder den Order der WebApplication (nicht der Website!), welchen wir im IIS zuvor erstellt haben. Anschließend klicken wir auf Publish und die Anwendung wir compiliert und in das ausgewählte Verzeichnis deployed.

Als nächstes müssen wir das Add-in deployen. Dazu klicken wir mit der rechten Maustaste auf das Add-in Projekt und wählen im Kontextmenü den Punkt Publish… .

Im Publish your add-in Dialog klicken wir auf Package the add-in.

In diesem Dialog müssen wir nun die Adresse der lokalen WebApplication eingeben die wir zuvor erstellt haben! Nicht die der Microsoft SharePoint Online Developer SiteCollection! Und noch die Client-ID eintragen die wir eben erzeugt haben und dann auf Finish klicken. Das Add-in wird kompiliert und das Add-in Package erzeugt. Das Package befindet sich unter dem Projekt-Ordern > bin\Release\app.publish\1.0.0.0 oder Versionsnummer x.x.x.x. Es ist wichtig, dass man nach jeder Änderung am Add-in (nicht an den Remote-Komponenten!) die Versionsnummer im Add-in Projekt innerhalb der Datei AppManifest.xml erhöht, da man ein Add-in mit derselben Versionsnummer nicht überschreiben kann. Ein guter Artikel hierzu ist Update SharePoint Add-ins.

Aus dem Explorer muss nun das Add-in in den Microsoft SharePoint Online App-Catalog hochgeladen werden, den wir in den Beiträgen zuvor erstellt haben. Unter Apps für SharePoint klicken wir auf Neu.

Im Dialog Dokument hochladen wählen wir das erzeugte Add-in Package aus und klicken auf OK.

Nachdem diese erfolgreich hochgeladen wurde, erscheint unser Add-in in der Liste der Apps für SharePoint.

Anschließend gehen wir zu unserer Developer SiteCollection und wählen aus den Office 365-Einstellungen denk Punkt App hinzufügen.

In der App-Auflistung wählen wir unser Low-Trust Add-in aus (in diesem Fall SharePointAddin1-LowTrustApp) .

Im Dialog Vertrauen Sie SharePoint Low Trust Test App? wählen wir Vetrauen aus.

Nach einiger Zeit wird die App erfolgreich hinzugefügt und kann mit einem Klick auf das Icon gestartet werden. Der User wird dann zu dem Add-in weitergeleitet.

Ohne Fehler wir die Startseite unseres Add-ins aufgerufen und mit einem Klick auf Populate Data sollten SharePoint Daten abgerufen werden können (wenn alles richtig gemacht wurde 🙂 ) …

Und voila! Alles hat funktioniert und unser Low-Trust Add-in kann Daten vom SharePoint abrufen!

Referenzen

Create high-trust SharePoint Add-ins

Creating SharePoint Add-ins that use low-trust authorization

Access SharePoint data with the Cross Domain JavaScript Library

Add Certificate to the SharePoint Trusted Root Certificate Authority

Debugging errors in SharePoint add-in (app) development