# Microsoft E-Mail & Outlook-Kalender – Einrichtung als Admin Diese Anleitung beschreibt, wie Sie als Microsoft-Administrator ein Konto und eine App-Registrierung einrichten, damit die Anwendung: - **Outlook-Kalender** per OAuth nutzen kann (Slots, Buchungen, Sync), - optional **E-Mails** per SMTP/IMAP mit diesem Konto senden und empfangen kann. --- ## Was muss ich genau tun? (Kurzantwort) **Kommt darauf an, ob die Auth schon läuft:** | Situation | Was Sie tun müssen | |-----------|--------------------| | **OAuth läuft schon** – In der `.env` stehen `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`, `MICROSOFT_TENANT_ID`, `MICROSOFT_REDIRECT_URI` und unter **Admin → Outlook-Integration** ist mindestens ein Konto verbunden. | **Nur die E-Mail eintragen bzw. das Konto verbinden.** Azure und die „Auth-Sachen“ brauchen Sie **nicht nochmal**. Sie gehen in die App → Admin → Outlook-Integration → „Mit Microsoft anmelden“ / „Konto verbinden“ → melden sich mit dem **weiteren** Konto an (z. B. `bz@ksb-dueren.de`). Optional in `.env`: `EVENT_CENTER_OUTLOOK_EMAIL=bz@ksb-dueren.de` eintragen, damit das Bewegungszentrum genau dieses Konto nutzt. **Nach Änderung dieser Variable:** `php bin/console cache:clear` ausführen, damit die Anwendung den neuen Wert verwendet. Fertig. | | **OAuth ist noch nicht da** – Neue Installation, oder die vier Microsoft-Variablen fehlen / funktionieren nicht (z. B. Fehler beim Verbinden). | **Komplette Einrichtung:** Azure-App anlegen (Abschnitte 2–4), die vier Werte in `.env` eintragen, dann in der App das erste Konto verbinden (Abschnitt 6). Die „Auth-Sachen“ (Client ID, Secret, Tenant, Redirect URI) brauchen Sie **einmal**; danach können Sie **beliebig viele** Outlook-Konten über dieselbe App verbinden. | **Zusammengefasst:** - **Nur ein weiteres Outlook-Konto hinzufügen (z. B. für Bewegungszentrum)?** → Nur in der App verbinden + optional `EVENT_CENTER_OUTLOOK_EMAIL` in `.env`. Keine Azure-Schritte. - **Erstmalig einrichten oder Auth kaputt?** → Ganze Anleitung durchgehen (Azure + .env + Konto verbinden). --- ## Wichtig: Die .env hat bereits mehrere E-Mail-Variablen In Ihrer `.env` gibt es **bereits** E-Mail- und Kalender-relevante Einträge. Die Microsoft-Einrichtung **ersetzt** diese nicht pauschal – sie **ergänzt** bzw. **verwendet** sie. Übersicht: | Variable | Zweck | Typisch bereits gesetzt? | |----------|--------|---------------------------| | **MAILER_DSN** | E-Mails **senden** (SMTP, z. B. Buchungsbestätigungen) | Ja (z. B. buchung@…) | | **MAILER_FROM** | Absenderadresse für ausgehende E-Mails | Ja | | **ADMIN_EMAIL** | Empfänger für System-/Admin-Benachrichtigungen | Ja | | **IMAP_*** | E-Mails **empfangen** (Postfach lesen) | Ja, falls genutzt | | **SMTP_*** (Legacy)** | Ältere SMTP-Konfiguration (Fallback) | Optional | | **EVENT_CENTER_OUTLOOK_EMAIL** | Welches **Outlook-Konto** für Bewegungszentrum/Geburtstage (Kalender) | Optional (z. B. bz@…) | | **MICROSOFT_CLIENT_ID / _SECRET / _TENANT_ID / _REDIRECT_URI** | **OAuth** für Outlook-Kalender (eine App für alle verbundenen Konten) | Einmal pro App-Registrierung | **Praktisch:** - **Neue Azure-App nur für Kalender:** Nur die vier Variablen `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`, `MICROSOFT_TENANT_ID`, `MICROSOFT_REDIRECT_URI` eintragen oder anpassen. Bestehende E-Mail-Adressen (MAILER_DSN, MAILER_FROM, ADMIN_EMAIL, IMAP_*) **unverändert lassen**. - **Neues Konto nur für Kalender (z. B. Bewegungszentrum):** Dieses Konto in der App unter Admin → Outlook-Integration verbinden und optional `EVENT_CENTER_OUTLOOK_EMAIL=bz@ksb-dueren.de` setzen. E-Mail-Versand kann weiter über das **bestehende** Konto (MAILER_DSN) laufen. - **Neues Konto auch für E-Mail:** Dann zusätzlich MAILER_DSN, MAILER_FROM, ggf. IMAP_* und ADMIN_EMAIL auf das neue Konto umstellen (und App-Kennwort für SMTP/IMAP verwenden). Falls in Ihrer `.env` zusätzlich **MICROSOFT_OAUTH_***-Variablen vorkommen: Das kann eine zweite/ältere App oder Legacy-Konfiguration sein. Für die Outlook-Integration nutzt die Anwendung die Werte aus **MICROSOFT_CLIENT_*** (siehe `config/packages/outlook_calendar.yaml`). Halten Sie entweder nur einen Satz (MICROSOFT_CLIENT_*) oder beide konsistent, je nachdem was Ihr Deployment erwartet. --- ## Übersicht | Schritt | Wo | Zweck | |--------|-----|--------| | 1 | Microsoft 365 Admin Center | Postfach/Konto anlegen (optional, falls neues Konto) | | 2 | Azure Portal (Microsoft Entra ID) | App-Registrierung für OAuth | | 3 | Azure Portal | Redirect URI, API-Berechtigungen, Client Secret | | 4 | .env der Anwendung | Client ID, Secret, Tenant ID, Redirect URI eintragen | | 5 | Optional | App-Kennwort für SMTP/IMAP (falls E-Mail über dasselbe Konto) | --- ## 1. Microsoft-Konto (Postfach) Falls Sie ein **neues** Konto nur für Kalender/E-Mail nutzen wollen (z. B. `bewegungszentrum@ihre-domain.de`): 1. Öffnen Sie das **Microsoft 365 Admin Center**: [admin.microsoft.com](https://admin.microsoft.com) 2. **Benutzer** → **Aktive Benutzer** → **Benutzer hinzufügen** 3. Name, Benutzername (E-Mail), Passwort und ggf. Lizenz vergeben 4. Speichern Ein **bereits vorhandenes** Konto (z. B. `buchung@ksb-dueren.de` oder `mobi@ksb-dueren.de`) können Sie direkt für OAuth und ggf. E-Mail verwenden – es muss nur in Ihrem Microsoft 365 / Azure AD (Entra ID) existieren. --- ## 2. App-Registrierung in Azure (Microsoft Entra ID) Die Anwendung braucht eine **App-Registrierung**, um sich per OAuth bei Microsoft anzumelden und auf Kalender zuzugreifen. 1. Öffnen Sie das **Azure Portal**: [portal.azure.com](https://portal.azure.com) 2. Melden Sie sich mit einem Konto an, das **Administrator-Rechte** in Ihrer Organisation hat (Globaler Administrator oder Anwendungsadministrator). 3. Suchen Sie nach **„Microsoft Entra ID“** (früher: Azure Active Directory) und öffnen Sie den Dienst. 4. Links im Menü: **Anwendungen** → **App-Registrierungen** → **Neue Registrierung**. ### Registrierung ausfüllen | Feld | Wert | |------|------| | **Name** | z. B. `KSB Kursverwaltung Outlook` (frei wählbar) | | **Unterstützte Kontotypen** | **Nur Konten in diesem Organisationsverzeichnis** (Single Tenant), sofern nur Ihre Organisation die App nutzt | | **Umleitungs-URI** | vorerst leer lassen – kommt in Schritt 3 | Auf **Registrieren** klicken. Nach der Erstellung sehen Sie die Übersichtsseite der App. Notieren Sie: - **Anwendungs-ID (Client-ID)** → kommt später in `.env` als `MICROSOFT_CLIENT_ID` - **Verzeichnis-ID (Mandanten-ID)** → kommt später in `.env` als `MICROSOFT_TENANT_ID` --- ## 3. Redirect URI und API-Berechtigungen ### 3.1 Umleitungs-URI (Redirect URI) 1. In der App-Registrierung: **Authentifizierung** öffnen. 2. **Plattform hinzufügen** → **Web**. 3. **Umleitungs-URIs**: - Tragen Sie die **exakte** Callback-URL Ihrer Anwendung ein, z. B.: - `https://ihre-domain.de/admin/outlook/callback` - oder `https://dp-smartsolutions.de/ksbdueren/public/admin/outlook/callback` (je nach Basis-URL und Pfad Ihrer Installation; keine abschließende Slash.) 4. Unter **Erweiterte Einstellungen**: **Zugriffstoken** und **ID-Token** müssen für den impliziten Ablauf **nicht** aktiviert sein (die App nutzt Authorization Code Flow). 5. **Konfigurieren** speichern. Die eingetragene URL ist Ihre **Redirect URI** und muss in `.env` als `MICROSOFT_REDIRECT_URI` **exakt** übereinstimmen. ### 3.2 API-Berechtigungen 1. In der App-Registrierung: **API-Berechtigungen** öffnen. 2. **Berechtigung hinzufügen**. 3. **Microsoft Graph** auswählen. 4. **Delegierte Berechtigungen** auswählen und folgende hinzufügen: | Berechtigung | Zweck | |--------------|--------| | **User.Read** | Benutzerprofil/E-Mail des angemeldeten Kontos lesen | | **Calendars.ReadWrite** | Kalender lesen und Termine erstellen/aktualisieren | | **offline_access** | Refresh-Token für längerfristigen Zugriff (Sync) | 5. **Berechtigungen hinzufügen** bestätigen. **Admin-Zustimmung (empfohlen):** - Auf **Administratorzustimmung für [Ihre Organisation] erteilen** klicken, damit alle Nutzer der App nicht einzeln zustimmen müssen. - Nach der Zustimmung sollten die Berechtigungen mit „Gewährt für …“ angezeigt werden. --- ## 4. Client Secret erstellen Die Anwendung benötigt ein **Client Secret** für den OAuth-Austausch am Server. 1. In der App-Registrierung: **Zertifikate & Geheimnisse** öffnen. 2. **Neuer geheimer Clientschlüssel**. 3. Beschreibung (z. B. „Kursverwaltung Outlook“) und Ablauf (z. B. 24 Monate) wählen. 4. **Hinzufügen**. 5. **Wert** des Geheimnisses **sofort kopieren** und sicher aufbewahren – er wird nur einmal angezeigt. Dieser Wert ist Ihr **Client Secret** und kommt in `.env` als `MICROSOFT_CLIENT_SECRET`. Niemals in Git oder öffentlich ablegen. --- ## 5. Werte in der Anwendung eintragen (.env) Tragen Sie in Ihrer `.env` (oder `.env.local`) die **OAuth-Werte** aus Azure ein. Wenn bereits E-Mail-Variablen (MAILER_DSN, MAILER_FROM, ADMIN_EMAIL, IMAP_* usw.) vorhanden sind, **diese nicht löschen** – nur den Microsoft-OAuth-Block ergänzen oder anpassen: ```env ###> Microsoft OAuth (Outlook Calendar Integration) ### MICROSOFT_CLIENT_ID= MICROSOFT_CLIENT_SECRET= MICROSOFT_TENANT_ID= MICROSOFT_REDIRECT_URI=https://IHRE-DOMAIN/PFAD/admin/outlook/callback ###< Microsoft OAuth ### ``` - **MICROSOFT_REDIRECT_URI** muss **genau** der in Azure eingetragenen Umleitungs-URI entsprechen (inkl. https, Domain und Pfad). - Bestehende E-Mail-Adressen (z. B. buchung@…, ADMIN_EMAIL, EVENT_CENTER_OUTLOOK_EMAIL) bleiben unverändert, sofern Sie nicht gezielt das Versand-/Kalender-Konto wechseln wollen. - Danach z. B. `php bin/console cache:clear` ausführen. --- ## 6. Outlook-Konto in der Anwendung verbinden 1. In der Anwendung als Admin anmelden. 2. **Admin** → **Outlook-Integration** (bzw. **Outlook-Kalender**) öffnen. 3. Auf **Mit Microsoft anmelden** / **Konto verbinden** klicken. 4. Mit dem gewünschten Microsoft-Konto (z. B. `buchung@ksb-dueren.de` oder `bewegungszentrum@ksb-dueren.de`) anmelden und Berechtigungen bestätigen. 5. Nach erfolgreicher Rückkehr ist das Konto verbunden und kann für Kalender-Sync genutzt werden. Optional können Sie **mehrere** Outlook-Konten verbinden. Welches Konto für das **Bewegungszentrum / Geburtstage** genutzt wird, steuern Sie mit der optionalen Umgebungsvariable `EVENT_CENTER_OUTLOOK_EMAIL` (siehe `OUTLOOK_EMAIL_SETUP.md` bzw. `ENV_TEMPLATE.txt`). --- ## 7. E-Mail (SMTP/IMAP) mit demselben Konto – App-Kennwort Wenn die Anwendung mit **demselben** Microsoft-Konto E-Mails senden oder empfangen soll (SMTP/IMAP), verlangt Microsoft 365 oft ein **App-Kennwort** statt des normalen Anmeldekennworts, sobald MFA aktiv ist. ### App-Kennwort erstellen (wenn MFA aktiv) 1. Der Benutzer meldet sich unter [account.microsoft.com/security](https://account.microsoft.com/security) an (oder über **Microsoft 365** → **Mein Konto** → **Sicherheit**). 2. **Zusätzliche Sicherheitsoptionen** / **Sicherheitsoptionen**. 3. **App-Kennwörter** → neues App-Kennwort erstellen (z. B. „Kursverwaltung SMTP“). 4. Das generierte Kennwort **einmalig** anzeigen und kopieren. ### In .env eintragen Nur anpassen, wenn dieses **konkrete** Konto auch für E-Mail-Versand/IMAP genutzt wird (also z. B. dasselbe wie in MAILER_DSN/IMAP_USERNAME): - **MAILER_DSN**: Im SMTP-Teil das Passwort durch das App-Kennwort ersetzen, z. B. `smtp://buchung@ksb-dueren.de:IHER_APP_KENNWORT@smtp-mail.outlook.com:587` - **IMAP_PASSWORD**: dasselbe App-Kennwort, falls Sie IMAP für dieses Konto nutzen. - Optional **SMTP_PASSWORD** (Legacy): dasselbe App-Kennwort. Wenn E-Mails bereits mit einem **anderen** Konto versendet werden und funktionieren, MAILER_DSN/IMAP_* **nicht** ändern. Ohne MFA kann bei manchen Tenants noch das normale Benutzerpasswort verwendet werden; bei Problemen oder Fehlermeldungen zu „Sicherheit“ auf App-Kennwort umstellen. --- ## 8. Checkliste - [ ] Microsoft-Konto vorhanden (neu angelegt oder bestehend) - [ ] App-Registrierung in Azure (Microsoft Entra ID) angelegt - [ ] Redirect URI in Azure = exakt die Callback-URL der App - [ ] API-Berechtigungen: User.Read, Calendars.ReadWrite, offline_access; Admin-Zustimmung erteilt - [ ] Client Secret erstellt und Wert notiert - [ ] .env: MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_ID, MICROSOFT_REDIRECT_URI gesetzt - [ ] Cache geleert (`php bin/console cache:clear`) - [ ] In der App unter Admin → Outlook-Integration Konto verbunden - [ ] Optional: EVENT_CENTER_OUTLOOK_EMAIL gesetzt, falls separates Konto für Bewegungszentrum - [ ] Optional: App-Kennwort für SMTP/IMAP erstellt und in MAILER_DSN/IMAP_PASSWORD eingetragen --- ## Fehlerbehebung - **„Redirect URI stimmt nicht überein“**: URI in Azure und in `MICROSOFT_REDIRECT_URI` Zeichen für Zeichen vergleichen (https, keine Slash am Ende, gleicher Pfad). - **„Berechtigung verweigert“ / Consent**: Admin-Zustimmung für die App unter API-Berechtigungen erteilen. - **Token abgelaufen**: In der App unter Outlook-Integration ggf. Konto erneut verbinden (Refresh-Token erneuern). - **SMTP/IMAP-Anmeldung schlägt fehl**: App-Kennwort statt Benutzerpasswort verwenden; sicherstellen, dass SMTP/IMAP für das Konto im Admin Center erlaubt ist. Weitere Details zur Nutzung mehrerer Konten und zu `EVENT_CENTER_OUTLOOK_EMAIL` finden Sie in **OUTLOOK_EMAIL_SETUP.md**.