SharePoint REST API mit POSTMAN

Bei der Entwicklung von clientseitigen Lösungen, zum Beispiel mit dem SPFx-Framework, müssen oft viele REST API Aufrufe gegen SharePoint abgesetzt werden. Da teilweise die Aufrufsyntax nicht immer klar ist, man im Vorfeld das Rückgabeformat prüfen möchte oder einfach API-Aufrufe im Vorfeld testen möchte, macht es Sinn diese nicht immer immer aus der Entwicklerversion heraus aufzurufen. Gerade bei umfangreichen SPFx-basierten Lösungen dauert teilweise die Transpilierung und Build-Zeit, so dass über diesen Weg Zeit verloren geht. Besser ist es die REST-Aufrufe zum Beispiel separat einzeln auszuführen. Als Tool eignet sich dafür u. a. zum Beispiel Postman sehr gut. Allerdings müssen die meisten REST API-Aufrufe unter SharePoint mit einen Sicherheitstoken ausgeführt werden, dieses muss im Vorfeld erstellt werden. Dazu sind die nachfolgenden Schritte notwendig. Alle Schritte sind auch im zusätzlichen Video zu sehen.

1. Registrieren einer SharePoint APP
   Zunächst muss eine neue SharePoint APP registiert werden. Dazu die folgende URL aufrufen:
   https://[TENANT DOMAIN]/[SITE COLLECTION ODER LEER FÜR ROOT]/_layouts/15/appregnew.aspx
   
   
   Für die beiden Felder Client-ID und geheimer Schlüssel kann jeweils über die Schaltfläche "Generieren" eine neue eindeutige Guid erstellt werden. Im Feld Titel sollte ein aussagekräftiger Name für die APP-Registrierung gewählt werden. Danach können die beiden Einstellungen "localhost" für die App-Domäne und der Weiterleitungs-URI so übernommen werden. Anschließend die Registrierung über "Erstellen" abschließen.
   
   
   Die Werte Client-ID und geheimen Schlüssel notieren. Diese werden später noch benötigt.
2. Die APP benötigte Berechtigungen (Permission) zuweisen
   Der neuen APP müssen nun noch Berechtigungen (Permissions) zugewiesen werden. Dazu den Link:
   https://[TENANT]-admin.sharepoint.com/_layouts/15/appinv.aspx
   aufrufen.
   
   In das Feld "App-ID" die Client-ID aus dem vorherigen Schritt einfügen und danach die Schaltfläche "Nachschlagen" wählen. Wurde die APP erfolgreich gefunden, in das Feld "App-Berechtigungsanforderungs-XML" die benötigten Berechtigungen eintragen:

   <AppPermissionRequests AllowAppOnlyPolicy="true">
   <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
   </AppPermissionRequests>
   

   Danach mit der Schaltfläche "Erstellen" die Berechtigungen anfordern. Den nachfolgenden Dialog entsprechend zustimmen.

   
   
   
3. Ermittlung der Mandanten-ID (Tenant-ID)
   Für weitere Aufrufe muss die Mandaten-ID (Tenant-ID) bekann sein. Diese kann sehr einfach über die URL:
   https://[TENANT]-admin.sharepoint.com/_layouts/15/appprincipals.aspx
   abgerufen werden.
   
   
   
   Die Tenant-ID ist auf der rechten Seite rot umrandet zu finden.
4. Abrufen des Zugriffstoken (Access Token)
   Nachdem all diese Informationen gesammelt wurden und bereitstehen, kann nun final das Zugriffstoken (Access Token) abgerufen werden. Dazu müssen in POSTMAN folgende Informationen eingetragen werden:
   
   
   1. https://accounts.accesscontrol.windows.net/[TENANT-ID]/tokens/OAuth/2/
   Header Werte:
   2. grant_type: client_credentials
   3. client_id: die zuvor erstellte Client-ID@TenantID
   4. client_secret: der zuvor erstellte Client-Secret Schlüssel
   5. resource: 00000003-0000-0ff1-ce00-000000000000/[TENANT].sharepoint.com@[TENANT-ID]
   Nachdem der POST-Request abgesetzt wurde, wird ein Zugriffstoken in der Antwort (Response) zurückgegeben. Dieses kann nun kopiert und für weitere REST-Aufrufe verwendet werden.
5. Verwendung des Access Token
   Das nachstehende Beispiel zeigt, wie der Zugriffstoken (Access Token) für den Abruf von SharePoint Listeninformationen verwendet werden kann. Im Header Feld "Authorization" ist einleitend mit Bearar der Token anzugeben.
   
   
   
   

Möglicher Fehler

Erscheint bei dem REST-Aufruf der Fehler:

{"error":"invalid_request","error_description":"Token type is not allowed."}

Dann muss noch eine Einstellung per PowerShell angepasst werden. Dazu zunächst wieder, wie in meinen Blog zu PowerShell erläutert wurde, eine Verbindung zu dem Office Tenant innerhalb einer PowerShell Sitzung herstellen. Danach dann folgendes Kommando absetzen:

set-spotenant -DisableCustomAppAuthentication $false

Die Einstellung ist bei neuen Mandanten im Standard deaktiviert, da Microsoft das reine Azure AD-App-Modell empfiehlt. Dieses ist neuer, moderner und sicherer. Daher ist für neue Mandanten diese Einstellung standardmäßig deaktiviert. Zum reinen Testen innerhalb eines Test-Mandanten kann die Einstellung aber über den oberen Befehl zurückgesetzt werden.
Weitere Informationen dazu:
Impact of Azure Access Control retirement for SharePoint add-ins