Nutzen von mit Azure AD gesicherten Unternehmens-APIs in SharePoint-Framework

In diesem Artikel wird veranschaulicht, wie Sie eine Verbindung mit einer Unternehmens-API, die mit Azure Active Directory geschützt ist, aus einer SharePoint-Framework-Lösung herstellen. Er umfasst das Erstellen und Sichern der API ebenso wie das Erstellen der SharePoint-Framework-Lösung.

Erstellen einer mit Azure AD gesicherten Unternehmens-API

Beginnen Sie mit der Erstellung einer Unternehmens-API, die mit Azure Active Directory gesichert ist. Während aus der Sicht von SharePoint-Framework keine Einschränkungen für die Implementierungsart der API bestehen, erstellen Sie die API in diesem Lernprogramm mit Azure Functions und schützen sie mithilfe der Azure App Service-Authentifizierung.

Während in Ihrer Organisation wahrscheinlich bereits bestimmte APIs ihre Anwendungen verfügbar machen, soll Ihnen dieser Abschnitt einen vollständigen Überblick über die Implementierungs- und Konfigurationsschritte geben.

Erstellen einer Azure-Funktion

Erstellen Sie im Azure-Portal eine neue Funktionen-App.

Weitere Informationen zum Erstellen von Function-Apps in Azure finden Sie im Hilfeartikel Erstellen einer Funktionen-App im Azure-Portal.

In der Function-App erstellen Sie eine neue, über HTTP ausgelöste Funktion. In diesem Beispiel werden Sie die Funktion mithilfe von C# erstellen, im Allgemeinen gibt es aber keine Beschränkung im Hinblick auf die zu verwendende Programmiersprache.

Klicken Sie in der Funktionen-App auf die Schaltfläche Neue Funktion:

Wählen Sie aus der Liste der Vorlagen HTTP-Trigger aus:

Geben Sie im Bereich „Neue Funktion“ den Funktionsnamen an, legen Sie dieAutorisierungsstufe als Anonym fest und klicken Sie auf die Schaltfläche Erstellen:

Azure Functions kann auf verschiedene Arten gesichert werden. Da Sie die Funktion mit Azure AD sichern möchten, statt sie an sich zu sichern, werden Sie die zugrunde liegende Function-App sichern. Daher geben Sie zu diesem Zeitpunkt an, dass nicht die Funktion selbst gesichert werden soll. Auf die Funktionen-App angewendete Authentifizierungseinstellungen gelten für alle Funktionen in dieser App.

Nachdem die Funktion erstellt wurde, ersetzen Sie den Inhalt durch den folgenden Codeausschnitt:

#r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    return (ActionResult)new OkObjectResult(new List<object> {
        new {
            Id = 1,
            OrderDate = new DateTime(2016, 1, 6),
            Region = "east",
            Rep = "Jones",
            Item = "Pencil",
            Units = 95,
            UnitCost = 1.99,
            Total = 189.05
        },
        new {
            Id = 2,
            OrderDate = new DateTime(2016, 1, 23),
            Region = "central",
            Rep = "Kivell",
            Item = "Binder",
            Units = 50,
            UnitCost = 19.99,
            Total = 999.50
        },
        new {
            Id = 3,
            OrderDate = new DateTime(2016, 2, 9),
            Region = "central",
            Rep = "Jardine",
            Item = "Pencil",
            Units = 36,
            UnitCost = 4.99,
            Total = 179.64
        },
        new {
            Id = 4,
            OrderDate = new DateTime(2016, 2, 26),
            Region = "central",
            Rep = "Gill",
            Item = "Pen",
            Units = 27,
            UnitCost = 19.99,
            Total = 539.73
        },
        new {
            Id = 5,
            OrderDate = new DateTime(2016, 3, 15),
            Region = "west",
            Rep = "Sorvino",
            Item = "Pencil",
            Units = 56,
            UnitCost = 2.99,
            Total = 167.44
        }
    });
}

Stellen Sie sicher, dass die Funktion richtig funktioniert, indem Sie auf die Schaltfläche Speichern und ausführen klicken:

