SharePoint einrichten¶

Diese Seite beschreibt die Integration von SharePoint in die Bot-Plattform.

Einrichtung im Azure Portal¶

Um die SharePoint-Integration einzurichten, musst du zunächst eine App-Registrierung im Azure Portal vornehmen.

Warum Azure Portal und App-Registrierung?¶

Technischer Hintergrund: SharePoint Online ist Teil des Microsoft 365 Ökosystems und verwendet Microsoft Entra ID (ehemals Azure Active Directory) für die Authentifizierung und Autorisierung. Da SharePoint-Daten sensible Unternehmensinformationen enthalten, implementiert Microsoft strenge Sicherheitsmaßnahmen:

1. Mandanten-Isolation (Tenant)¶

Jede Organisation hat einen eigenen Mandanten (Tenant) in Microsoft Entra ID
Der Mandant ist die oberste Sicherheitsgrenze und isoliert Daten verschiedener Organisationen
Tenant-ID identifiziert eindeutig deine Organisation im Microsoft-Ökosystem
Ohne Tenant-ID kann Microsoft nicht bestimmen, auf welche SharePoint-Instanz zugegriffen werden soll

2. App-Registrierung als Sicherheitskonzept¶

Vertrauen schaffen: Microsoft muss externe Anwendungen (wie unseren Bot) explizit kennen
Identitätsnachweis: Jede App erhält eine eindeutige Client-ID als Identifikation
Berechtigungsmodell: Nur explizit genehmigte Apps können auf SharePoint zugreifen
Audit-Trail: Alle API-Zugriffe werden der registrierten App zugeordnet

3. OAuth 2.0 Standard¶

Microsoft implementiert den OAuth 2.0 Standard für sichere API-Zugriffe
Client Secret beweist, dass die App tatsächlich die registrierte App ist
Scope-basierte Berechtigungen: Apps erhalten nur die minimal nötigen Berechtigungen
Token-basierte Authentifizierung: sichere, zeitbegrenzte Zugriffstokens

4. Sicherheitsebenen¶

Organisation (Tenant) -> App-Registrierung -> Berechtigungen -> SharePoint-Zugriff

Ohne diese Struktur wäre SharePoint ein offenes System ohne Kontrolle über externe Zugriffe und damit ein erhebliches Sicherheitsrisiko für Unternehmensdaten.

1. App-Registrierung erstellen¶

Melde dich beim Azure Portal an.
Navigiere zu Microsoft Entra ID (ggf. über die Suche).
Navigiere zu Verwalten -> App-Registrierungen in der linken Seitenleiste.
Klicke auf Neue Registrierung.
Gib einen Namen für deine Anwendung ein (z. B. "Bot SharePoint Integration").
Wähle unter Unterstützte Kontotypen die Option "Nur Konten in diesem Organisationsverzeichnis".
Unter Umleitungs-URI:
Plattform: Web
URI für Produktion: https://ai.clye-gmbh.de/api/sharepoint/callback
Für lokale Entwicklung: http://localhost:3000/api/sharepoint/callback
Klicke auf Registrieren.

2. API-Berechtigungen konfigurieren¶

Gehe in deiner App-Registrierung in der Seitenleiste zu Verwalten -> API-Berechtigungen.
Klicke auf Berechtigung hinzufügen -> Microsoft Graph.
Wähle Anwendungsberechtigungen (nicht delegierte Berechtigungen).
Suche und füge folgende Berechtigungen hinzu:
Sites.Read.All (zum Lesen von SharePoint-Sitesammlungen)
Sites.ReadWrite.All (zum Schreiben in SharePoint-Listen, falls notwendig)
Files.Read.All (zum Downloaden und Lesen von Dateien)
Klicke auf Berechtigungen hinzufügen.
Wichtig: Klicke auf Administratorzustimmung für [dein Verzeichnis] erteilen und bestätige.

3. Client Secret erstellen¶

Navigiere in deiner App-Registrierung zu Zertifikate & Geheimnisse.
Klicke unter Geheimer Clientschlüssel auf Neuer geheimer Clientschlüssel.
Gib eine Beschreibung ein und wähle die gewünschte Ablaufzeit.
Klicke auf Hinzufügen.
Wichtig: Kopiere und speichere den angezeigten Wert des geheimen Clientschlüssels. Er wird nur einmal angezeigt.

