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

In diesem Artikel wird veranschaulicht, wie Sie eine Verbindung mit einer mehrinstanzenfähigen 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 mehrinstanzenfähigen, mit Azure AD gesicherten Unternehmens-API

Beginnen Sie mit der Erstellung einer mehrinstanzenfähigen, mit Azure Active Directory gesicherten Unternehmens-API. Es gibt zwar keine Einschränkungen, wie die API aus SharePoint-Framework Sicht implementiert werden soll, in diesem Tutorial erstellen Sie die API jedoch mithilfe von Azure Functions und schützen sie mithilfe von 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 Funktions-App.

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

Erstellen Sie in der Funktionen-App eine neue über HTTP ausgelöste Funktion. In diesem Beispiel erstellen Sie es mit C#, aber es gibt keine Einschränkung in Bezug auf die Programmiersprache, die Sie verwenden können.

Wählen Sie in der Funktions-App die Schaltfläche Hinzufügen aus, und wählen Sie in der Liste der verfügbaren Funktionstypen die Option HTTP-Trigger aus.

Geben Sie in den Einstellungen der Funktion den Funktionsnamen an, und legen Sie die Autorisierungsebene auf Anonym fest.

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.

Um Ihre Einstellungen zu bestätigen und die Funktion zu erstellen, wählen Sie die Schaltfläche Funktion erstellen aus.

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

using System.Net;

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, TraceWriter log)
{
    log.Info("C# HTTP trigger function processed a request.");

    return req.CreateResponse(HttpStatusCode.OK, 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
        }
    });
}

Überprüfen Sie, ob die Funktion ordnungsgemäß funktioniert, indem Sie die Schaltfläche Testen und ausführen auswählen und auf Ausführen klicken.

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

Schützen der Azure-Funktion

Da die Azure-Funktion nun funktioniert, besteht der nächste Schritt darin, sie mit Azure Active Directory zu schützen, damit Sie sich mit Ihrem Organisationskonto anmelden müssen, um darauf zugreifen zu können.

Wählen Sie auf dem Blatt Funktions-App im Seitenbereich 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 Aktion, die ausgeführt werden soll, wenn die Anforderung nicht authentifiziert ist, den Wert in Mit Azure Active Directory anmelden.

Diese Einstellung stellt sicher, dass anonyme Anforderungen an die API nicht zulässig sind.

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

Wählen Sie auf dem Blatt Azure Active Directory-Einstellungen für die erste Option unter Verwaltungsmodus die Option Express aus. Wählen Sie für die zweite Option unter Verwaltungsmodus die Option Neue AD-App erstellen aus.

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

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 Schützen der API verwenden und die Sie später benötigen, um Berechtigungen für den Zugriff auf die API aus dem SharePoint-Framework-Projekt anzufordern.

Aktualisieren Sie die Einstellungen der Funktionen-App für Authentifizierung und Autorisierung, indem Sie die Schaltfläche Speichern wählen.

Überprüfen Sie, ob die API ordnungsgemäß gesichert wurde, indem Sie ein neues Browserfenster im privaten Modus öffnen und zu der API navigieren. Wenn die Authentifizierungseinstellungen richtig angewendet wurden, sollten Sie zur Azure AD-Anmeldeseite umgeleitet werden.

Die Azure AD-Anwendung mehrinstanzenfähig machen

Wenn Sie eine Azure-Funktion mit einer Azure AD-Anwendung sichern, kann diese Azure-Funktion standardmäßig nur von Benutzern aus der gleichen Azure AD verwendet werden, in der sich die Anwendung befindet. Wenn Sie die API in verschiedenen Mandanten verwenden möchten, müssen Sie die Azure AD-Anwendung in eine mehrinstanzenfähige Anwendung ändern.

Ändern der Anwendung in eine mehrinstanzenfähige Anwendung

Navigieren Sie zur Startseite des Azure-Portal, und suchen Sie nach Azure Active Directory.