Wenn die Funktion richtig ausgeführt wurde, wird die Bezeichnung Status: 200 OK und die Auftragsliste im Testbereich angezeigt.

Sichern von Azure Function

Nachdem die Azure Function nun funktioniert, besteht der nächste Schritt darin, sie mit Azure Active Directory zu sichern, sodass man sich für den Zugriff darauf mit dem eigenen Organisationskonto anmelden muss.

Wählen Sie im Blatt „Funktionen-App“ im seitlichen Fensterbereich die Funktionen-App aus:

Wechseln Sie im oberen Abschnitt zur Registerkarte Plattformfeatures:

Wählen Sie als Nächstes in der Gruppe Netzwerk den Link Authentifizierung/Autorisierung aus:

Aktivieren Sie auf dem Blatt Authentifizierung/Autorisierung die App Service-Authentifizierung durch Umschalten der Umschaltfläche App Service-Authentifizierung in Ein:

Ändern Sie in der Dropdownliste Auszuführende Aktion, wenn die Anforderung nicht authentifiziert ist den Wert zu Mit Azure Active Directory anmelden. Durch diese Einstellung wird sichergestellt, dass anonyme Anforderungen an die API nicht zulässig sind:

Wählen Sie dann in der Liste der Authentifizierungsanbieter Azure Active Directory aus:

Legen Sie auf dem Blatt Azure Active Directory-Einstellungen die Option Verwaltungsmodus auf Erweitert fest. Legen Sie die zweite Option Verwaltungsmodus auf Neue AD-App erstellen fest:

Wichtig

Bevor Sie fortfahren, notieren Sie sich den Wert im Feld App erstellen. Dieser Wert stellt den Namen der Azure AD-Anwendung dar, die Sie zum Sichern der API verwenden werden. Sie benötigen ihn später, um Berechtigungen zum Zugriff auf die API aus dem SharePoint-Framework-Projekt anzufordern.

Bestätigen Sie Ihre Auswahl mit der Schaltfläche OK.

Zurück im Blatt Authentifizierung / Autorisierung , aktualisieren Sie die Authentifizierungs- und Autorisierungseinstellungen der Funktions-App, indem Sie die Schaltfläche Speichern drücken:

Überprüfen Sie, ob die API ordnungsgemäß gesichert wurde, indem Sie ein neues Browserfenster im privaten Modus öffnen und zu der API navigieren. Die URL für Ihre Funktons-App finden Sie im Abschnitt Übersicht des Blattes Funktions-App. Wenn die Authentifizierungseinstellungen richtig angewendet wurden, sollten Sie zur Azure AD-Anmeldeseite umgeleitet werden:

Abrufen einer Azure AD-Anwendungs-ID

Zur Anforderung eines Zugriffstokens für die Verbindung mit der API benötigen Sie die Anwendungs-ID der Azure AD-Anwendung, mit der die API gesichert wurde.

Navigieren Sie in der Funktionen-App zu den Einstellungen Authentifizierung. Wenn der Authentifizierungslink unter Konfigurierte Features nicht verfügbar ist, klicken Sie auf den Button Aktualisieren neben der Function-App im linken Bereich:

Wählen Sie in der Liste der Authentifizierungsanbieter Azure Active Directory aus:

Wählen Sie auf dem Blatt Azure Active Directory-Einstellungen die Schaltfläche Anwendung verwalten aus:

Kopieren Sie auf dem Blatt der Azure AD-Anwendung den Wert der Eigenschaft Anwendungs-ID:

Aktivieren von CORS

Die Funktionen-App wird von JavaScript, ausgeführt auf einer SharePoint-Seite, aufgerufen. Da die API in einer anderen Domäne als das SharePoint-Portal gehostet wird, werden die domänenübergreifenden Sicherheitseinschränkungen auf den API-Aufruf angewendet. Standardmäßig können mit Azure-Funktionen-Apps implementierte APIs nicht aus anderen Domänen aufgerufen werden. Sie können dies durch Anpassen der CORS-Einstellungen der Funktionen-App ändern.

Wichtig