4. Benötigte Informationen sammeln¶

Notiere dir folgende Werte, die du für die Konfiguration der SharePoint-Integration benötigst:

Client-ID (Anwendungs-ID): auf der Übersichtsseite deiner App-Registrierung
Mandanten-ID (Verzeichnis-ID): ebenfalls auf der Übersichtsseite
Client Secret: der zuvor kopierte geheime Clientschlüssel
SharePoint-Site-URL: die URL deiner SharePoint-Website (z. B. https://dein-unternehmen.sharepoint.com)

Konfiguration im Bot-Admin-Panel¶

Nachdem du die Azure App-Registrierung abgeschlossen hast, kannst du die SharePoint-Integration für deinen Bot konfigurieren.

1. Zum Bot-Admin-Panel navigieren¶

Melde dich in der Bot-Plattform an.
Navigiere zu den Einstellungen des gewünschten Bots.
Klicke in der linken Seitenleiste auf Tools.
Scrolle nach unten zu SharePoint Integrationen.

2. Neue Integration erstellen¶

Klicke auf Neue Integration anlegen.
Fülle die folgenden Felder aus:
Name: beliebiger Name für die Integration (z. B. "Haupt-SharePoint")
SharePoint Site URL: die URL deiner SharePoint-Website
Client ID: die Anwendungs-ID aus deiner Azure App-Registrierung
Tenant ID: die Verzeichnis-ID aus deiner Azure App-Registrierung
Client Secret: der geheime Clientschlüssel
Klicke auf Erstellen.

3. Integration verbinden¶

Nach der Erstellung siehst du die neue Integration in der Liste mit einem roten Punkt neben dem Namen. Das zeigt an, dass die Integration noch nicht autorisiert ist.

Aktiviere die SharePoint-Integration mit dem Switch.
Klicke auf den Link-Button neben der Integration.
Du wirst automatisch zu Microsoft weitergeleitet.
Melde dich mit deinem Microsoft-Account an, der Zugriff auf die SharePoint-Website hat.
Bestätige die Berechtigung für die Bot-Anwendung.
Nach erfolgreicher Authentifizierung wirst du zur Bot-Plattform zurückgeleitet.

Der rote Punkt wird nun grün, was bedeutet, dass die Integration erfolgreich verbunden ist und der Bot auf SharePoint zugreifen kann.

Verwendung der SharePoint-API in der Bot-Plattform¶

Nach der erfolgreichen Konfiguration und Verbindung der SharePoint-Integration stehen dem Bot zwei wichtige Funktionen zur Verfügung:

Verfügbare SharePoint-Funktionen¶

1. `sharepoint_search` - Inhalte suchen¶

Diese Funktion ermöglicht es dem Bot, nach Inhalten in SharePoint-Dateien zu suchen.

Zweck: Durchsucht Dokumente und Dateien nach spezifischen Inhalten
Rückgabe: Relevante Textpassagen und Snippets aus gefundenen Dokumenten
Anwendung: Ideal für die Beantwortung von Fragen basierend auf Unternehmensdokumenten

2. `sharepoint_read` - Komplette Dateien lesen¶

Diese Funktion ermöglicht es dem Bot, vollständige Dateien aus SharePoint zu lesen und auszugeben.

Zweck: Liest und gibt den kompletten Inhalt einer spezifischen Datei aus
Rückgabe: Vollständiger Dateiinhalt (bei Textdateien)
Anwendung: Nützlich für die Analyse ganzer Dokumente oder das Extrahieren spezifischer Informationen

Konfiguration des System-Prompts¶

Empfehlung: Passe den System-Prompt deines Bots an, um die SharePoint-Integration optimal zu nutzen.

Navigiere zu den Einstellungen deines Bots.
Klicke auf Advanced.
Füge eine Anweisung zum System-Prompt hinzu, z. B.:

Du hast Zugriff auf SharePoint-Dokumente über die Funktionen sharepoint_search und sharepoint_read.
Nutze diese Funktionen, um Fragen basierend auf Unternehmensdokumenten zu beantworten.
Suche zuerst nach relevanten Inhalten mit sharepoint_search, bevor du antwortest.

Verwendung im Chat¶

Option 1: Automatische Nutzung (empfohlen)¶

Wenn der System-Prompt entsprechend angepasst wurde, wird der Bot automatisch SharePoint durchsuchen, wenn dies für die Beantwortung einer Frage relevant ist.

Option 2: Manuelle Anweisung¶

Falls der System-Prompt nicht angepasst wurde, kann der Benutzer den Bot explizit anweisen.

Beispiele für Chat-Anfragen:

"Suche in SharePoint nach Informationen über das Projekt XY"
"Durchsuche unsere SharePoint-Dokumente nach der aktuellen Urlaubsregelung"
"Öffne und lies die Datei 'Mitarbeiterhandbuch.pdf' aus SharePoint"

Tipps für die optimale Nutzung¶

Spezifische Suchbegriffe: Verwende präzise Suchbegriffe für bessere Ergebnisse
Kombinierte Suche: Der Bot kann mehrere Suchvorgänge durchführen, um umfassende Antworten zu geben

Token-Management und Authentifizierung¶

Die SharePoint-Integration verwendet ein Token-Management-System basierend auf Microsoft Entra ID und OAuth 2.0.

Authentifizierungsflow¶

1. Initiale Authentifizierung¶

Wenn eine SharePoint-Integration erstellt wird, läuft folgender Authentifizierungsflow ab:

Autorisierungsanfrage: Der Benutzer klickt auf den "Verbinden"-Button
State-Generierung: Das System generiert einen eindeutigen State-Parameter
Weiterleitung zu Microsoft: Benutzer wird zu Microsoft OAuth-Endpunkt weitergeleitet
Benutzeranmeldung: Anmeldung mit Microsoft-Account
Zustimmung: Benutzer erteilt der Bot-Anwendung die erforderlichen Berechtigungen
Callback-Verarbeitung: Microsoft leitet mit Autorisierungscode zurück
Token-Austausch: Autorisierungscode wird gegen Access Token getauscht

2. Token-Typen¶

Das System verwendet zwei verschiedene Token-Mechanismen:

Interactive Token (OAuth Code Flow):

Wird bei der initialen Verbindung verwendet
Erfordert Benutzerinteraktion
Verwendet für die erste Autorisierung

App-Only Token (Client Credentials Flow):

Wird für laufende API-Anfragen verwendet
Keine Benutzerinteraktion erforderlich
Automatische Verlängerung möglich

Token-Speicherung¶

Datenbank-Storage¶

Tokens werden sicher in der Bot-Konfiguration gespeichert:

{
  "sharepoint": [
    {
      "name": "Haupt-SharePoint",
      "siteUrl": "https://firma.sharepoint.com",
      "clientId": "client-id",
      "tenantId": "tenant-id",
      "clientSecret": "geheim",
      "tokenCache": {
        "accessToken": "verschluesselter-token",
        "expiresOn": 1640995200000,
        "scope": ["https://graph.microsoft.com/.default"],
        "timestamp": 1640991600000
      }
    }
  ]
}

Sicherheitsaspekte¶

Verschlüsselung: Sensible Daten werden verschlüsselt gespeichert
Ablaufzeit: Tokens haben eine definierte Lebensdauer (normalerweise 1 Stunde)
Scope-Beschränkung: Tokens sind auf spezifische Berechtigungen beschränkt

Automatische Token-Verlängerung¶

Smart Token Management¶

Das System implementiert intelligente Token-Verwaltung:

Cache-Prüfung: Vor jeder API-Anfrage wird geprüft, ob ein gültiger Token im Cache vorhanden ist
Ablaufprüfung: Tokens werden auf Ablaufzeit überprüft
Automatische Verlängerung: Abgelaufene Tokens werden automatisch erneuert
Fallback-Mechanismus: Bei Fehlern wird auf gecachten Token zurückgegriffen

Token-Erneuerungsprozess¶

1. API-Anfrage -> Token-Cache pruefen
2. Token abgelaufen? -> Client Credentials Flow
3. Neuer Token -> Cache aktualisieren
4. API-Anfrage mit neuem Token

Error Handling¶

Häufige Authentifizierungsfehler¶

Abgelaufene Tokens: automatische Erneuerung
Ungültige Credentials: Benutzer muss sich erneut authentifizieren
Fehlende Berechtigungen: Admin-Zustimmung erforderlich