Wählen Sie auf dem linken Blatt App-Registrierungen und dann die App aus, die beim Erstellen der Funktions-App automatisch erstellt wurde.

Ändern Sie im Feld Api-Update des App-ID-URI verfügbar machen die ID Ihrer Azure AD-App, sodass sie mit https://yourtenant.onmicrosoft.combeginnt, https://contoso.onmicrosoft.com/contoso-apiz. B. . Diese Änderung ist erforderlich, da die Azure AD-App von anderen Mandanten verwendet wird und die Eindeutigkeit für alle Azure Active Directorys sichergestellt werden muss.

Klicken Sie in der Übersicht auf den Link Unterstützte Kontotypen, der nur My organization sein wird. Wir müssen sie ändern, damit die App mehrinstanzenfähig ist.

Ändern Sie den Wert des Mehrinstanzenfähigen Felds auf Ja:

Bestätigen Sie schließlich Ihre Änderungen, indem Sie auf der Symbolleiste die Schaltfläche Speichern wählen.

Zulassen, dass Benutzer aus anderen Azure ADs Ihre Anwendungen verwenden

Da Sie Ihre API unter Verwendung der Azure AD Express-Einstellungen gesichert haben, dürfen nur Benutzer aus dem gleichen Azure AD, in dem die Anwendung gespeichert ist, die API verwenden. Da die API auch von Benutzern aus anderen Mandanten verwendet werden soll, müssen Sie die Sicherheitseinstellungen anpassen.

Schließen Sie alle geöffneten Blätter, bis Sie wieder auf dem Blatt Authentifizierung/Autorisierung der Funktions-App sind. Wählen Sie in der Liste der Authentifizierungsanbieter Azure Active Directory aus.

Ändern Sie auf dem Blatt Azure Active Directory-Einstellungen den Wert der Option Verwaltungsmodus in Erweitert.

Löschen Sie als Nächstes den Wert im Feld Aussteller-URL. Dadurch können sich Benutzer aus anderen Azure Active Directorys bei Ihrer API authentifizieren.

Bevor Sie Ihre Änderungen bestätigen, kopieren Sie den Wert aus dem Feld Client-ID. Sie benötigen es beim Erstellen Ihres Webparts, um ein Zugriffstoken für die API anzufordern.

Bestätigen Sie Ihre Änderungen mithilfe der Schaltfläche OK , und bestätigen Sie Ihre Änderungen mithilfe der Schaltfläche Speichern .

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 Function Apps implementierte APIs nicht aus anderen Domänen aufgerufen werden. Sie können dies durch Anpassen der CORS-Einstellungen der Funktionen-App ändern.

Klicken Sie in der Funktions-App auf 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.

Zustimmen zur Verwendung der API in Ihrem Mandanten

Bevor Benutzer in Ihrem Mandanten die API von einem anderen Mandanten verwenden können, muss die API genehmigt werden. Die Genehmigung, auch als Zustimmung bezeichnet, kann auf zwei Ebenen erfolgen: auf Benutzer- und auf Administratorebene (Organisation). In diesem Szenario verwenden Sie die Administratoreinwilligung, um die API für die Verwendung durch die gesamte organization zu genehmigen.

Hinweis

In der Regel werden Sie von der Website, die die API verfügbar macht, durch den Vorgang der Zustimmung zu der API in Ihrem Mandanten geführt. In diesem Beispiel führen Sie die erforderlichen Schritte manuell aus, um besser zu verstehen, wie der Prozess funktioniert.

Wählen Sie auf dem Blatt „Funktionen-App“ Ihre Funktion aus.

Um die URL der Funktion zu ermitteln, wählen Sie auf der Symbolleiste die Option Funktions-URL abrufen.

Kopieren Sie im Dialogfeld Funktions-URL abrufen die URL der Funktion mithilfe der Schaltfläche Kopieren.