Wenn Sie sich über die API mit dem SharePoint Online Cookie anstelle von OAuth authentifizieren, können Sie die CORS-Einstellungen nicht über das Azure-Portal konfigurieren. Damit die Authentifizierung funktioniert, müssen Sie alle CORS-Einstellungen im Azure-Portal löschen und stattdessen in Ihrer API angeben.

Wechseln Sie in der Funktionen-App zur Registerkarte Plattformfeatures.

Wählen Sie in der Gruppe API den Link CORS:

Fügen Sie der Liste der zulässigen Ursprünge die URL Ihres SharePoint-Mandanten hinzu (z. B. https://contoso.sharepoint.com):

Bestätigen Sie Ihre Änderungen mit der Schaltfläche Speichern.

Nutzen von mit Azure AD gesicherten Unternehmens-APIs aus SharePoint-Framework

Nachdem die API konfiguriert und funktionsfähig ist, besteht der nächste Schritt in der Erstellung der SharePoint-Framework-Lösung, die diese API nutzen wird.

Bevor Sie fortfahren, stellen Sie sicher, dass Sie Version 1.4.1 oder höher des Yeoman-Generators von SharePoint-Framework installiert haben. Wenn Sie den Generator global installiert haben, können Sie die installierte Version überprüfen, indem Sie in der Befehlszeile Folgendes ausführen: npm ls -g --depth=0.

Erstellen eines neuen SharePoint-Framework-Projekts

Als nächstes erstellen Sie ein neues SharePoint Framework-Projekt, um die API zu verwenden.

Erstellen Sie in der Befehlszeile einen neuen Ordner für das Projekt:

md contoso-api

Wechseln des Arbeitsordners

cd contoso-api

Starten Sie zum Erstellen eines neuen Projekts den Yeoman-Generator von SharePoint-Framework aus:

yo @microsoft/sharepoint

Es werden verschiedene Eingabeaufforderungen angezeigt. Geben Sie jeweils die folgenden Werte an:

• Wie lautet der Name Ihrer Lösung? contoso-api
• Welche Basisplanpakete möchten Sie für Ihre Komponente(n) als Ziel festlegen? Nur SharePoint Online (aktuellste)
• Wohin möchten Sie die Daten verschieben? Verwenden Sie den aktuellen Ordner.
• Möchten Sie den Mandantenadministratoren erlauben, festzulegen, ob die Lösungen unmittelbar für alle Websites bereitgestellt werden, ohne die Bereitstellung von Features oder das Hinzufügen von Apps zu Websites? Ja
• Benötigen die Komponenten in der Lösung Berechtigungen für den Zugriff auf eindeutige, nicht für andere Komponenten des Mandanten freigegebene Web-APIs? Nein
• Welchen Typ von clientseitiger Komponente möchten Sie erstellen? WebPart
• Wie lautet der Name Ihres Webparts? Aufträge
• Wie lautet die Beschreibung Ihres Webparts? Letzte Bestellungen anzeigen
• Welches Framework möchten Sie verwenden? Kein JavaScript-Framework:

Nachdem das Projekt erstellt wurde, öffnen Sie es in einem Code-Editor. In diesem Tutorial werden Sie Visual Studio Code verwenden:

Anfordern von Berechtigungen für die Unternehmens-API

Standardmäßig hat SharePoint-Framework keinen Zugriff auf Unternehmens-APIs, obwohl sie im gleichen Azure Active Directory wie Office 365 registriert sind. Dies ist beabsichtigt und ermöglicht es Organisationen auswählen, welche APIs für in SharePoint bereitgestellte Skripts und clientseitige Lösungen verfügbar gemacht werden sollen. Um Zugriff auf Ihre Unternehmens-APIs zu erhalten, müssen Sie eine Berechtigungsanforderung aus dem SharePoint-Framework-Projekt ausgeben, das Sie erstellen.

Öffnen Sie im Code-Editor die Datei config/package-solution.json:

Fügen Sie der solution-Eigenschaft eine neue Eigenschaft namens webApiPermissionRequests hinzu mit einem Verweis auf die Azure AD-Anwendung, die zum Sichern Ihrer API verwendet wird:

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "contoso-api-client-side-solution",
    "id": "8cbc01fb-bab6-48fc-afec-2c2053759771",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false,
    "webApiPermissionRequests": [
      {
        "resource": "contoso-api-dp20191109",
        "scope": "user_impersonation"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/contoso-api.sppkg"
  }
}

Der Wert der resource-Eigenschaft muss auf den Namen der Azure AD-Anwendung verweisen, mit der die API gesichert wird. Der Wert der scope-Eigenschaft gibt den Berechtigungsbereich an, den Ihre Lösung zur Kommunikation mit der API benötigt. In diesem Lernprogramm wird Azure AD nur zum Sichern der API verwendet. Daher werden Sie den Bereich user_impersonation verwenden.

Hinweis

Wenn Sie eine Verbindung zu einer Unternehmens-API herstellen möchten, die zuvor erstellt wurde, erkundigen Sie sich bei Ihrem Administrator nach den Details für die Azure AD-Anwendung, mit der sie gesichert ist. Sie benötigen Informationen wie die Anwendungs-ID, Berechtigungen, die die Anwendung verfügbar macht, und die Zielgruppe, für die sie konfiguriert ist.

Herstellen einer Verbindung mit der Unternehmens-API

Der letzte Teil besteht in der Implementierung der tatsächlichen Verbindung zu der Unternehmens-API.

Öffnen Sie im Code-Editor die Datei src\webparts\orders\OrdersWebPart.ts:

Verweisen Sie im oberen Abschnitt der Datei auf die Klassen AadHttpClient und HttpClientResponse, indem Sie den folgenden Codeausschnitt hinzufügen:

import { AadHttpClient, HttpClientResponse } from '@microsoft/sp-http';

Fügen Sie der OrdersWebPart-Klasse eine neue Klassenvariable namens ordersClient hinzu:

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  // shortened for brevity
}

