Download the PHP package hwkdo/ms-graph-laravel without Composer

Microsoft Graph Laravel

Ein Laravel Package für die Integration mit Microsoft Graph API. Dieses Package bietet eine umfassende Lösung für die Verwaltung von Microsoft 365-Diensten wie Benutzer, E-Mails, OneDrive, Lizenzen und Abwesenheitsvorlagen.

Installation

Sie können das Package über Composer installieren:

Sie können die Migrationen veröffentlichen und ausführen:

Sie können die Konfigurationsdatei veröffentlichen:

Webhook-Job-Mappings initialisieren

Das Package enthält einen Seeder, um die Standard-Webhook-Job-Mappings zu erstellen:

Alternativ können Sie den Seeder in Ihrem DatabaseSeeder registrieren:

Der Seeder erstellt automatisch Mappings für folgende Webhook-Typen:

• intracollect - Formwerk Mail Webhooks für IntraCollect
• angebote - Bestellungen und Angebote Webhooks
• ntopng - Ntopng Webhooks
• onedrive_filer - OneDrive Filer Webhooks
• onedrive_filerextern - Externe OneDrive Filer Webhooks

Die Notification URLs werden automatisch basierend auf der PORTAL_URL Umgebungsvariable generiert.

Konfiguration

Fügen Sie die folgenden Umgebungsvariablen zu Ihrer .env-Datei hinzu:

Delegated Permissions (User-Token)

App-only (MSGRAPH_APP_ID / Client Credentials) bleibt der Default für Admin- und Hintergrundjobs.

Für Calls im Namen des eingeloggten Users (z. B. Cloudshare) nutzt das Package den Socialite-Token der Login-App (MICROSOFT_CLIENT_ID):

1. Entra an der Login-App (nicht an MSGRAPH_APP_ID): Delegated User.Read, Files.ReadWrite, offline_access
2. Admin-Consent für den Tenant
3. Socialite-Login muss Access Token, Refresh Token, Ablauf und Scopes am User speichern
4. MsGraphDelegatedOneDriveFactoryInterface::forUser($user) liefert einen OneDrive-Client mit Bearer-User-Token

Nach Scope-Änderungen müssen User einmal neu per Microsoft einloggen. Falls createLink im Tenant scheitert, zusätzlich Delegated Files.ReadWrite.All gewähren.

Teams Bot Einrichtung

Der Teams-Bot nutzt den Docker-Service external/teams-sdk-rest (Microsoft Teams SDK v2).

1. App Registration für den Bot anlegen (getrennt von MSGRAPH_APP_ID)
2. Azure Bot (Bot Channels Registration) mit Microsoft App ID = Bot App ID
   • Messaging Endpoint: https://<teams-sdk-rest-host>/api/messages
   • Kanal Microsoft Teams aktivieren
3. teams-sdk-rest starten und konfigurieren (TEAMS_API_KEY, LARAVEL_WEBHOOK_URL, WELCOME_MESSAGE, …)
4. Laravel Webhook: {PORTAL_URL}/api/kunden/ms-graph-laravel/teams-webhook

5. Teams App Manifest (manifest.json + Icons): bots[].botId und webApplicationInfo.id = Bot App ID

   Wichtig: Ohne webApplicationInfo.id schlägt die Installation mit [Forbidden] Caller is not authorized fehl. Für die App-Validierung im Developer Portal commandLists mit Befehl Hi ergänzen:

   Der Webhook sendet automatisch eine Welcome-Nachricht (personal scope) und antwortet auf Hi.

6. App im Teams Admin Center in den Organisations-App-Katalog hochladen (nach Manifest-Änderung erneut!)
7. API Permissions (Application): TeamsAppInstallation.ReadWriteSelfForUser.All + Admin Consent
   • Alternative bei anhaltendem „Caller is not authorized“: TeamsAppInstallation.ReadWriteForUser.All
8. Env-Variablen setzen und MSGRAPH_TEAMS_BOT_ENABLED=true
   • MSGRAPH_TEAMS_APP_CATALOG_ID = id aus Graph/Katalog nach Upload (kann sich nach Neuveröffentlichung ändern!)

Azure Setup

1. Erstellen Sie eine App-Registrierung im Azure Portal
2. Erstellen Sie einen Client Secret für die App
3. Weisen Sie die erforderlichen Microsoft Graph-Berechtigungen zu:
   • User.Read.All - Für Benutzerverwaltung
   • Mail.Read - Für E-Mail-Zugriff
   • Files.Read.All - Für OneDrive-Zugriff
   • License.Read.All - Für Lizenzverwaltung
   • Presence.Read.All - Für Anwesenheitsstatus

Verwendung

Facade verwenden

Dependency Injection verwenden

Verfügbare Services

UserService

Verwaltung von Microsoft 365-Benutzern:

LicenseService

Verwaltung von Microsoft 365-Lizenzen:

MailboxService

E-Mail-Verwaltung:

OneDriveService

OneDrive-Dateiverwaltung:

