busylight_modular/docs/azure-einrichtung.md

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

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:

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