Überschreiben Sie als Nächstes in der OrdersWebPart-Klasse die onInit()-Methode, um eine Instanz von AadHttpClient zu erstellen:

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  protected onInit(): Promise<void> {
    return new Promise<void>((resolve: () => void, reject: (error: any) => void): void => {
      this.context.aadHttpClientFactory
        .getClient('6bc8bca8-5866-405d-b236-9200bdbb73c0')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  // shortened for brevity
}

Die als zweiter Parameter des AadHttpClient-Konstruktors übergebene GUID ist die Anwendungs-ID der Azure AD-Anwendung, mit der die Unternehmens-API gesichert ist.

Erweitern Sie schließlich die render()-Methode um das Laden und Anzeigen von mit der Unternehmens-API abgerufenen Aufträgen:

export default class OrdersWebPart extends BaseClientSideWebPart<IOrdersWebPartProps> {
  private ordersClient: AadHttpClient;

  protected onInit(): Promise<void> {
    return new Promise<void>((resolve: () => void, reject: (error: any) => void): void => {
      this.context.aadHttpClientFactory
        .getClient('6bc8bca8-5866-405d-b236-9200bdbb73c0')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  public render(): void {
    this.context.statusRenderer.displayLoadingIndicator(this.domElement, 'orders');

    this.ordersClient
      .get('https://contoso-api-dp20191109.azurewebsites.net/api/Orders', AadHttpClient.configurations.v1)
      .then((res: HttpClientResponse): Promise<any> => {
        return res.json();
      })
      .then((orders: any): void => {
        this.context.statusRenderer.clearLoadingIndicator(this.domElement);
        this.domElement.innerHTML = `
          <div class="${ styles.orders}">
            <div class="${ styles.container}">
              <div class="${ styles.row}">
                <div class="${ styles.column}">
                  <span class="${ styles.title}">Orders</span>
                  <p class="${ styles.description}">
                    <ul>
                      ${orders.map(o => `<li>${o.rep} $${o.total}</li>`).join('')}
                    </ul>
                  </p>
                  <a href="https://aka.ms/spfx" class="${ styles.button}">
                    <span class="${ styles.label}">Learn more</span>
                  </a>
                </div>
              </div>
            </div>
          </div>`;
      }, (err: any): void => {
        this.context.statusRenderer.renderError(this.domElement, err);
      });
  }

  // shortened for brevity
}

Bereitstellen der Lösung im SharePoint-App-Katalog

Nach Abschluss der Implementierung der SharePoint-Framework-Lösung besteht der nächste Schritt in der Bereitstellung für SharePoint.

Erstellen und packen Sie zuerst das Projekt unter Verwendung der Befehlszeile:

gulp bundle --ship && gulp package-solution --ship

Öffnen Sie dann im Dateiexplorer den Projektordner, und navigieren Sie zum Ordner sharepoint/solution:

Navigieren Sie im Webbrowser zum Mandanten-App-Katalog in Ihrem Office 365-Mandanten:

Fügen Sie die neu erstellte .sppkg-Datei durch Ziehen und Ablegen aus dem Explorer zum Mandanten-App-Katalog hinzu:

Wenn Sie dazu aufgefordert werden, aktivieren Sie das Kontrollkästchen Diese Lösung an allen Standorten der Organisation verfügbar machen. Beachten Sie außerdem die Bemerkung, dass Sie zu der Seite für die Verwaltung von Dienstprinzipalberechtigungen navigieren sollten, um ausstehende Berechtigungen zu genehmigen. Bestätigen Sie die Bereitstellung durch Auswählen der Schaltfläche Bereitstellen.

Gewähren des Zugriffs auf die Unternehmens-API

Navigieren Sie im Webbrowser zur Mandantenadministratorwebsite, indem Sie im App-Startfeld von Office 365 die Option Admin auswählen:

Wählen Sie im Menü in der Gruppe Admin Center die Option SharePoint aus:

Navigieren Sie im SharePoint Admin Center zu der neuen SharePoint Admin Center-Vorschau mithilfe des Links Neues SharePoint Admin Center (Vorschau) testen:

Wählen Sie im neuen Admin Center aus dem Menü die Option API Management aus:

Wählen Sie auf der Seite „API Management“ in der Gruppe Genehmigung ausstehend die neu hinzugefügte Berechtigungsanforderung für den Zugriff auf die API contoso-api aus (der Name Ihrer API wird angezeigt):

Klicken Sie dann in der Symbolleiste auf die Schaltfläche Genehmigen oder ablehnen:

Gewähren Sie im seitlichen Bereich den Zugriff auf die API, indem Sie auf die Schaltfläche Genehmigen klicken:

Hinweis

Es ist möglich, ein Domänen-isoliertes Webpart zu erstellen, das eine Verbindung mit der API herstellt, die mit AAD gesichert wurde. In diesem Fall muss der CORS für die API entsprechend neu konfiguriert werden, da jede Instanz eines Domänen-isolierten Webparts in dedizierten App-Webparts mit eindeutiger Domäne ausgeführt wird.

Hinzufügen des Webparts „Orders“ zu der Seite

Um zu überprüfen, ob alles wie erwartet funktioniert, fügen Sie das zuvor erstellte „Orders“-Webpart zu einer Seite hinzu.

Navigieren Sie im Webbrowser zu einer Website in Ihrem Mandanten. Wählen Sie auf der Symbolleiste die Option Bearbeiten aus:

Wählen Sie im Zeichenbereich einen Abschnitt aus, um das Webpart hinzuzufügen:

Wählen Sie die Option + aus, um die Toolbox zu öffnen. Geben Sie im Suchfeld Aufträge (Orders) ein, um das Aufträge-Webpart schnell zu finden:

Wählen Sie das Orders-Webpart aus, um es der Seite hinzuzufügen. Die Liste der von der Unternehmens-API abgerufenen Aufträge sollte angezeigt werden:

Wenn Sie einen Fehler mit den technischen Details von "Popup-Fenster nicht geöffnet" erhalten, haben Sie einen Popup-Blocker aktiviert. Sie müssen den Popup-Blocker des Browsers für Ihre Website deaktivieren, um die Seite korrekt anzuzeigen.