Voraussetzungen für den Microsoft SharePoint 365-Connector in Jitterbit Studio

Einführung

Um den Microsoft SharePoint 365-Connector zu verwenden, benötigen Sie eine Microsoft SharePoint 365-App, deren Anmeldedaten und bestimmte Berechtigungen. Dieses Dokument beschreibt die Erstellung einer App und das Abrufen ihrer Anmeldedaten für beide verfügbaren Authentifizierungstypen in der Verbindung (Azure Access Control Service oder Microsoft Entra ID).

Weitere Informationen zum Upgrade Ihrer vorhandenen SharePoint-App von Azure Access Control Service zu Microsoft Entra ID finden Sie in Microsofts Dokumentation.

Microsoft Entra ID

In diesem Abschnitt wird beschrieben, wie man eine App mit Microsoft Entra ID registriert, deren Berechtigungen festlegt und eine Client-Assertion generiert.

Schritte zur Microsoft Entra ID-App-Registrierung

Führen Sie diese Schritte aus, um eine App-Registrierung zu erstellen mit der Microsoft-Identitätsplattform:

1. Suchen Sie im Azure-Portal nach Microsoft Entra ID (früher als Azure Active Directory oder Azure AD bekannt) und klicken Sie darauf:

   

2. Klicken Sie in der linken Seitenleiste unter Verwalten auf App-Registrierungen.

3. Klicken Sie auf Neue Registrierung:

   

4. Geben Sie einen Namen für Ihre App ein. Dieser Anzeigename ist für Benutzer sichtbar:

   

5. Klicken Sie auf Registrieren, um die App-Registrierung abzuschließen. Sie werden dann zur Übersichtsseite der App weitergeleitet:

   

   Wichtig

   Speichern Sie die Anwendungs-ID (Client) und die Verzeichnis-ID (Mandant) der App-Registrierung, um sie als Client-ID und Mandanten-ID beim Konfigurieren einer Verbindung zu verwenden.

Erforderliche Berechtigungen zur App-Registrierung hinzufügen

Ihre App-Registrierung muss über einen bestimmten Satz von Berechtigungen verfügen.

Navigieren Sie im Azure-Portal zu Ihrer App-Registrierung und klicken Sie in der linken Seitenleiste auf API-Berechtigungen:

Um Microsoft SharePoint-Anwendungsberechtigungen hinzuzufügen, führen Sie diese Schritte aus:

1. Klicken Sie auf der Seite API-Berechtigungen auf Berechtigung hinzufügen.

2. Klicken Sie im Bereich API-Berechtigungen anfordern auf die Registerkarte APIs, die meine Organisation verwendet, suchen Sie nach SharePoint und klicken Sie darauf.

3. Klicken Sie auf Anwendungsberechtigungen.

4. Aktivieren Sie die Berechtigung Sites.FullControl.All.

5. Klicken Sie auf Berechtigungen hinzufügen. Die Seite Konfigurierte Berechtigungen der aktualisierten App-Registrierung wird angezeigt.

Client-Assertion generieren

Führen Sie diese Schritte aus, um eine Client-Assertion zu generieren (erforderlich für die Verbindungskonfiguration):

1. Erstellen Sie ein selbstsigniertes Zertifikat, indem Sie die folgenden Anweisungen ausführen:

   Speichern Sie das von Microsoft bereitgestellte PowerShell-Skript mit dem Namen Create-SelfSignedCertificate.ps1 auf Ihrem Computer.

Gehen Sie in PowerShell in das Verzeichnis, in dem das Skript gespeichert wurde, und führen Sie dieses Skript aus (als Administrator):

.\Create-SelfSignedCertificate.ps1 -CommonName "<Geben Sie einen Namen für das Zertifikat ein, Beispiel: MyCert>" -StartDate <Geben Sie ein Zertifikatstartdatum im ISO-Datumsformat ein: 2024-10-01> -EndDate <Geben Sie ein Zertifikatablaufdatum im ISO-Format ein: 2029-10-01>

Ersetzen Sie den Platzhaltertext (einschließlich der spitzen Klammern < >) durch die entsprechenden Werte für Ihren Anwendungsfall.

Nach dem Ausführen des Skripts werden Sie aufgefordert, ein Passwort zum Verschlüsseln Ihres privaten Schlüssels einzugeben. Anschließend werden sowohl die .PFX-Datei als auch die .CER-Datei in das aktuelle Verzeichnis exportiert.

