152 lines
5.1 KiB
Markdown
152 lines
5.1 KiB
Markdown
# 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
|