# 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