OutOfOfficeTemplateService

Abwesenheitsvorlagen-Verwaltung:

Artisan Commands

Das Package stellt folgende Artisan-Befehle zur Verfügung:

Webhook-Subscriptions

Das Package unterstützt Microsoft Graph Webhook-Subscriptions für Echtzeit-Updates.

Webhook-Job-Mappings

Webhook-Subscriptions werden in der Datenbank verwaltet. Jede Subscription ist mit einem Job verknüpft, der ausgeführt wird, wenn ein Webhook empfangen wird.

Neue Webhook-Subscription hinzufügen

Webhook-Subscription abrufen

Webhook-Job erstellen

Ihr Webhook-Job sollte die empfangenen Daten verarbeiten:

Webhook-Endpoint

Das Package registriert automatisch einen Webhook-Endpoint unter:

Microsoft Graph sendet Webhooks an diese URL. Der {typ} Parameter bestimmt, welcher Job ausgeführt wird.

Features

Microsoft Graph Integration

• Automatische Token-Verwaltung: OAuth-Tokens werden automatisch abgerufen, gecacht und erneuert
• Mehrere App-Registrierungen: Unterstützung für verschiedene Microsoft Graph-Anwendungen
• Umfassende API-Abdeckung: Benutzer, E-Mails, OneDrive, Lizenzen, Teams und mehr

Services

• UserService: Vollständige Benutzerverwaltung mit UPN- und Alias-Suche
• LicenseService: Lizenzverwaltung und -überwachung
• MailboxService: E-Mail-Verwaltung und -verarbeitung
• OneDriveService: Datei-Upload, -Download und -verwaltung
• OutOfOfficeTemplateService: Abwesenheitsvorlagen-Management

Webhooks & Subscriptions

• Echtzeit-Updates: Webhook-Subscriptions für E-Mails und OneDrive
• Automatische Verwaltung: Subscription-Lebenszyklus wird automatisch verwaltet
• Mehrere Endpunkte: Unterstützung für verschiedene Webhook-Endpunkte

Allgemein

• Laravel HTTP Client: Verwendet Laravels eingebauten HTTP-Client für alle Anfragen
• Umfassendes Logging: Alle Operationen werden für Debugging-Zwecke geloggt
• Exception Handling: Ordnungsgemäße Fehlerbehandlung mit detaillierten Fehlermeldungen
• Caching: Konfigurierbare Cache-Zeiten für bessere Performance

API-Referenz

UserService

getUser(string $mail): ?User

Ruft einen Benutzer anhand der E-Mail-Adresse ab.

Parameter:

• $mail: E-Mail-Adresse des Benutzers

Rückgabe: Microsoft Graph User-Objekt oder null

getUserByUpn(string $upn): User

Ruft einen Benutzer anhand des UPN (User Principal Name) ab.

Parameter:

• $upn: UPN des Benutzers

Rückgabe: Microsoft Graph User-Objekt

getUserByAlias(string $alias): ?User

Ruft einen Benutzer anhand des Alias ab.

Parameter:

• $alias: Alias des Benutzers

Rückgabe: Microsoft Graph User-Objekt oder null

update(string $upn, array $data): User

Aktualisiert Benutzerdaten.

Parameter:

• $upn: UPN des Benutzers
• $data: Zu aktualisierende Daten

Rückgabe: Aktualisiertes Microsoft Graph User-Objekt

getUserPresence(string $upn): Presence

Ruft den Anwesenheitsstatus eines Benutzers ab.

Parameter:

• $upn: UPN des Benutzers

Rückgabe: Microsoft Graph Presence-Objekt

getUserTeams(string $upn): array

Ruft die Teams eines Benutzers ab.

Parameter:

• $upn: UPN des Benutzers

Rückgabe: Array von Microsoft Graph Team-Objekten

getUserDirectGroups(string $upn): array

Ruft die direkten Gruppen eines Benutzers ab.

Parameter:

• $upn: UPN des Benutzers

Rückgabe: Array von Microsoft Graph Group-Objekten

getUserTransitiveGroups(string $upn): array

Ruft die transitiven Gruppen eines Benutzers ab.

Parameter:

• $upn: UPN des Benutzers

Rückgabe: Array von Microsoft Graph Group-Objekten

LicenseService

getLicenseDetails(string $upn): array

Ruft die Lizenzdetails eines Benutzers ab.

Parameter:

• $upn: UPN des Benutzers

Rückgabe: Array von Microsoft Graph LicenseDetails-Objekten

Testing

Changelog

Bitte sehen Sie CHANGELOG für weitere Informationen zu den letzten Änderungen.

Contributing

Bitte sehen Sie CONTRIBUTING für Details.

Security Vulnerabilities

Bitte überprüfen Sie unsere Sicherheitsrichtlinie, wie Sicherheitslücken gemeldet werden.

Credits

• hwkdo
• Alle Contributors

License

Die MIT-Lizenz (MIT). Bitte sehen Sie License File für weitere Informationen.