1. Laden Sie das selbstsignierte Zertifikat in die App-Registrierung hoch:

   Klicken Sie auf der Übersichtsseite Ihrer App-Registrierung auf Zertifikat oder Geheimnis hinzufügen und dann auf Zertifikat hochladen. Wählen Sie die in Schritt 1 generierte .CER-Datei aus.

   Nach dem Hochladen des Zertifikats behalten Sie den Wert in der Spalte Fingerabdruck für das Zertifikat. Dieser Wert ist eine Hexadezimalzeichenfolge und muss in eine base64url-codierte Zeichenfolge konvertiert werden, um als x5t-Wert in Schritt 4 verwendet zu werden. Konvertieren Sie dazu den Hex-Fingerabdruck in sein rohes Byte-Array, codieren Sie dieses Byte-Array mit Base64, und konvertieren Sie das Ergebnis dann in base64url, indem Sie alle +-Zeichen durch - ersetzen, alle /-Zeichen durch _ ersetzen und alle nachgestellten =-Zeichen entfernen.

   Beispielsweise kann diese Konvertierung mit einem Jitterbit-Skript durchgeführt werden:

   <trans>
   // thumbprint holds the hex value from the certificate's Thumbprint column
   base64 = Base64Encode(HexToBinary(thumbprint));
   x5t = RTrimChars(Replace(Replace(base64, "+", "-"), "/", "_"), "=");
   </trans>
   

2. Generieren Sie eine .PEM-Datei aus der generierten .PFX-Datei (aus Schritt 1) mit diesem Skript in PowerShell (als Administrator):

   openssl pkcs12 -in <Geben Sie den Namen der generierten .PFX-Datei ein>.pfx -out private.pem -nodes
   

   Ersetzen Sie den Platzhaltertext (einschließlich der spitzen Klammern < >) durch die entsprechenden Werte.

   Behalten Sie den private_key-Wert aus der generierten .PEM-Datei (zur Verwendung in Schritt 4).

3. Generieren Sie die Client-Assertion. Die folgenden Schritte zeigen, wie dies mit jwt.io durchgeführt wird.

   Tipp

   Die Client-Assertion kann auch vollständig in einem Jitterbit-Skript mit der Funktion CreateJwtToken generiert werden.

   Wählen Sie auf jwt.io RS256 als Algorithmus aus und konfigurieren Sie Header, Payload und Signatur überprüfen.

   Tipp

   Anstatt Header und Payload JSON manuell zu verfassen, generiert dieses Jitterbit-Skript beide Werte, einschließlich der jti-GUID und der Zeitstempel iat, nbf und exp, und schreibt sie in das Operationsprotokoll. Führen Sie dieses Skript in einer Operation aus und kopieren Sie dann die protokollierten Werte in die Felder Header und Payload unten.

   <trans>
   // Application (client) ID from Entra
   client_id = '<Enter client ID>';
   
   // Directory (tenant) ID from Entra
   tenant_id = '<Enter tenant ID>';
   
   // base64url-encoded thumbprint obtained in step 2
   x5t = '<Enter x5t value>';
   
   // If the agent is not running on a server in the Central time zone, replace 'America/Chicago' with the appropriate time zone
   now = Int(ConvertTimeZone(Now(), 'America/Chicago', 'UTC'));
   later = Int(ConvertTimeZone(DateAdd('yyyy', 10, Now()), 'America/Chicago', 'UTC'));
   
   header = '{
    "alg": "RS256",
    "typ": "JWT",
    "x5t":"' + x5t + '"
   }';
   
   payload = '{
    "aud": "https://login.microsoftonline.com/' + tenant_id + '/oauth2/v2.0/token",
    "exp": ' + later + ',
    "iss": "' + client_id + '",
    "jti": "' + GUID() + '",
    "nbf": ' + now + ',
    "iat": ' + now + ',
    "sub": "' + client_id + '"
   }';
   
   WriteToOperationLog('JWT Header:');
   WriteToOperationLog(header);
   WriteToOperationLog('\r\n');
   WriteToOperationLog('JWT Payload:');
   WriteToOperationLog(payload);
   </trans>
   

   Geben Sie den Header in diesem Format ein:

   Header

   {
    "alg": "RS256",
    "typ": "JWT",
    "x5t":"<Enter the base64url-encoded thumbprint obtained in step 2>"
   }
   

   Ersetzen Sie den Platzhaltertext (einschließlich der spitzen Klammern < >) durch den entsprechenden Wert.

   Geben Sie den Payload in diesem Format ein:

   Payload

   {
    "aud": "https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token",
    "exp": <an expiration time>,
    "iss": "<client ID>",
    "jti": "<a GUID>",
    "nbf": <a "not before" claim>,
    "iat": <an "issued at" claim>,
    "sub": "<client ID>"
   }
   

   Ersetzen Sie den Platzhaltertext (einschließlich der spitzen Klammern < >) durch den entsprechenden Wert für Ihren Anwendungsfall. Weitere Informationen zu diesen Feldern finden Sie in der Microsoft-Dokumentation.

   Geben Sie im Abschnitt Signatur überprüfen den private_key (aus Schritt 3) für die App-Registrierung ein.

   Nachdem die Abschnitte Header, Payload und Signatur überprüfen konfiguriert wurden, ist der im Abschnitt Encoded generierte Wert der Wert, der als Client-Assertion in der Verbindungskonfiguration verwendet werden soll.