Navigieren Sie in einem neuen Browserfenster zu der Funktions-URL, die Sie kopiert haben. Wenn Sie zur Anmeldung aufgefordert werden, verwenden Sie dazu das Administratorkonto des Office 365-Mandanten, in dem Sie die API verwenden möchten.

Nach der Anmeldung werden Sie aufgefordert, der Verwendung dieser API zuzustimmen.

Dies ist jedoch die Benutzerzustimmung. Um zur Administratoreinwilligung zu wechseln und die API für die Verwendung durch die gesamte organization zu genehmigen, fügen Sie an die URL &prompt=admin_consent an. Auch hier werden Sie mit einem Zustimmungsdialogfeld aufgefordert. Beachten Sie jedoch, dass dieses Mal im Dialogfeld angegeben wird, dass die App zugriff auf die angegebenen Ressourcen für alle Benutzer in Ihrem organization hat und niemand sonst dazu aufgefordert wird.

Bestätigen Sie, dass Benutzer in Ihrer Organisation die API verwenden dürfen, indem Sie die Schaltfläche Zulassen wählen.

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 ausführen: npm ls -g --depth=0.

Erstellen eines neuen SharePoint-Framework-Projekts

Beginnen Sie mit der Erstellung eines neuen SharePoint-Framework-Projekts. Erstellen Sie in der Befehlszeile einen neuen Ordner für das Projekt:

md contoso-api

Ändern Sie das Arbeitsverzeichnis, indem Sie in der Befehlszeile Folgendes ausführen:

cd contoso-api

Führen 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:

• contoso-api als Lösungsnamen
• SharePoint Online only (latest) als Basispaketsatz
• Verwenden Sie den aktuellen Ordner als Speicherort für Dateien
• Y als Option zum Aktivieren der mandantenweiten Bereitstellung
• WebPart als den Typ der zu erstellenden Komponente
• Orders als den Namen des zu erstellenden Webparts
• Zeigt letzte Bestellungen als Webpartbeschreibung
• No JavaScript framework als das zu verwendende Framework

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

Anfordern von Berechtigungen für die Unternehmens-API

Standardmäßig haben 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 einen neuen Abschnitt namens webApiPermissionRequests mit einem Verweis auf die Azure AD-Anwendung zum Sichern Ihrer API hinzu:

{
  "$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,
    "webApiPermissionRequests": [
      {
        "resource": "contoso-api",
        "scope": "user_impersonation"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/contoso-api.sppkg"
  }
}

Der Wert der Ressourceneigenschaft bezieht sich nur auf den Namen der Azure AD-Anwendung, die zum Sichern der API verwendet wird. Der Wert der Scope-Eigenschaft gibt den Berechtigungsbereich an, den Ihre Lösung für die 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('https://contoso-api.azurewebsites.net')
        .then((client: AadHttpClient): void => {
          this.ordersClient = client;
          resolve();
        }, err => reject(err));
    });
  }

  // shortened for brevity
}

Der an die getClient() -Methode übergebene URI ist der Anwendungs-ID-URI der Azure AD-Anwendung, die zum Schützen der Unternehmens-API verwendet wird.

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('https://contoso-api.azurewebsites.net')
        .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.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 Sie zunächst das Projekt, und packen Sie es, indem Sie in der Befehlszeile ausführen:

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

Öffnen Sie dann im Explorer den Projektordner, und navigieren Sie zum Ordner sharepoint/solution.

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

Fügen Sie die neu generierte Datei .sppkg** hinzu, indem Sie sie aus dem Explorer in den Mandanten-App-Katalog ziehen und ablegen.

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.

Wählen Sie dann auf der Symbolleiste die Option Genehmigen oder ablehnen aus.

Gewähren Sie im seitlichen Bereich den Zugriff auf die API, indem Sie die Schaltfläche Genehmigen wählen.

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 der 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 Orders ein, um das Orders-Webpart schnell zu finden.

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