Admin-Runbook: SharePoint-Einrichtung (App-only)

Dieses Dokument beschreibt, was ein Microsoft-Entra-Administrator tun muss, damit Silent AI SharePoint-Sites ohne eine Benutzeranmeldung einliest.

Der Konnektor authentifiziert sich als registrierte Anwendung (Dienstidentität) über den OAuth-2.0-client_credentials-Flow mit einem Client-Secret. Er liest die Sites, für die Du ihm Zugriff gewährst, und löst die Berechtigungen jedes Dokuments auf, damit Silent AI die Ergebnisse pro Endbenutzer filtert. Verwende diese Variante, wenn der Konnektor unabhängig von einem einzelnen Konto lesen und einen Personalwechsel überstehen soll. Für den Ablauf, bei dem sich jeder Benutzer einzeln per OAuth anmeldet, verwende stattdessen die App-Registrierung im Azure Portal (OIDC / User Delegated Sign-In).

1. Voraussetzungen

• Du hast Zugriff auf das Microsoft Entra Admin Center und darfst Anwendungen registrieren, Graph-Berechtigungen zustimmen und (bei Sites.Selected) den Zugriff pro Site gewähren. Die Einrichtung ist kein Self-Service.

• Die URL jeder Site, die eingelesen werden soll, zum Beispiel https://<tenant>.sharepoint.com/sites/<name>.

• Ein Konnektor-Manager mit einem Microsoft-Konto, das die Sites lesen darf. Diese Person meldet sich einmal an, damit Silent AI SharePoint-Websitegruppen auflösen kann (siehe Abschnitt 7).

• Für App-only wird keine Redirect-URL benötigt. Der client_credentials-Flow verwendet keine.

• Die zertifikatsbasierte Authentifizierung wird noch nicht unterstützt. Dieses Dokument verwendet ein Client-Secret.

2. App-Registrierung anlegen

1. Öffne das Microsoft Entra Admin Center und melde dich an.

2. Navigiere zu Identity > Applications > App registrations.

3. Klicke auf + New registration.

4. Gib einen Namen ein, zum Beispiel Silent AI SharePoint (app-only).

5. Belasse Supported account types auf Single-Tenant (einzelner Mandant).

6. Lass Redirect URI leer.

7. Klicke auf Register.

8. Notiere auf der Übersichtsseite die Application (client) ID und die Directory (tenant) ID.

3. API-Berechtigungen konfigurieren

Navigiere in der App zu API permissions und füge die folgenden Berechtigungen hinzu. Klicke danach auf Grant admin consent for [Tenant].

Achte auf die Spalte Typ. Eine Registrierung, die nur delegierte Berechtigungen trägt, liefert zwar ein gültiges App-only-Token. Microsoft Graph lehnt damit aber jeden Aufruf ab.

Ohne offline_access liefert Microsoft Entra bei der Anmeldung kein Refresh-Token. Silent AI speichert dann keine Leseidentität, meldet aber keinen Fehler. Die Anmeldung sieht erfolgreich aus, und der Konnektor verhält sich danach wie einer ganz ohne Leseidentität, siehe Abschnitt 9.

Wähle bei den Website-Inhalten genau ein Modell. Sites.Selected gewährt nichts, bis Du der Anwendung in Abschnitt 5 einzelne Sites zuweist. Sites.Read.All ist einfacher im Betrieb, hebt aber die Isolation pro Site auf. Überspringe Abschnitt 5, wenn Du Sites.Read.All verwendest.

Dokumentbibliotheken werden über die Site-Berechtigung gelesen, daher ist kein Files.Read.All erforderlich. Die Tabelle ist damit der vollständige Satz, einschließlich des Verbindungstests aus Abschnitt 8.

AllSites.Read liegt unter Office 365 SharePoint Online, nicht unter Microsoft Graph. SharePoint weist Tokens ab, die eine Anwendung allein aus ihrem Client-Secret bezieht, und antwortet mit 401 Unsupported app only token. Die Websitegruppen einer Site liest Silent AI daher mit der Anmeldung eines Konnektor-Managers, siehe Abschnitt 7.

4. Client Secret anlegen

1. Navigiere zu Certificates & secrets > Client secrets.

2. Klicke auf + New client secret.

3. Vergib eine Beschreibung und wähle eine Ablaufzeit gemäß Deiner Sicherheitsrichtlinie. Notiere das Datum, siehe Abschnitt 9.

4. Klicke auf Add.

5. Kopiere den Wert sofort. Er wird danach nicht mehr angezeigt.

5. Lesezugriff pro Site gewähren (nur Sites.Selected)