Azure Access Control Service (veraltet)

In diesem Abschnitt wird beschrieben, wie man eine App mit dem SharePoint Add-in-Modell und Azure Access Control Service (ACS) erstellt und deren Berechtigungen festlegt. Die Schritte zur Authentifizierung mit Microsoft Entra ID werden im nächsten Abschnitt beschrieben.

App erstellen

Dies sind die Anweisungen zum Erstellen einer App:

1. Melden Sie sich bei der Microsoft SharePoint-Instanz an.

2. Nach der Anmeldung navigieren Sie zu dieser URL (ersetzen Sie <office_365_tenant_URL> durch Ihre Office 365-Mandanten-URL):

   https://<office_365_tenant_URL>/_layouts/15/appregnew.aspx

3. Unter dieser URL wird folgende Oberfläche angezeigt:

   

   • Client-ID: Klicken Sie auf Generieren, um eine Client-ID für Ihre App zu generieren.

   • Client-Geheimnis: Klicken Sie auf Generieren, um ein Client-Geheimnis für Ihre App zu generieren.

   • Titel: Geben Sie einen Titel für Ihre App ein.

   • App-Domäne: Geben Sie eine Domäne für Ihre App ein oder geben Sie einen Platzhalterwert ein.

   • Redirect-URI: Geben Sie einen Redirect-URI für Ihre App ein oder geben Sie einen Platzhalterwert ein.

   Hinweis

   Der Microsoft SharePoint 365-Connector verwendet die konfigurierten Werte für App-Domäne oder Redirect-URI nicht.

4. Nachdem alle Felder ausgefüllt sind, klicken Sie auf Erstellen. Eine Seite zeigt die Informationen der App an. Speichern Sie diese Informationen zur späteren Verwendung beim Festlegen von Berechtigungen für die App.

Berechtigungen festlegen

Dies sind die Anweisungen zum Autorisieren der App für die Verwendung mit dem Microsoft SharePoint 365-Connector:

1. Navigieren Sie zu dieser URL (ersetzen Sie <office_365_tenant_URL> durch Ihre Office 365-Mandanten-URL):

   https://<office_365_tenant_URL>/_layouts/appinv.aspx

2. Unter dieser URL wird folgende Oberfläche angezeigt:

   

   • App-ID: Geben Sie die Client-ID für die App ein (generiert während der App-Erstellung).

   • Titel: Geben Sie den Titel Ihrer App ein (festgelegt während der App-Erstellung).

   • App-Domäne: Geben Sie die Domäne für Ihre App ein (festgelegt während der App-Erstellung).

   • Redirect-URL: Geben Sie die Redirect-URL für Ihre App ein (festgelegt während der App-Erstellung).

   • Permission Request XML: Geben Sie diese Berechtigung in das Textfeld ein:

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

     Weitere Informationen zu Add-in-Berechtigungen finden Sie in der Microsoft-Dokumentation zu Add-in-Berechtigungen in SharePoint und Authorization Code OAuth flow for SharePoint Add-ins.