Microsoft 365 — Anleitung für IT

Für Microsoft-Administratoren im Kundenbüro. Endnutzer: Microsoft 365 verbinden.

Voraussetzungen

• Microsoft 365 mit Exchange Online (Cloud-Postfach)
• On-Prem-Mailboxen ohne Exchange Online werden nicht unterstützt

1. Entra App-Registrierung

1. Azure Portal → Microsoft Entra ID → App registrations → New registration

2. Name: z. B. GutachtenOS — Ihr Büroname

3. Supported account types: Single tenant

4. Redirect URI (Web):

   https://gutachtenos.pxl.systems/api/integrations/microsoft/callback

5. Optional für Entra-Login (SSO): zweite Redirect URI
   https://gutachtenos.pxl.systems/api/auth/entra/callback

API Permissions (Delegated)

Permission	Zweck
offline_access	Refresh Token
User.Read	Verbunden-als-Anzeige
Mail.Read	Posteingang in GutachtenOS
Calendars.ReadWrite	Termine ↔ Outlook
Files.ReadWrite.All	SharePoint-Upload
Sites.ReadWrite.All	SharePoint-Sites

→ Grant admin consent für die Organisation.

Client Secret

Certificates & secrets → New client secret → Wert einmalig kopieren.

Notieren: Directory (tenant) ID, Application (client) ID, Client secret.

2. GutachtenOS konfigurieren

Büro-Admin (tenant_admin) in der App:

1. Einstellungen → Microsoft 365 (/dashboard/einstellungen/microsoft)
2. Azure Tenant ID, Client ID, Client Secret eintragen
3. SharePoint Drive ID (Document Library der Aktenablage) und Basisordner (z. B. GutachtenOS)
4. Speichern → Mit Microsoft verbinden → Admin-Konto autorisieren
5. Verbindung testen — Meldung mit Mailbox-Adresse

Empfohlene Optionen:

• E-Mails automatisch verknüpfen
• SharePoint Auto-Sync

3. SharePoint Drive-ID

Im Graph Explorer (als Admin):

GET https://graph.microsoft.com/v1.0/sites/:hostname:/:/site-path:/drives

Pro Akte legt GutachtenOS Unterordner mit der Aktennummer unter dem konfigurierten Basisordner an.

4. Smoke-Test

#	Aktion	Erwartung
1	Einstellungen → Microsoft 365	„Verbunden als …“
2	E-Mails (/dashboard/emails)	Outlook-Nachrichten laden
3	Testmail mit Aktenzeichen	Verknüpfungsvorschlag im Posteingang
4	Akte → Termin anlegen	Outlook-Eintrag (bei Kalender-Sync)
5	Akte → Dokument hochladen	SharePoint-Sync ok (bei Drive-ID)

Fehlerbilder

Symptom	Ursache	Fix
Posteingang leer / not_connected	OAuth abgelaufen	Neu verbinden
403 Graph	Fehlende Admin Consent	Permissions + Consent
SharePoint sync error	Falsche Drive-ID / Site-Rechte	Drive-ID und Berechtigung prüfen