Überspringe diesen Abschnitt, wenn Du in Abschnitt 3 Sites.Read.All gewählt hast.

Sites.Selected gewährt nichts, bis Du bestimmte Sites autorisierst. Ermittle zuerst die Site-ID aus der URL:

GET https://graph.microsoft.com/v1.0/sites/{tenant}.sharepoint.com:/sites/{name}

Gewähre der Anwendung dann die Rolle read für diese Site, mit Graph Explorer, PowerShell oder einem beliebigen Client mit Admin-Token:

POST https://graph.microsoft.com/v1.0/sites/{site-id}/permissions Content-Type: application/json { "roles": ["read"], "grantedToIdentities": [ { "application": { "id": "<application-client-id>", "displayName": "Silent AI SharePoint (app-only)" } } ] }

Wiederhole das für jede Site, die eingelesen werden soll.

6. Den Konnektor in Silent AI anlegen

Lege den Konnektor im Formular an und wähle dort Dienstidentität. Das Formular zeigt anschließend die Felder für Tenant ID, Client ID und Client-Secret. Alternativ verwendest Du die Konnektor-API mit auth_mode auf app_only:

POST /api/connector Content-Type: application/json { "name": "SharePoint (app-only)", "connector_type": "msgraph", "credentials": { "type": "msgraph", "tenant_id": "<directory-tenant-id>", "client_id": "<application-client-id>", "client_secret": "<secret-value>", "auth_mode": "app_only" } }

Hinweise:

• auth_mode muss ausdrücklich auf app_only gesetzt werden. Der Standardwert ist delegated.

• Die Authentifizierungsmethode lässt sich nach dem Anlegen nicht mehr ändern. Ein Konnektor mit der falschen Methode muss gelöscht und neu angelegt werden.

• Sende kein refresh_token. App-only-Anmeldedaten enthalten keines. Silent AI erstellt und erneuert die Zugriffstokens selbst.

• connector_type ist msgraph. SharePoint-Konnektoren verwenden den MS-Graph-Typ.

• Die einzulesende Site wird pro Datenquelle festgelegt (deren site_url), nicht am Konnektor. Ein App-only-Konnektor bedient so mehrere gewährte Sites.

Verwende im letzten Schritt des Assistenten die Schaltfläche Konnektor testen, bevor Du den Konnektor anlegst und Datenquellen hinzufügst. Der Test erkennt eine Registrierung ohne Anwendungsberechtigungen sofort, siehe Abschnitt 8.

7. Die Leseidentität für Websitegruppen verbinden

SharePoint vergibt die meisten Rechte in einer Teamwebsite über Websitegruppen, zum Beispiel Mitglieder von <Site>. Eine Websitegruppe ist kein Verzeichnisobjekt. Microsoft Graph nennt sie an einer Datei, listet ihre Mitglieder aber nicht auf. Ohne diesen Abschnitt findet Silent AI zu solchen Dateien keine Benutzer, und niemand sieht sie. Das betrifft jeden Ordner, den eine Person in einer Teamwebsite anlegt, und ist damit der Normalfall und kein Sonderfall.

Öffne den Konnektor in Silent AI und verbinde das Microsoft-Konto eines Konnektor-Managers. Silent AI speichert dabei ein Refresh-Token und liest damit die Mitglieder einer Websitegruppe über die SharePoint-REST-API. Beachte drei Punkte:

• Die Person muss sich an derselben Anwendungsregistrierung anmelden, die Du in Abschnitt 2 angelegt hast. Microsoft Entra löst ein Refresh-Token nur für die Anwendung ein, die es ausgestellt hat.

• Die Registrierung braucht dafür die delegierte Berechtigung AllSites.Read aus Abschnitt 3.

• Silent AI speichert eine Leseidentität pro Konnektor, nicht eine pro Benutzer. Das Token erneuert sich bei jeder Nutzung. Eine regelmäßig genutzte Identität läuft daher nicht ab.

Silent AI prüft die Leseidentität beim Speichern nicht. Ein Fehler zeigt sich erst im ersten Lauf, siehe Abschnitt 9.

8. Überprüfen

Verbindungstest (Test Connection)

Für App-only-MS-Graph steht ein Verbindungstest bereit. Er fordert ein App-only-Token an (client_credentials) und führt genau einen Lesevorgang auf einen Benutzer aus (User.Read.All). Das ist dieselbe Berechtigung, die auch die Berechtigungsauflösung zur Abfragezeit verwendet. Ein erfolgreicher Test spiegelt daher den tatsächlichen Ingestion-Pfad wider.

