From 7b8b01917f47e86886036ff253031615afbda26a Mon Sep 17 00:00:00 2001 From: Christian Mueller Date: Sun, 3 May 2026 09:18:41 +0200 Subject: [PATCH] docs: Azure Entra ID Einrichtungsanleitung fuer Onboarding Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/azure-einrichtung.md | 151 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 docs/azure-einrichtung.md diff --git a/docs/azure-einrichtung.md b/docs/azure-einrichtung.md new file mode 100644 index 0000000..5b47eb5 --- /dev/null +++ b/docs/azure-einrichtung.md @@ -0,0 +1,151 @@ +# Azure Entra ID Einrichtung fuer Busylight + +Schritt-fuer-Schritt Anleitung zur Einrichtung der Azure App-Registrierung fuer das Busylight-System. +Das Busylight nutzt die Microsoft Graph API, um den Teams-Presence-Status der Mitarbeiter abzufragen. + +## Voraussetzungen + +- Zugang zum Azure Portal (https://portal.azure.com) mit Admin-Rechten +- Azure Entra ID (ehemals Azure AD) Lizenz (in Microsoft 365 Business enthalten) +- Microsoft Teams muss im Einsatz sein + +## 1. App-Registrierung erstellen + +1. Azure Portal oeffnen: https://portal.azure.com +2. Navigieren zu: **Microsoft Entra ID** > **App-Registrierungen** > **Neue Registrierung** +3. Folgende Werte eintragen: + +| Feld | Wert | +|------|------| +| **Name** | `Busylight` (oder z.B. `Busylight cynfo`) | +| **Unterstuetzte Kontotypen** | *Nur Konten in diesem Organisationsverzeichnis* | +| **Umleitungs-URI** | leer lassen | + +4. Auf **Registrieren** klicken + +### IDs notieren + +Nach der Registrierung auf der Uebersichtsseite zwei Werte kopieren: + +- **Anwendungs-ID (Client-ID)** - z.B. `1c3d0eef-a003-4e8d-9f4b-02b6cb2eeb1b` +- **Verzeichnis-ID (Mandanten-ID / Tenant-ID)** - z.B. `6a0349fc-7bb3-4868-a711-27a0d1c58c83` + +## 2. Oeffentliche Clientflows aktivieren + +1. In der App-Registrierung: **Authentifizierung** (linkes Menue) +2. Ganz nach unten scrollen zu **Erweiterte Einstellungen** +3. **Oeffentliche Clientflows zulassen** auf **Ja** setzen +4. **Speichern** klicken + +> **Warum?** Das Busylight authentifiziert sich ueber den Device-Code-Flow. +> Dabei wird ein Code im Terminal angezeigt, den man im Browser eingibt. +> Dafuer muessen oeffentliche Clientflows aktiviert sein. + +## 3. API-Berechtigungen setzen + +1. **API-Berechtigungen** > **Berechtigung hinzufuegen** > **Microsoft Graph** +2. **Delegierte Berechtigungen** waehlen +3. Folgende Berechtigungen suchen und hinzufuegen: + +| Berechtigung | Zweck | +|-------------|-------| +| `User.Read` | Angemeldeten Benutzer lesen | +| `User.Read.All` | Alle Benutzer aus dem Verzeichnis lesen | +| `Presence.Read` | Eigenen Presence-Status lesen | +| `Presence.Read.All` | Presence-Status aller Benutzer lesen | + +4. **Administratorzustimmung erteilen** klicken (gruener Haken muss bei allen erscheinen) + +> **Wichtig:** Ohne Administratorzustimmung koennen die Berechtigungen nicht genutzt werden. +> Es reicht nicht, die Berechtigungen nur hinzuzufuegen. + +## 4. Busylight konfigurieren + +### Ueber das Web-Interface + +1. Busylight Web-UI oeffnen (z.B. `http://SERVER:8080/settings`) +2. Folgende Felder ausfuellen: + +| Feld | Wert | +|------|------| +| **Client ID** | Die Anwendungs-ID aus Schritt 1 | +| **Tenant ID** | Die Verzeichnis-ID aus Schritt 1 | +| **Auth Tenant** | Die Verzeichnis-ID (gleicher Wert wie Tenant ID) | +| **Graph Scopes** | `User.Read User.Read.All Presence.Read Presence.Read.All` | + +3. Speichern + +### Alternativ per CLI + +```bash +cd /opt/busylight && source venv/bin/activate +python -c " +from database import init_db, set_setting +init_db() +set_setting('azure_client_id', 'DEINE-CLIENT-ID') +set_setting('azure_tenant_id', 'DEINE-TENANT-ID') +set_setting('azure_auth_tenant', 'DEINE-TENANT-ID') +" +``` + +## 5. Azure Authentifizierung durchfuehren + +Die Authentifizierung erfolgt einmalig ueber den Device-Code-Flow im Terminal: + +```bash +cd /opt/busylight && source venv/bin/activate +python -W ignore -c " +import logging +logging.getLogger('azure').setLevel(logging.WARNING) +from app import cli_auth +cli_auth() +" +``` + +Es erscheint eine Meldung wie: + +``` +To sign in, use a web browser to open the page https://microsoft.com/devicelogin +and enter the code LW5ZR5BFC to authenticate. +``` + +1. Browser oeffnen: https://microsoft.com/devicelogin +2. Den angezeigten Code eingeben +3. Mit einem Azure-Konto anmelden (muss ein Benutzer des Tenants sein) +4. Berechtigung bestaetigen + +Nach erfolgreicher Anmeldung wird das Token in der Datenbank gespeichert und automatisch erneuert. + +> **Hinweis:** Die Sidebar im Web-Interface zeigt danach **"Azure verbunden"** (gruen) an. + +## 6. Benutzer synchronisieren + +1. Im Web-Interface zu **Benutzer** navigieren +2. Auf **"Aus Azure synchronisieren"** klicken +3. Alle Benutzer aus dem Verzeichnis werden importiert +4. Nicht benoetigte Benutzer (Service-Accounts, Raeume, etc.) deaktiviert lassen +5. Fuer aktive Benutzer die **Telefon-Durchwahl** eintragen (fuer Starface-Webhook) + +## Fehlerbehebung + +### "Azure getrennt" trotz Authentifizierung + +- Service neustarten: `sudo systemctl restart busylight` +- Erneut authentifizieren: `python app.py --auth` (loescht alten Token automatisch) + +### Authentifizierung schlaegt fehl + +- **"AADSTS7000218"**: Oeffentliche Clientflows sind nicht aktiviert (Schritt 2) +- **"AADSTS700016"**: Client-ID ist falsch +- **"AADSTS90002"**: Tenant-ID ist falsch oder Auth-Tenant steht auf `common` statt der Tenant-ID + +### Berechtigungsfehler beim Presence-Abruf + +- API-Berechtigungen pruefen: Sind alle 4 Berechtigungen eingetragen? +- Administratorzustimmung erteilt? (gruener Haken in Azure) +- Hat der authentifizierte Benutzer eine Teams-Lizenz? + +### Token laeuft ab + +- Das Token wird automatisch erneuert, solange der Service laeuft +- Bei laengerer Downtime (>90 Tage) muss erneut authentifiziert werden