In der Benutzeroberfläche. Der Assistent zeigt im letzten Schritt die Schaltfläche Konnektor testen, direkt neben der Schaltfläche zum Anlegen. Teste dort, bevor Du den Konnektor anlegst. Einen bereits angelegten Konnektor öffnest Du und verwendest dieselbe Schaltfläche.

Das Ergebnis erscheint im Formular und nennt die Ursache im Klartext, zum Beispiel einen ungültigen oder abgelaufenen Client Secret, eine im Mandanten unbekannte Client ID oder eine fehlende mandantenweite Graph-Berechtigung. Die Schaltfläche erscheint nur bei Dienstidentität. Ein delegierter Konnektor wird über seinen Anmeldevorgang verifiziert, nicht über diesen Test.

Über die API. Rufe den Test alternativ über die API auf, entweder mit den Anmeldedaten aus dem Formular oder mit connector_id für einen bereits angelegten Konnektor:

POST /api/connectors/test-connection Content-Type: application/json { "connector_type": "msgraph", "credentials": { "tenant_id": "<directory-tenant-id>", "client_id": "<application-client-id>", "client_secret": "<secret-value>", "auth_mode": "app_only" } }

auth_mode muss hier ausdrücklich auf app_only gesetzt werden. Fehlt es, gilt der Standardwert delegated, und der Test liefert not_applicable.

Mögliche Ergebnisse der API:

• valid: Token erhalten und Verzeichnis-Lesevorgang erfolgreich.

• invalid: Die Authentifizierung ist fehlgeschlagen. Die Meldung nennt die Ursache anhand des AADSTS-Codes, etwa ein ungültiges oder abgelaufenes Client-Secret, eine im Mandanten unbekannte Client ID oder eine unbekannte Tenant ID.

• could_not_verify: Die Authentifizierung war erfolgreich, aber der Anwendung fehlt die erforderliche Graph-Berechtigung oder die Administratorzustimmung. Oder Microsoft Graph war nicht erreichbar.

• not_applicable: Der Konnektor läuft im Modus delegated. In der Benutzeroberfläche tritt dieser Fall nicht auf, dort blendet Silent AI die Schaltfläche aus.

Der Test prüft die Anmeldedaten und die mandantenweiten Graph-Berechtigungen, nicht die Freigabe einzelner Sites unter Sites.Selected. Der Zugriff pro Site wird erst beim Einlesen überprüft, siehe Abschnitt 5.

Überprüfung per Discovery-Lauf

• Füge eine Datenquelle für eine der gewährten Sites hinzu und starte die Erkennung (Discovery). Die Erkennung listet die Dokumentbibliotheken dieser Site auf.

• Eine Site, die Du nicht gewährt hast (unter Sites.Selected), meldet keinen Fehler. Microsoft Graph liefert die Site und danach eine leere Liste von Dokumentbibliotheken. Der Lauf endet mit NO_ITEMS_DISCOVERED und sieht damit aus wie eine Site ohne Inhalt. Prüfe in diesem Fall zuerst die Freigabe aus Abschnitt 5.

• Die eingelesenen Ergebnisse lassen sich pro Endbenutzer filtern, was bestätigt, dass die Berechtigungen User.Read.All und GroupMember.Read.All die Dokumentberechtigungen aufgelöst haben.

• Jeder Endbenutzer verbindet sein eigenes Microsoft-Konto mit dem Konnektor. Erst danach sieht er Ergebnisse. Silent AI leitet die Identität nicht mehr aus dem Silent-AI-Benutzernamen ab, weil ein Benutzername keine verlässliche Angabe der Microsoft-Identität ist.

9. Fehlerbehebung

• Die Authentifizierung funktioniert nach einigen Wochen nicht mehr. Das Client-Secret ist abgelaufen (das in Abschnitt 4 festgelegte Datum). Rotiere es vor Ablauf: Erstelle ein neues Secret (Abschnitt 4), aktualisiere den vorhandenen Konnektor mit PATCH /connector/{connector_id} und sende dabei nur das neue client_secret, und entferne anschließend das alte Secret. Führe nicht erneut den POST aus Abschnitt 6 aus, das legt einen zweiten Konnektor an. Die Rotation des Client-Secrets ist ein betriebliches Risiko, bis die Zertifikatsunterstützung verfügbar ist.

• Ein Discovery- oder Extraktionslauf schlägt fehl, statt Teilergebnisse zu liefern. Silent AI hält ein App-only-Zugriffstoken zwischen und verwendet es bis zu seinem Ablauf. Läuft es ab, während der Microsoft-Token-Endpunkt (login.microsoftonline.com) nicht erreichbar ist, schlägt der Lauf fehl. App-only-Anmeldedaten haben kein Refresh-Token, mit dem Silent AI die Unterbrechung überbrücken könnte. Wiederhole den Vorgang, sobald der Endpunkt wieder erreichbar ist.

• Ein Lauf findet keine Dokumente auf einer Site. Unter Sites.Selected wurde der Anwendung diese Site nicht gewährt. Microsoft Graph antwortet darauf nicht mit einem Fehler, sondern mit einer leeren Liste von Dokumentbibliotheken. Eine fehlende Freigabe sieht deshalb genauso aus wie eine leere Site. Gewähre die Site in Abschnitt 5. Erweitere die Anwendung nicht auf Sites.Read.All, es sei denn, der mandantenweite Lesezugriff ist Dein gewähltes Modell.

• Die Erkennung schlägt mit „Insufficient privileges to complete the operation“ fehl, oder die Ergebnisse werden nicht pro Benutzer gefiltert. Der Anwendung fehlen Anwendungsberechtigungen aus Abschnitt 3. Eine Registrierung, die nur delegierte Berechtigungen trägt, liefert ein gültiges Token, das Microsoft Graph dann bei jedem Aufruf ablehnt. Fehlt dagegen nur GroupMember.Read.All, läuft die Erkennung durch, aber die Dokumentberechtigungen werden nicht auf Silent-AI-Identitäten aufgelöst. Der Verbindungstest (Abschnitt 8) erkennt den ersten Fall. Den zweiten erkennt er nicht, weil er nur einen Benutzer liest. Füge die Berechtigungen in Abschnitt 3 hinzu und stimme erneut zu (re-consent), oder verwende die Registrierung aus Abschnitt 2.

• Ein Lauf meldet, die Leseidentität für Websitegruppen fehle oder sei unbrauchbar. Der Registrierung fehlt offline_access, sodass die Anmeldung kein Refresh-Token liefert, oder sie besitzt die delegierte Berechtigung AllSites.Read nicht, oder der Konnektor-Manager hat sich an einer anderen Registrierung angemeldet. Ergänze die Berechtigung in Abschnitt 3, stimme erneut zu und verbinde das Konto in Abschnitt 7 noch einmal.

• Ein Benutzer sieht einzelne Dateien nicht, obwohl der Lauf erfolgreich war. Die Datei ist nur über eine Websitegruppe freigegeben, und der Konnektor besitzt keine Leseidentität. Führe Abschnitt 7 aus und lies die Datenquelle erneut ein.

• Ein Lauf ist erfolgreich, liefert aber weniger Dokumente als erwartet. Silent AI liest die besitzende Site eines Laufwerks einmal pro Laufwerk. Schlägt dieser Aufruf fehl, lässt Silent AI die betroffenen Dokumente aus, statt sie ohne passende Berechtigung einzulesen. Die Benutzeroberfläche zeigt diesen Fall nicht an. Die Anzahl der ausgelassenen Dokumente steht nur im Protokoll des Backends. Wiederhole den Lauf. Bleibt der Fehler, prüfe die Berechtigungen aus Abschnitt 3.

10. Zugriff widerrufen

• Pro Site: Entferne die Berechtigung der Anwendung für diese Site (DELETE /sites/{site-id}/permissions/{permission-id}). Die Anwendung verliert den Zugriff auf genau diese Site, alle anderen bleiben bestehen.

• Mandantenweit: Microsoft Entra Admin Center → Enterprise applications → Silent AI-App suchen → Delete (oder Berechtigungen entfernen). Die Anwendung verliert jeden Zugriff.

• Nur die Anmeldedaten: Entferne das Client-Secret unter Certificates & secrets. Der nächste Lauf schlägt fehl, die Registrierung bleibt bestehen.

• Die Leseidentität: Der Konnektor-Manager widerruft seine Einwilligung unter My Apps → App auswählen → Remove. Das Refresh-Token wird ungültig, und Silent AI expandiert keine Websitegruppen mehr. Silent AI bietet keine eigene Schaltfläche dafür. Eine erneute Anmeldung eines Konnektor-Managers ersetzt die gespeicherte Identität.

App-only kennt keine Einwilligung pro Benutzer. Die Anwendung liest weiter, bis ein Administrator einen der Punkte oben ausführt.

11. Weiterführende Links

• Microsoft Docs – App registrieren

• Microsoft Docs – Client Credentials Flow

• Microsoft Docs – App-only-Zugriff auf SharePoint

• Microsoft Graph Permissions Reference

• Microsoft Graph Explorer